diff options
Diffstat (limited to 'numpy/doc/numpybook/numpybook.lyx')
| -rw-r--r-- | numpy/doc/numpybook/numpybook.lyx | 27836 |
1 files changed, 0 insertions, 27836 deletions
diff --git a/numpy/doc/numpybook/numpybook.lyx b/numpy/doc/numpybook/numpybook.lyx deleted file mode 100644 index 16ee19d90..000000000 --- a/numpy/doc/numpybook/numpybook.lyx +++ /dev/null @@ -1,27836 +0,0 @@ -#LyX 1.5.1 created this file. For more info see http://www.lyx.org/ -\lyxformat 276 -\begin_document -\begin_header -\textclass mybook -\begin_preamble - - - -\usepackage{array} - -% This gives us a better font in URL links (otherwise the default -% MonoSpace font is bitmapped, and it looks horrible in PDF) -\usepackage{courier} - -\usepackage{fullpage} - -\usepackage{color} % so we can use red for the fixme warnings - -% The hyperref package gives us a pdf with properly built -% internal navigation ('pdf bookmarks' for the table of contents, -% internal cross-reference links, web links for URLs, etc.) - -% A few colors to replace the defaults for certain link types -\definecolor{darkorange}{rgb}{.71,0.21,0.01} -\definecolor{darkgreen}{rgb}{.12,.54,.11} - -\usepackage[ - %pdftex, % needed for pdflatex - breaklinks=true, % so long urls are correctly broken across lines - colorlinks=true, - urlcolor=blue, - linkcolor=darkorange, - citecolor=darkgreen, - ]{hyperref} - -% This helps prevent overly long lines that stretch beyond the margins -\sloppy - -% Define a \fixme command to mark visually things needing fixing in the draft. -% For final printing or to simply disable these bright warnings, simply -% uncomment the \renewcommand redefinition below - -\newcommand{\fixme}[1] { -\textcolor{red}{ -{\fbox{ {\bf FIX} -\ensuremath{\blacktriangleright \blacktriangleright \blacktriangleright}} -{\bf #1} -\fbox{\ensuremath{ \blacktriangleleft \blacktriangleleft \blacktriangleleft } -} } } -} -% Uncomment the next line to make the \fixme command be a no-op -%\renewcommand{\fixme}[1]{} - -%%% If you also want to use the listings package for nicely formatted -%%% Python source code, this configuration produces good on-paper and -%%% on-screen results: - -\definecolor{orange}{cmyk}{0,0.4,0.8,0.2} -% Use and configure listings package for nicely formatted code -\usepackage{listings} -\lstset{ - language=Python, - basicstyle=\small\ttfamily, - commentstyle=\ttfamily\color{blue}, - stringstyle=\ttfamily\color{orange}, - showstringspaces=false, - breaklines=true, - postbreak = \space\dots -} -\end_preamble -\language english -\inputencoding auto -\font_roman default -\font_sans default -\font_typewriter default -\font_default_family default -\font_sc false -\font_osf false -\font_sf_scale 100 -\font_tt_scale 100 -\graphics default -\paperfontsize 10 -\spacing onehalf -\papersize custom -\use_geometry true -\use_amsmath 2 -\use_esint 0 -\cite_engine basic -\use_bibtopic false -\paperorientation portrait -\paperwidth 7in -\paperheight 9in -\leftmargin 1in -\topmargin 1in -\rightmargin 1in -\bottommargin 1in -\secnumdepth 3 -\tocdepth 3 -\paragraph_separation indent -\defskip medskip -\quotes_language english -\papercolumns 1 -\papersides 1 -\paperpagestyle headings -\tracking_changes false -\output_changes false -\author "" -\author "" -\end_header - -\begin_body - -\begin_layout Standard -\begin_inset VSpace 2in* -\end_inset - - -\end_layout - -\begin_layout Standard -\align center - -\family sans -\series bold -\size giant -Guide to NumPy -\end_layout - -\begin_layout Standard -\align center - -\family sans -\size larger -Travis E. - Oliphant, PhD -\newline -August 21, 2008 -\end_layout - -\begin_layout Standard -\begin_inset VSpace vfill -\end_inset - -This book was released from a restricted distribution using a Market-Determined, - Temporary, Distribution-Restriction (MDTDR) system (see http://www.trelgol.com) - on August 21, 2008. - It is now released to the public domain and can be used as source material - for other works. - -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand tableofcontents - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset FloatList table - -\end_inset - - -\end_layout - -\begin_layout Part -NumPy from Python -\end_layout - -\begin_layout Chapter -Origins of NumPy -\end_layout - -\begin_layout Quotation -A complex system that works is invariably found to have evolved from a simple - system that worked -\end_layout - -\begin_layout Right Address ---- -\emph on -John Gall -\end_layout - -\begin_layout Quotation -Copy from one, it's plagiarism; copy from two, it's research. -\end_layout - -\begin_layout Right Address ---- -\emph on -Wilson Mizner -\end_layout - -\begin_layout Standard -NumPy builds on (and is a successor to) the successful Numeric array object. - Its goal is to create the corner-stone for a useful environment for scientific - computing. - In order to better understand the people surrounding NumPy and (its library-pac -kage) SciPy, I will explain a little about how SciPy and (current) NumPy - originated. - In 1998, as a graduate student studying biomedical imaging at the Mayo - Clinic in Rochester, MN, I came across Python and its numerical extension - (Numeric) while I was looking for ways to analyze large data sets for Magnetic - Resonance Imaging and Ultrasound using a high-level language. - I quickly fell in love with Python programming which is a remarkable statement - to make about a programming language. - If I had not seen others with the same view, I might have seriously doubted - my sanity. - I became rather involved in the Numeric Python community, adding the C-API - chapter to the Numeric documentation (for which Paul Dubois graciously - made me a co-author). - -\end_layout - -\begin_layout Standard -As I progressed with my thesis work, programming in Python was so enjoyable - that I felt inhibited when I worked with other programming frameworks. - As a result, when a task I needed to perform was not available in the core - language, or in the Numeric extension, I looked around and found C or Fortran - code that performed the needed task, wrapped it into Python (either by - hand or using SWIG), and used the new functionality in my programs. - -\end_layout - -\begin_layout Standard -Along the way, I learned a great deal about the underlying structure of - Numeric and grew to admire it's simple but elegant structures that grew - out of the mechanism by which Python allows itself to be extended. - -\end_layout - -\begin_layout Note -Numeric was originally written in 1995 based off of an earlier Matrix Object - design by Jim Fulton which was released in 1994. - Most of the code was written by Jim Hugunin while he was a graduate student - at MIT. - He received help from many people including Jim Fulton, David Ascher, Paul - Dubois, and Konrad Hinsen. - These individuals and many others added comments, criticisms, and code - which helped the Numeric extension reach stability. - Jim Hugunin did not stay long as an active member of the community --- - moving on to write Jython and, later, Iron Python. -\end_layout - -\begin_layout Standard -By operating in this need-it-make-it fashion I ended up with a substantial - library of extension modules that helped Python + Numeric become easier - to use in a scientific setting. - These early modules included raw input-output functions, a special function - library, an integration library, an ordinary differential equation solver, - some least-squares optimizers, and sparse matrix solvers. - While I was doing this laborious work, Pearu Peterson noticed that a lot - of the routines I was wrapping were written in Fortran, and there was no - simplified wrapping mechanism for Fortran subroutines (like SWIG for C). - He began the task of writing f2py which made it possible to easily wrap - Fortran programs into Python. - I helped him a little bit, mostly with testing and contributing early function- -call-back code, but he put forth the brunt of the work. - His result was simply amazing to me. - I've always been impressed with f2py, especially because I knew how much - effort writing and maintaining extension modules could be. - Anybody serious about scientific computing with Python will appreciate - that f2py is distributed along with NumPy. -\end_layout - -\begin_layout Standard -When I finished my Ph.D. - in 2001, Eric Jones (who had recently completed his Ph.D. - at Duke) contacted me because he had a collection of Python modules he - had developed as part of his thesis work as well. - He wanted to combine his modules with mine into one super package. - Together with Pearu Peterson we joined our efforts, and SciPy was born - in 2001. - Since then, many people have contributed module code to SciPy including - Ed Schofield, Robert Cimrman, David M. - Cooke, Charles (Chuck) Harris, Prabhu Ramachandran, Gary Strangman, Jean-Sebast -ien Roy, and Fernando Perez. - Others such as Travis Vaught, David Morrill, Jeff Whitaker, and Louis Luangkeso -rn have contributed testing and build support. - -\end_layout - -\begin_layout Standard -At the start of 2005, SciPy was at release 0.3 and relatively stable for - an early version number. - Part of the reason it was difficult to stabilize SciPy was that the array - object upon which SciPy builds was undergoing a bit of an upheaval. - At about the same time as SciPy was being built, some Numeric users were - hitting up against the limited capabilities of Numeric. - In particular, the ability to deal with memory mapped files (and associated - alignment and swapping issues), record arrays, and altered error checking - modes were important but limited or non-existent in Numeric. - As a result, numarray was created by Perry Greenfield, Todd Miller, and - Rick White at the Space Science Telescope Institute as a replacement for - Numeric. - Numarray used a very different implementation scheme as a mix of Python - classes and C code (which led to slow downs in certain common uses). - While improving some capabilities, it was slow to pick up on the more advanced - features of Numeric's universal functions (ufuncs) --- never re-creating - the C-API that SciPy depended on. - This made it difficult for SciPy to -\begin_inset Quotes eld -\end_inset - -convert -\begin_inset Quotes erd -\end_inset - - to numarray. - -\end_layout - -\begin_layout Standard -Many newcomers to scientific computing with Python were told that numarray - was the future and started developing for it. - Very useful tools were developed that could not be used with Numeric (because - of numarray's change in C-API), and therefore could not be used easily - in SciPy. - This state of affairs was very discouraging for me personally as it left - the community fragmented. - Some developed for numarray, others developed as part of SciPy. - A few people even rejected adopting Python for scientific computing entirely - because of the split. - In addition, I estimate that quite a few Python users simply stayed away - from both SciPy and numarray, leaving the community smaller than it could - have been given the number of people that use Python for science and engineerin -g purposes. - -\end_layout - -\begin_layout Standard -It should be recognized that the split was not intentional, but simply an - outgrowth of the different and exacting demands of scientific computing - users. - My describing these events should not be construed as assigning blame to - anyone. - I very much admire and appreciate everyone I've met who is involved with - scientific computing and Python. - Using a stretched biological metaphor, it is only through the process of - dividing and merging that better results are born. - I think this concept applies to NumPy. -\end_layout - -\begin_layout Standard -In early 2005, I decided to begin an effort to help bring the diverging - community together under a common framework if it were possible. - I first looked at numarray to see what could be done to add the missing - features to make SciPy work with it as a core array object. - After a couple of days of studying numarray, I was not enthusiastic about - this approach. - My familiarity with the Numeric code base no doubt biased my opinion, but - it seemed to me that the features of Numarray could be added back to Numeric - with a few fundamental changes to the core object. - This would make the transition of SciPy to a more enhanced array object - much easier in my mind. - -\end_layout - -\begin_layout Standard -Therefore, I began to construct this hybrid array object complete with an - enhanced set of universal (broadcasting) functions that could deal with - it. - Along the way, quite a few new features and significant enhancements were - added to the array object and its surrounding infrastructure. - This book describes the result of that year-and-a-half-long effort which - culminated with the release of NumPy 0.9.2 in early 2006 and NumPy 1.0 in - late 2006. - I first named the new package, SciPy Core, and used the scipy namespace. - However, after a few months of testing under that name, it became clear - that a separate namespace was needed for the new package. - As a result, a rapid search for a new name resulted in actually coming - back to the NumPy name which was the unofficial name of Numerical Python - but never the actual namespace. - Because the new package builds on the code-base of and is a successor to - Numeric, I think the NumPy name is fitting and hopefully not too confusing - to new users. -\end_layout - -\begin_layout Standard -This book only briefly outlines some of the infrastructure that surrounds - the basic objects in NumPy to provide the additional functionality contained - in the older Numeric package ( -\emph on -i.e. - -\emph default - LinearAlgebra, RandomArray, FFT). - This infrastructure in NumPy includes basic linear algebra routines, Fourier - transform capabilities, and random number generators. - In addition, the f2py module is described in its own documentation, and - so is only briefly mentioned in the second part of the book. - There are also extensions to the standard Python distutils and testing - frameworks included with NumPy that are useful in constructing your own - packages built on top of NumPy. - The central purpose of this book, however, is to describe and document - the basic NumPy system that is available under the numpy namespace. -\end_layout - -\begin_layout Note -The numpy namespace includes all names under the numpy.core and numpy.lib - namespaces as well. - Thus, -\family typewriter -import numpy -\family default - will also import the names from numpy.core and numpy.lib. - This is the recommended way to use numpy. -\end_layout - -\begin_layout Standard -The following table gives a brief outline of the sub-packages contained - in numpy package. -\end_layout - -\begin_layout Standard -\align center -\begin_inset Tabular -<lyxtabular version="3" rows="9" columns="3"> -<features> -<column alignment="center" valignment="top" leftline="true" width="1in"> -<column alignment="center" valignment="top" leftline="true" width="2in"> -<column alignment="center" valignment="top" leftline="true" rightline="true" width="2in"> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Package -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Purpose -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Comments -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -core -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -basic objects -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -all names exported to numpy -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -lib -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -additional utilities -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -all names exported to numpy -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -linalg -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -basic linear algebra -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -old LinearAlgebra from Numeric -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -fft -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -discrete Fourier transforms -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -old FFT from Numeric -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -random -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -random number generators -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -old RandomArray from Numeric -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -distutils -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -enhanced build and distribution -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -improvements built on standard distutils -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -testing -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -unit-testing -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -utility functions useful for testing -\end_layout - -\end_inset -</cell> -</row> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -f2py -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -automatic wrapping of Fortran code -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -a useful utility needed by SciPy -\end_layout - -\end_inset -</cell> -</row> -</lyxtabular> - -\end_inset - - -\end_layout - -\begin_layout Chapter -Object Essentials -\end_layout - -\begin_layout Quotation -Our programs last longer if we manage to build simple abstractions for ourselves... -\end_layout - -\begin_layout Right Address ---- -\emph on -Ron Jeffries -\end_layout - -\begin_layout Quotation -I will tell you the truth as soon as I figure it out. -\end_layout - -\begin_layout Right Address ---- -\emph on -Wayne Birmingham -\end_layout - -\begin_layout Standard -NumPy provides two fundamental objects: an N-dimensional array object ( -\family typewriter -ndarray -\family default -) and a universal function object ( -\family typewriter -ufunc -\family default -). - In addition, there are other objects that build on top of these which you - may find useful in your work, and these will be discussed later. - The current chapter will provide background information on just the -\family typewriter -ndarray -\family default - and the -\family typewriter -ufunc -\family default - that will be important for understanding the attributes and methods to - be discussed later. - -\end_layout - -\begin_layout Standard -An N-dimensional array is a homogeneous collection of -\begin_inset Quotes eld -\end_inset - -items -\begin_inset Quotes erd -\end_inset - - indexed using -\begin_inset Formula $N$ -\end_inset - - integers. - There are two essential pieces of information that define an -\begin_inset Formula $N$ -\end_inset - --dimensional array: 1) the shape of the array, and 2) the kind of item the - array is composed of. - The shape of the array is a tuple of -\begin_inset Formula $N$ -\end_inset - - integers (one for each dimension) that provides information on how far - the index can vary along that dimension. - The other important information describing an array is the kind of item - the array is composed of. - Because every -\family typewriter -ndarray -\family default - is a homogeneous collection of exactly the same data-type, every item takes - up the same size block of memory, and each block of memory in the array - is interpreted in exactly the same way -\begin_inset Foot -status open - -\begin_layout Standard -By using OBJECT arrays, one can effectively have heterogeneous arrays, but - the system still sees each element of the array as exactly the same thing - (a reference to a Python object). -\end_layout - -\end_inset - -. -\end_layout - -\begin_layout Tip -All arrays in NumPy are indexed starting at 0 and ending at M-1 following - the Python convention. -\end_layout - -\begin_layout Standard -For example, consider the following piece of code: -\end_layout - -\begin_layout MyCode ->>> a = array([[1,2,3],[4,5,6]]) -\newline ->>> a.shape -\newline -(2, 3) -\newline ->>> a.dtype -\newline -dtype('int32') -\end_layout - -\begin_layout Note -for all code in this book it is assumed that you have first entered -\family typewriter -from numpy import * -\family default -. - In addition, any previously defined arrays are still defined for subsequent - examples. -\end_layout - -\begin_layout Standard -This code defines an array of size -\begin_inset Formula $2\times3$ -\end_inset - - composed of 4-byte (little-endian) integer elements (on my 32-bit platform). - We can index into this two-dimensional array using two integers: the first - integer running from 0 to 1 inclusive and the second from 0 to 2 inclusive. - For example, index -\begin_inset Formula $\left(1,1\right)$ -\end_inset - - selects the element with value 5: -\end_layout - -\begin_layout MyCode ->>> a[1,1] -\newline -5 -\end_layout - -\begin_layout Standard -All code shown in the shaded-boxes in this book has been (automatically) - executed on a particular version of NumPy. - The output of the code shown below shows which version of NumPy was used - to create all of the output in your copy of this book. -\end_layout - -\begin_layout MyCode ->>> import numpy; print numpy.__version__ -\newline -1.0.2.dev3478 -\end_layout - -\begin_layout Section -Data-Type Descriptors -\end_layout - -\begin_layout Standard -In NumPy, an ndarray is an -\begin_inset Formula $N$ -\end_inset - --dimensional array of items where each item takes up a fixed number of bytes. - Typically, this fixed number of bytes represents a number ( -\emph on -e.g. - -\emph default - integer or floating-point). - However, this fixed number of bytes could also represent an arbitrary record - made up of any collection of other data types. - NumPy achieves this flexibility through the use of a data-type (dtype) - object. - Every array has an associated dtype object which describes the layout of - the array data. - Every dtype -\begin_inset LatexCommand index -name "dtype" - -\end_inset - - object, in turn, has an associated Python type-object that determines exactly - what type of Python object is returned when an element of the array is - accessed. - The dtype objects are flexible enough to contain references to arrays of - other dtype objects and, therefore, can be used to define nested records. - This advanced functionality will be described in better detail later as - it is mainly useful for the recarray (record array) subclass that will - also be defined later. - However, all ndarrays can enjoy the flexibility provided by the dtype objects. - Figure -\begin_inset LatexCommand ref -reference "cap:Conceptual-diagram-showing" - -\end_inset - - provides a conceptual diagram showing the relationship between the ndarray, - its associated data-type object, and an array-scalar that is returned when - a single-element of the array is accessed. - Note that the data-type points to the type-object of the array scalar -\begin_inset LatexCommand index -name "array scalars" - -\end_inset - -. - An array scalar is returned using the type-object and a particular element - of the ndarray. -\end_layout - -\begin_layout Standard -\begin_inset Float figure -wide false -sideways false -status open - -\begin_layout Standard -\align center -\begin_inset Graphics - filename Figures/threefundamental.eps - width 90text% - keepAspectRatio - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset Caption - -\begin_layout Standard -\begin_inset LatexCommand label -name "cap:Conceptual-diagram-showing" - -\end_inset - -Conceptual diagram showing the relationship between the three fundamental - objects used to describe the data in an array: 1) the ndarray itself, 2) - the data-type object that describes the layout of a single fixed-size element - of the array, 3) the array-scalar Python object that is returned when a - single element of the array is accessed. -\end_layout - -\end_inset - - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -Every dtype object is based on one of 21 built-in dtype objects. - These built-in objects allow numeric operations on a wide-variety of integer, - floating-point, and complex data types. - Associated with each data-type is a Python type object whose instances - are array scalars. - This type-object can be obtained using the -\family typewriter -type -\family default - attribute of the dtype object. - Python typically defines only one data-type of a particular data class - (one integer type, one floating-point type, etc.). - This can be convenient for some applications that don't need to be concerned - with all the ways data can be represented in a computer. - For scientific applications, however, this is not always true. - As a result, in NumPy, their are 21 different fundamental Python data-type-desc -riptor objects built-in. - These descriptors are mostly based on the types available in the C language - that CPython is written in. - However, there are a few types that are extremely flexible, such as -\family typewriter -str_ -\family default -, -\family typewriter -unicode_ -\family default -, and -\family typewriter -void -\family default -. -\end_layout - -\begin_layout Standard -The fundamental data-types are shown in Table -\begin_inset LatexCommand ref -reference "cap:Fundamental-Data-Types" - -\end_inset - -. - Along with their (mostly) C-derived names, the integer, float, and complex - data-types are also available using a bit-width convention so that an array - of the right size can always be ensured ( -\emph on -e.g. - -\emph default - int8, float64, complex128). - The C-like names are also accessible using a character code which is also - shown in the table (use of the character codes, however, is discouraged). - Names for the data types that would clash with standard Python object names - are followed by a trailing underscore, '_'. - These data types are so named because they use the same underlying precision - as the corresponding Python data types. - Most scientific users should be able to use the array-enhanced scalar objects - in place of the Python objects. - The array-enhanced scalars inherit from the Python objects they can replace - and should act like them under all circumstances (except for how errors - are handled in math computations). - -\end_layout - -\begin_layout Tip -The array types -\series bold -bool -\series default -_, -\series bold -int -\series default -_, -\series bold -complex -\series default -_, -\series bold -float -\series default -_, -\series bold -object -\series default -_, -\series bold -unicode -\series default -_, and -\series bold -str_ -\series default - are enhanced-scalars. - They are very similar to the standard Python types (without the trailing - underscore) and inherit from them (except for bool_ and object_). - They can be used in place of the standard Python types whenever desired. - Whenever a data type is required, as an argument, the standard Python types - are recognized as well. -\end_layout - -\begin_layout Standard -Three of the data types are flexible in that they can have items that are - of an arbitrary size: the -\family typewriter -str_ -\family default - type, the -\family typewriter -unicode_ -\family default - type, and the -\family typewriter -void -\family default - type. - While, you can specify an arbitrary size for these types, every item in - an array is still of that specified size. - The void type, for example, allows for arbitrary records to be defined - as elements of the array, and can be used to define exotic types built - on top of the basic -\family typewriter -ndarray -\family default -. -\end_layout - -\begin_layout Standard -\begin_inset Float table -wide false -sideways false -status open - -\begin_layout Standard -\begin_inset Caption - -\begin_layout Standard -\begin_inset LatexCommand label -name "cap:Fundamental-Data-Types" - -\end_inset - -Built-in array-scalar types corresponding to data-types for an ndarray. - The bold-face types correspond to standard Python types. - The object_ type is special because arrays with dtype='O' do not return - an array scalar on item access but instead return the actual object referenced - in the array. -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\align center -\begin_inset Tabular -<lyxtabular version="3" rows="24" columns="3"> -<features> -<column alignment="center" valignment="top" leftline="true" width="0"> -<column alignment="center" valignment="top" leftline="true" width="0"> -<column alignment="center" valignment="top" leftline="true" rightline="true" width="0"> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Type -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Bit-Width -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Character -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -bool_ -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -boolXX -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'?' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -byte -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -intXX -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'b' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -short -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'h' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -intc -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'i' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -int_ -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'l' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -longlong -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'q' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -intp -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'p' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -ubyte -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -uintXX -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'B' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -ushort -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'H' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -uintc -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'I' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -uint -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'L' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -ulonglong -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'Q' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -uintp -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'P' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -single -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -floatXX -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'f' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -float_ -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'d' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -longfloat -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'g' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -csingle -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -complexXX -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'F' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -complex_ -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'D' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -clongfloat -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'G' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -object_ -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'O' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -str_ -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'S#' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -unicode_ -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'U#' -\end_layout - -\end_inset -</cell> -</row> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -void -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family typewriter -'V#' -\end_layout - -\end_inset -</cell> -</row> -</lyxtabular> - -\end_inset - - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Note -The two types -\family typewriter -intp -\family default - and -\family typewriter -uintp -\family default - are not separate types. - They are names bound to a specific integer type just large enough to hold - a memory address (a pointer) on the platform. -\end_layout - -\begin_layout Warning -Numeric Compatibility: If you used old typecode characters in your Numeric - code (which was never recommended), you will need to change some of them - to the new characters. - In particular, the needed changes are 'c->'S1', 'b'->'B', '1'->'b', 's'->'h', - 'w'->'H', and 'u'->'I'. - These changes make the typecharacter convention more consistent with other - Python modules such as the struct module. -\end_layout - -\begin_layout Standard -The fundamental data-types are arranged into a hierarchy of Python type-objects - shown in Figure -\begin_inset LatexCommand ref -reference "cap:Hierarchy-of-type" - -\end_inset - -. - Each of the leaves on this hierarchy correspond to actual data-types that - arrays can have (in other words, there is a built in dtype object associated - with each of these new types). - They also correspond to new Python objects that can be created. - These new objects are -\begin_inset Quotes eld -\end_inset - -scalar -\begin_inset Quotes erd -\end_inset - - types corresponding to each fundamental data-type. - Their purpose is to smooth out the rough edges that result when mixing - scalar and array operations. - These scalar objects will be discussed in more detail in Chapter -\begin_inset LatexCommand ref -reference "cha:Scalar-objects" - -\end_inset - -. - The other types in the hierarchy define particular categories of types. - These categories can be useful for testing whether or not the object returned - by -\family typewriter -self.dtype.type -\family default - is of a particular class (using -\family typewriter -issubclass -\family default -). -\end_layout - -\begin_layout Standard -\begin_inset Float figure -wide false -sideways false -status open - -\begin_layout Standard -\align center -\begin_inset Graphics - filename Figures/hierarchy.eps - lyxscale 75 - width 95text% - keepAspectRatio - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset Caption - -\begin_layout Standard -\begin_inset LatexCommand label -name "cap:Hierarchy-of-type" - -\end_inset - -Hierarchy of type objects representing the array data types. - Not shown are the two integer types -\family typewriter -intp -\family default - and -\family typewriter -uintp -\family default - which just point to the integer type that holds a pointer for the platform. - All the number types can be obtained using bit-width names as well. -\end_layout - -\end_inset - - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Section -Basic indexing (slicing) -\end_layout - -\begin_layout Standard -Indexing -\begin_inset LatexCommand index -name "indexing" - -\end_inset - - is a powerful tool in Python and NumPy takes full advantage of this power. - In fact, some of capabilities of Python's indexing were first established - by the needs of Numeric users. -\begin_inset Foot -status open - -\begin_layout Standard -For example, the ability to index with a comma separated list of objects - and have it correspond to indexing with a tuple is a feature added to Python - at the request of the NumPy community. - The Ellipsis object was also added to Python explicitly for the NumPy community. - Extended slicing (wherein a step can be provided) was also a feature added - to Python because of Numeric. -\end_layout - -\end_inset - - Indexing is also sometimes called slicing in Python, and slicing for an - -\family typewriter -ndarray -\family default - works very similarly as it does for other Python sequences. - There are three big differences: 1) slicing can be done over multiple dimension -s, 2) exactly one ellipsis object can be used to indicate several dimensions - at once, 3) slicing cannot be used to expand the size of an array (unlike - lists). -\end_layout - -\begin_layout Standard -A few examples should make slicing more clear. - Suppose -\begin_inset Formula $A$ -\end_inset - - is a -\begin_inset Formula $10\times20$ -\end_inset - - array, then -\begin_inset Formula $A[3]$ -\end_inset - - is the same as -\begin_inset Formula $A[3,:]$ -\end_inset - - and represents the 4th length-20 -\begin_inset Quotes eld -\end_inset - -row -\begin_inset Quotes erd -\end_inset - - of the array. - On the other hand, -\begin_inset Formula $A[:,3]$ -\end_inset - - represents the 4th length-10 -\begin_inset Quotes eld -\end_inset - -column -\begin_inset Quotes erd -\end_inset - - of the array. - Every third element of the 4th column can be selected as -\begin_inset Formula $A[::3,3]$ -\end_inset - -. - Ellipses can be used to replace zero or more -\begin_inset Quotes eld -\end_inset - -: -\begin_inset Quotes erd -\end_inset - - terms. - In other words, an Ellipsis -\begin_inset LatexCommand index -name "Ellipsis" - -\end_inset - - object expands to zero or more full slice objects ( -\begin_inset Quotes eld -\end_inset - -: -\begin_inset Quotes erd -\end_inset - -) so that the total number of dimensions in the slicing tuple matches the - number of dimensions in the array. - Thus, if -\begin_inset Formula $A$ -\end_inset - - is -\begin_inset Formula $10\times20\times30\times40$ -\end_inset - -, then -\begin_inset Formula $A[3:,...,4]$ -\end_inset - - is equivalent to -\begin_inset Formula $A[3:,:,:,4]$ -\end_inset - - while -\begin_inset Formula $A[...,3]$ -\end_inset - - is equivalent to -\begin_inset Formula $A[:,:,:,3].$ -\end_inset - - -\end_layout - -\begin_layout Standard -The following code illustrates some of these concepts: -\end_layout - -\begin_layout MyCode ->>> a = arange(60).reshape(3,4,5); print a -\newline -[[[ 0 1 2 3 4] -\newline - [ 5 6 7 - 8 9] -\newline - [10 11 12 13 14] -\newline - [15 16 17 18 19]] -\newline - -\newline - [[20 21 22 23 24] -\newline - [25 26 27 - 28 29] -\newline - [30 31 32 33 34] -\newline - [35 36 37 38 39]] -\newline - -\newline - [[40 41 42 43 44] -\newline - [45 46 47 - 48 49] -\newline - [50 51 52 53 54] -\newline - [55 56 57 58 59]]] -\end_layout - -\begin_layout Standard -\InsetSpace ~ - -\end_layout - -\begin_layout MyCode ->>> print a[...,3] -\newline -[[ 3 8 13 18] -\newline - [23 28 33 38] -\newline - [43 48 53 58]] -\newline ->>> print a[1,...,3] -\newline -[23 - 28 33 38] -\newline ->>> print a[:,:,2] -\newline -[[ 2 7 12 17] -\newline - [22 27 32 37] -\newline - [42 47 52 57]] -\newline ->>> - print a[0,::2,::2] -\newline -[[ 0 2 4] -\newline - [10 12 14]] -\end_layout - -\begin_layout Section -Memory Layout of -\family typewriter -ndarray -\end_layout - -\begin_layout Standard -On a fundamental level, an -\begin_inset Formula $N$ -\end_inset - --dimensional array object is just a one-dimensional sequence of memory with - fancy indexing code that maps an -\begin_inset Formula $N$ -\end_inset - --dimensional index into a one-dimensional index. - The one-dimensional index is necessary on some level because that is how - memory is addressed in a computer. - The fancy indexing, however, can be very helpful for translating our ideas - into computer code. - This is because many concepts we wish to model on a computer have a natural - representation as an -\begin_inset Formula $N$ -\end_inset - --dimensional array. - While this is especially true in science and engineering, it is also applicable - to many other arenas which can be appreciated by considering the popularity - of the spreadsheet as well as -\begin_inset Quotes eld -\end_inset - -image processing -\begin_inset Quotes erd -\end_inset - - applications. -\end_layout - -\begin_layout Warning -Some high-level languages give pre-eminence to a particular use of 2-dimensional - arrays as Matrices. - In NumPy, however, the core object is the more general -\begin_inset Formula $N$ -\end_inset - --dimensional array. - NumPy defines a matrix object as a sub-class of the N-dimensional array. - -\end_layout - -\begin_layout Standard -In order to more fully understand the array object along with its attributes - and methods it is important to learn more about how an -\begin_inset Formula $N$ -\end_inset - --dimensional array is represented in the computer's memory. - A complete understanding of this layout is only essential for optimizing - algorithms operating on general purpose arrays. - But, even for the casual user, a general understanding of memory layout - will help to explain the use of certain array attributes that may otherwise - be mysterious. - -\end_layout - -\begin_layout Subsection -Contiguous Memory Layout -\end_layout - -\begin_layout Standard -There is a fundamental ambiguity in how the mapping to a one-dimensional - index can take place which is illustrated for a 2-dimensional array in - Figure -\begin_inset LatexCommand ref -reference "cap:Options-for-memory" - -\end_inset - -. - In that figure, each block represents a chunk of memory that is needed - for representing the underlying array element. - For example, each block could represent the 8 bytes needed to represent - a double-precision floating point number. - -\end_layout - -\begin_layout Standard -In the figure, two arrays are shown, a -\begin_inset Formula $4x3$ -\end_inset - - array and a -\begin_inset Formula $3x4$ -\end_inset - - array. - Each of these arrays takes 12 blocks of memory shown as a single, contiguous - segment. - How this memory is used to form the abstract 2-dimensional array can vary, - however, and the -\family typewriter -ndarray -\family default - object supports both styles. - Which style is in use can be interrogated by the use of the flags attribute - which returns a dictionary of the state of array flags. - -\end_layout - -\begin_layout Standard -\begin_inset Float figure -wide false -sideways false -status open - -\begin_layout Standard -\align center -\begin_inset Graphics - filename Figures/contiguous.eps - width 85text% - keepAspectRatio - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset Caption - -\begin_layout Standard -\begin_inset LatexCommand label -name "cap:Options-for-memory" - -\end_inset - -Options for memory layout of a 2-dimensional array. -\end_layout - -\end_inset - - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -In the C-style of -\begin_inset Formula $N$ -\end_inset - --dimensional indexing shown on the left of Figure -\begin_inset LatexCommand ref -reference "cap:Options-for-memory" - -\end_inset - - the last -\begin_inset Formula $N$ -\end_inset - --dimensional index -\begin_inset Quotes eld -\end_inset - -varies the fastest. -\begin_inset Quotes erd -\end_inset - - In other words, to move through computer memory sequentially, the last - index is incremented first, followed by the second-to-last index and so - forth. - Some of the algorithms in NumPy that deal with -\begin_inset Formula $N$ -\end_inset - --dimensional arrays work best with this kind of data. - -\end_layout - -\begin_layout Standard -In the Fortran-style of -\begin_inset Formula $N$ -\end_inset - --dimensional indexing shown on the right of Figure -\begin_inset LatexCommand ref -reference "cap:Options-for-memory" - -\end_inset - -, the first -\begin_inset Formula $N$ -\end_inset - --dimensional index -\begin_inset Quotes eld -\end_inset - -varies the fastest. -\begin_inset Quotes erd -\end_inset - - Thus, to move through computer memory sequentially, the first index is - incremented first until it reaches the limit in that dimension, then the - second index is incremented and the first index is reset to zero. - While NumPy can be compiled without the use of a Fortran compiler, several - modules of SciPy (available separately) rely on underlying algorithms written - in Fortran. - Algorithms that work on -\begin_inset Formula $N$ -\end_inset - --dimensional arrays that are written in Fortran typically expect Fortran-style - arrays. - -\end_layout - -\begin_layout Standard -The two-styles of memory layout for arrays are connected through the transpose - operation. - Thus, if -\begin_inset Formula $A$ -\end_inset - - is a (contiguous) C-style array, then the same block of memory can be used - to represent -\begin_inset Formula $A^{T}$ -\end_inset - - as a (contiguous) Fortran-style array. - This kind of understanding can be useful when trying to optimize the wrapping - of Fortran subroutines, or if a more detailed understanding of how to write - algorithms for generally-indexed arrays is desired. - But, fortunately, the casual user who does not care if an array is copied - occasionally to get it into the right orientation needed for a particular - algorithm can forget about how the array is stored in memory and just visualize - it as an -\begin_inset Formula $N$ -\end_inset - --dimensional array (that is, after all, the whole point of creating the - -\family typewriter -ndarray -\family default - object in the first place). - -\end_layout - -\begin_layout Subsection -Non-contiguous memory layout -\end_layout - -\begin_layout Standard -Both of the examples presented above are -\emph on -single-segment -\begin_inset LatexCommand index -name "single-segment" - -\end_inset - - -\emph default - arrays where the entire array is visited by sequentially marching through - memory one element at a time. - When an algorithm in C or Fortran expects an N-dimensional array, this - single segment (of a certain fundamental type) is usually what is expected - along with the shape -\begin_inset Formula $N$ -\end_inset - --tuple. - With a single-segment of memory representing the array, the one-dimensional - index into computer memory can always be computed from the -\begin_inset Formula $N$ -\end_inset - --dimensional index. - This concept is explored further in the following paragraphs. -\end_layout - -\begin_layout Standard -Let -\begin_inset Formula $n_{i}$ -\end_inset - - be the value of the -\begin_inset Formula $i^{\textrm{th}}$ -\end_inset - - index into an array whose shape is represented by the -\begin_inset Formula $N$ -\end_inset - - integers -\begin_inset Formula $d_{i}$ -\end_inset - - ( -\begin_inset Formula $i=0\ldots N-1).$ -\end_inset - - Then, the one-dimensional index into a C-style contiguous array is -\begin_inset Formula \[ -n^{C}=\sum_{i=0}^{N-1}n_{i}\prod_{j=i+1}^{N-1}d_{j}\] - -\end_inset - - while the one-dimensional index into a Fortran-style contiguous array is - -\begin_inset Formula \[ -n^{F}=\sum_{i=0}^{N-1}n_{i}\prod_{j=0}^{i-1}d_{j}.\] - -\end_inset - - In these formulas we are assuming that -\begin_inset Formula \[ -\prod_{j=k}^{m}d_{j}=d_{k}d_{k+1}\cdots d_{m-1}d_{m}\] - -\end_inset - -so that if -\begin_inset Formula $m<k,$ -\end_inset - - the product is -\begin_inset Formula $1.$ -\end_inset - - While perfectly general, these formulas may be a bit confusing at first - glimpse. - Let's see how they expand out for determining the one-dimensional index - corresponding to the element -\begin_inset Formula $\left(1,3,2\right)$ -\end_inset - - of a -\begin_inset Formula $4\times5\times6$ -\end_inset - - array. - If the array is stored as Fortran contiguous, then -\begin_inset Formula \begin{eqnarray*} -n^{F} & = & n_{0}\cdot\left(1\right)+n_{1}\cdot(4)+n_{2}\cdot\left(4\cdot5\right)\\ - & = & 1+3\cdot4+2\cdot20=53.\end{eqnarray*} - -\end_inset - - On the other hand, if the array is stored as C contiguous, then -\begin_inset Formula \begin{eqnarray*} -n^{C} & = & n_{0}\cdot\left(5\cdot6\right)+n_{1}\cdot\left(6\right)+n_{2}\cdot\left(1\right)\\ - & = & 1\cdot30+3\cdot6+2\cdot1=50.\end{eqnarray*} - -\end_inset - - The general pattern should be more clear from these examples. - -\end_layout - -\begin_layout Standard -The formulas for the one-dimensional index of the N-dimensional arrays reveal - what results in an important generalization for memory layout. - Notice that each formula can be written as -\begin_inset Formula \[ -n^{X}=\sum_{i=0}^{N-1}n_{i}s_{i}^{X}\] - -\end_inset - - where -\begin_inset Formula $s_{i}^{X}$ -\end_inset - - gives the -\emph on -stride -\begin_inset LatexCommand index -name "stride" - -\end_inset - - -\emph default - for dimension -\begin_inset Formula $i$ -\end_inset - -. -\begin_inset Foot -status open - -\begin_layout Standard -Our definition of stride here is an element-based stride, while the strides - attribute returns a byte-based stride. - The byte-based stride is the element itemsize multiplied by the element-based - stride. -\end_layout - -\end_inset - - Thus, for C and Fortran contiguous arrays respectively we have -\begin_inset Formula \begin{eqnarray*} -s_{i}^{C} & = & \prod_{j=i+1}^{N-1}d_{j}=d_{i+1}d_{i+2}\cdots d_{N-1},\\ -s_{i}^{F} & = & \prod_{j=0}^{i-1}d_{j}=d_{0}d_{1}\cdots d_{i-1}.\end{eqnarray*} - -\end_inset - - -\end_layout - -\begin_layout Standard -The stride is how many elements in the underlying one-dimensional layout - of the array one must jump in order to get to the next array element of - a specific dimension in the N-dimensional layout. - Thus, in a C-style -\begin_inset Formula $4\times5\times6$ -\end_inset - - array one must jump over 30 elements to increment the first index by one, - so 30 is the stride for the first dimension ( -\begin_inset Formula $s_{0}^{C}=30$ -\end_inset - -). - If, for each array, we define a strides tuple with -\begin_inset Formula $N$ -\end_inset - - integers, then we have pre-computed and stored an important piece of how - to map the -\begin_inset Formula $N$ -\end_inset - --dimensional index to the one-dimensional one used by the computer. - -\end_layout - -\begin_layout Standard -In addition to providing a pre-computed table for index mapping, by allowing - the strides tuple to consist of arbitrary integers we have provided a more - general layout for the -\begin_inset Formula $N$ -\end_inset - --dimensional array. - As long as we always use the stride information to move around in the -\begin_inset Formula $N$ -\end_inset - --dimensional array, we can use any convenient layout we wish for the underlying - representation as long as it is regular enough to be defined by constant - jumps in each dimension. - The -\family typewriter -ndarray -\family default - object of NumPy uses this stride information and therefore the underlying - memory of an -\family typewriter -ndarray -\family default - can be laid out dis-contiguously. - -\end_layout - -\begin_layout Note -Several algorithms in NumPy work on arbitrarily strided arrays. - However, some algorithms require single-segment arrays. - When an irregularly strided array is passed in to such algorithms, a copy - is automatically made. - -\end_layout - -\begin_layout Standard -An important situation where irregularly strided arrays occur is array indexing. - Consider again Figure -\begin_inset LatexCommand ref -reference "cap:Options-for-memory" - -\end_inset - -. - In that figure a high-lighted sub-array is shown. - Define -\begin_inset Formula $C$ -\end_inset - - to be the -\begin_inset Formula $4\times3$ -\end_inset - - C contiguous array and -\begin_inset Formula $F$ -\end_inset - - to be the -\begin_inset Formula $3\times4$ -\end_inset - - Fortran contiguous array. - The highlighted areas can be written respectively as -\begin_inset Formula $C$ -\end_inset - -[1:3,1:3] and -\begin_inset Formula $F$ -\end_inset - -[1:3,1:3]. - As evidenced by the corresponding highlighted region in the one-dimensional - view of the memory, these sub-arrays are neither C contiguous nor Fortran - contiguous. - However, they can still be represented by an -\family typewriter -ndarray -\family default - object using the same striding tuple as the original array used. - Therefore, a regular indexing expression on an -\family typewriter -ndarray -\family default - can always produce an -\family typewriter -ndarray -\family default - object -\emph on -without -\emph default - copying any data. - This is sometimes referred to as the -\begin_inset Quotes eld -\end_inset - -view -\begin_inset Quotes erd -\end_inset - - feature of array indexing, and one can see that it is enabled by the use - of striding information in the underlying -\family typewriter -ndarray -\family default - object. - The greatest benefit of this feature is that it allows indexing to be done - very rapidly and without exploding memory usage (because no copies of the - data are made). -\end_layout - -\begin_layout Section -Universal Functions for arrays -\end_layout - -\begin_layout Standard -NumPy provides a wealth of mathematical functions that operate on then ndarray - object. - From algebraic functions such as addition and multiplication to trigonometric - functions such as -\begin_inset Formula $\sin,$ -\end_inset - - and -\begin_inset Formula $\cos$ -\end_inset - -. - Each universal function -\begin_inset LatexCommand index -name "universal function" - -\end_inset - - ( -\family typewriter -ufunc -\family default - -\begin_inset LatexCommand index -name "ufunc" - -\end_inset - -) is an instance of a general class so that function behavior is the same. - All ufuncs perform element-by-element operations over an array or a set - of arrays (for multi-input functions). - The ufuncs themselves and their methods are documented in Part -\begin_inset LatexCommand ref -reference "par:The-Ufunc-Object" - -\end_inset - -. - -\end_layout - -\begin_layout Standard -One important aspect of ufunc behavior that should be introduced early, - however, is the idea of -\emph on - -\begin_inset LatexCommand index -name "broadcasting" - -\end_inset - -broadcasting -\emph default -. - Broadcasting is used in several places throughout NumPy and is therefore - worth early exposure. - To understand the idea of broadcasting, you first have to be conscious - of the fact that all ufuncs are always element-by-element operations. - In other words, suppose we have a ufunc with two inputs and one output - ( -\emph on -e.g. - -\emph default - addition) and the inputs are both arrays of shape -\begin_inset Formula $4\times6\times5$ -\end_inset - -. - Then, the output is going to be -\begin_inset Formula $4\times6\times5$ -\end_inset - -, and will be the result of applying the underlying function ( -\emph on -e.g. - -\emph default - -\begin_inset Formula $+$ -\end_inset - -) to each pair of inputs to produce the output at the corresponding -\begin_inset Formula $N$ -\end_inset - --dimensional location. - -\end_layout - -\begin_layout Standard -Broadcasting allows ufuncs to deal in a meaningful way with inputs that - do not have exactly the same shape. - In particular, the first rule of broadcasting is that if all input arrays - do not have the same number of dimensions, then a -\begin_inset Quotes eld -\end_inset - - -\begin_inset Formula $1$ -\end_inset - - -\begin_inset Quotes erd -\end_inset - - will be repeatedly pre-pended to the shapes of the smaller arrays until - all the arrays have the same number of dimensions. - The second rule of broadcasting ensures that arrays with a size of 1 along - a particular dimension act as if they had the size of the array with the - largest shape along that dimension. - The value of the array element is assumed to be the same along that dimension - for the -\begin_inset Quotes eld -\end_inset - -broadcasted -\begin_inset Quotes erd -\end_inset - - array. - After application of the broadcasting rules, the sizes of all arrays must - match. -\end_layout - -\begin_layout Standard -While a little tedious to explain, the broadcasting rules are easy to pick - up by looking at a couple of examples. - Suppose there is a -\family typewriter -ufunc -\family default - with two inputs, -\begin_inset Formula $A$ -\end_inset - - and -\begin_inset Formula $B$ -\end_inset - -. - Now supposed that -\begin_inset Formula $A$ -\end_inset - - has shape -\begin_inset Formula $4\times6\times5$ -\end_inset - - while -\begin_inset Formula $B$ -\end_inset - - has shape -\begin_inset Formula $4\times6\times1$ -\end_inset - -. - The ufunc will proceed to compute the -\begin_inset Formula $4\times6\times5$ -\end_inset - - output as if -\begin_inset Formula $B$ -\end_inset - - had been -\begin_inset Formula $4\times6\times5$ -\end_inset - - by assuming that -\begin_inset Formula $B[...,k]=B[...,0]$ -\end_inset - - for -\begin_inset Formula $k=1,2,3,4$ -\end_inset - -. - -\end_layout - -\begin_layout Standard -Another example illustrates the idea of adding -\begin_inset Formula $1$ -\end_inset - -'s to the beginning of the array shape-tuple. - Suppose -\begin_inset Formula $A$ -\end_inset - - is the same as above, but -\begin_inset Formula $B$ -\end_inset - - is a length -\begin_inset Formula $5$ -\end_inset - - array. - Because of the first rule, -\begin_inset Formula $B$ -\end_inset - - will be interpreted as a -\begin_inset Formula $1\times1\times5$ -\end_inset - - array, and then because of the second rule -\begin_inset Formula $B$ -\end_inset - - will be interpreted as a -\begin_inset Formula $4\times6\times5$ -\end_inset - - array by repeating the elements of -\begin_inset Formula $B$ -\end_inset - - in the obvious way. - -\end_layout - -\begin_layout Standard -The most common alteration needed is to route-around the automatic pre-pending - of 1's to the shape of the array. - If it is desired, to add -\begin_inset Formula $1$ -\end_inset - -'s to the end of the array shape, then dimensions can always be added using - the -\family typewriter -newaxis -\family default - name in NumPy: -\begin_inset Formula $B[...,\textrm{newaxis, newaxis}]$ -\end_inset - - returns an array with 2 additional 1's appended to the shape of -\begin_inset Formula $B.$ -\end_inset - - -\end_layout - -\begin_layout Standard -One important aspect of broadcasting is the calculation of functions on - regularly spaced grids. - For example, suppose it is desired to show a portion of the multiplication - table by computing the function -\begin_inset Formula $a*b$ -\end_inset - - on a grid with -\begin_inset Formula $a$ -\end_inset - - running from 6 to 9 and -\begin_inset Formula $b$ -\end_inset - - running from 12 to 16. - The following code illustrates how this could be done using ufuncs and - broadcasting. - -\end_layout - -\begin_layout MyCode ->>> a = arange(6, 10); print a -\newline -[6 7 8 9] -\newline ->>> b = arange(12, 17); print b -\newline -[12 - 13 14 15 16] -\newline ->>> table = a[:,newaxis] * b -\newline ->>> print table -\newline -[[ 72 78 84 90 - 96] -\newline - [ 84 91 98 105 112] -\newline - [ 96 104 112 120 128] -\newline - [108 117 126 135 144]] -\end_layout - -\begin_layout Section -Summary of new features -\end_layout - -\begin_layout Standard -More information about using arrays in Python can be found in the old Numeric - documentation at -\begin_inset LatexCommand htmlurl -name "http://numeric.scipy.org" -target "http://numeric.scipy.org" - -\end_inset - -. - Quite a bit of that documentation is still accurate, especially in the - discussion of array basics. - There are significant differences, however, and this book seeks to explain - them in detail. - The following list tries to summarize the significant new features (over - Numeric) available in the -\family typewriter -ndarray -\family default - and -\family typewriter -ufunc -\family default - objects of NumPy: -\end_layout - -\begin_layout Enumerate -more data types (all standard C-data types plus complex floats, Boolean, - string, unicode, and void *); -\end_layout - -\begin_layout Enumerate -flexible data types where each array can have a different itemsize (but - all elements of the same array still have the same itemsize); -\end_layout - -\begin_layout Enumerate -there is a true Python scalar type (contained in a hierarchy of types) for - every data-type an array can have; -\end_layout - -\begin_layout Enumerate -data-type objects define the data-type with support for data-type objects - with fields and subarrays which allow record arrays with nested records; -\end_layout - -\begin_layout Enumerate -many more array methods in addition to functional counterparts; -\end_layout - -\begin_layout Enumerate -attributes more clearly distinguished from methods (attributes are intrinsic - parts of an array so that setting them changes the array itself); -\end_layout - -\begin_layout Enumerate -array scalars covering all data types which inherit from Python scalars - when appropriate; -\end_layout - -\begin_layout Enumerate -arrays can be misaligned, swapped, and in Fortran order in memory (facilitates - memory-mapped arrays); -\end_layout - -\begin_layout Enumerate -arrays can be more easily read from text files and created from buffers - and iterators; -\end_layout - -\begin_layout Enumerate -arrays can be quickly written to files in text and/or binary mode; -\end_layout - -\begin_layout Enumerate -arrays support the removal of the 64-bit memory limitation as long as you - have Python 2.5 or later; -\end_layout - -\begin_layout Enumerate -fancy indexing can be done on arrays using integer sequences and Boolean - masks; -\end_layout - -\begin_layout Enumerate -coercion rules are altered for mixed scalar / array operations so that scalars - (anything that produces a 0-dimensional array internally) will not determine - the output type in such cases. -\end_layout - -\begin_layout Enumerate -when coercion is needed, temporary buffer-memory allocation is limited to - a user-adjustable size; -\end_layout - -\begin_layout Enumerate -errors are handled through the IEEE floating point status flags and there - is flexibility on a per-thread level for handling these errors; -\end_layout - -\begin_layout Enumerate -one can register an error callback function in Python to handle errors are - set to 'call' for their error handling; -\end_layout - -\begin_layout Enumerate -ufunc reduce, accumulate, and reduceat can take place using a different - type then the array type if desired (without copying the entire array); -\end_layout - -\begin_layout Enumerate -ufunc output arrays passed in can be a different type than expected from - the calculation; -\end_layout - -\begin_layout Enumerate -ufuncs take keyword arguments which can specify 1) the error handling explicitly - and 2) the specific 1-d loop to use by-passing the type-coercion detection. - -\end_layout - -\begin_layout Enumerate -arbitrary classes can be passed through ufuncs (__array_wrap__ and __array_prior -ity__ expand previous __array__ method); -\end_layout - -\begin_layout Enumerate -ufuncs can be easily created from Python functions; -\end_layout - -\begin_layout Enumerate -ufuncs have attributes to detail their behavior, including a dynamic doc - string that automatically generates the calling signature; -\end_layout - -\begin_layout Enumerate -several new ufuncs (frexp, modf, ldexp, isnan, isfinite, isinf, signbit); -\end_layout - -\begin_layout Enumerate -new types can be registered with the system so that specialized ufunc loops - can be written over new type objects; -\end_layout - -\begin_layout Enumerate -new types can also register casting functions and rules for fitting into - the -\begin_inset Quotes eld -\end_inset - -can-cast -\begin_inset Quotes erd -\end_inset - - hierarchy; -\end_layout - -\begin_layout Enumerate -C-API enhanced so that more of the functionality is available from compiled - code; -\end_layout - -\begin_layout Enumerate -C-API enhanced so array structure access can take place through macros; -\end_layout - -\begin_layout Enumerate -new iterator objects created for easy handling in C of non-contiguous arrays; -\end_layout - -\begin_layout Enumerate -new multi-iterator object created for easy handling in C of broadcasting; -\end_layout - -\begin_layout Enumerate -types have more functions associated with them (no magic function lists - in the C-code). - Any function needed is part of the type structure. -\end_layout - -\begin_layout Standard -All of these enhancements will be documented more thoroughly in the remaining - portions of this book. -\end_layout - -\begin_layout Section -Summary of differences with Numeric -\end_layout - -\begin_layout Standard -An effort was made to retain backwards compatibility with Numeric all the - way to the C-level. - This was mostly accomplished, with a few changes that needed to be made - for consistency of the new system. - If you are just starting out with NumPy, then this section may be skipped. -\end_layout - -\begin_layout Standard -There are two steps (one required and one optional) to converting code that - works with Numeric to work fully with NumPy The first step uses a compatibility - layer and requires only small changes which can be handled by the numpy.oldnumer -ic.alter_code1 module. - Code written to the compatibility layer will work and be supported. - The purpose of the compatibility layer is to make it easy to convert to - NumPy and many codes may only take this first step and work fine with NumPy. - The second step is optional as it removes dependency on the compatibility - layer and therefore requires a few more extensive changes. - Many of these changes can be performed by the numpy.oldnumeric.alter_code2 - module, but you may still need to do some final tweaking by hand. - Because many users will probably be content to only use the first step, - the alter_code2 module for second-stage migration may not be as complete - as it otherwise could be. - -\end_layout - -\begin_layout Subsection -First-step changes -\end_layout - -\begin_layout Standard -In order to use the compatibility layer there are still a few changes that - need to be made to your code. - Many of these changes can be made by running the alter_code1 module with - your code as input. - -\end_layout - -\begin_layout Enumerate -Importing (the alter_code1 module handles all these changes) -\end_layout - -\begin_deeper -\begin_layout Enumerate -import Numeric --> import numpy.oldnumeric as Numeric -\end_layout - -\begin_layout Enumerate -import Numeric as XX --> import numpy.oldnumeric as XX -\end_layout - -\begin_layout Enumerate -from Numeric import <name1>,...<nameN> --> from numpy.oldnumeric import <name1>,...,<na -meN> -\end_layout - -\begin_layout Enumerate -from Numeric import * --> from numpy.oldnumeric import * -\end_layout - -\begin_layout Enumerate -Similar name changes need to be made for Matrix, MLab, UserArray, LinearAlgebra, - RandomArray RNG, RNG.Statistics, and FFT. - The new names are numpy.oldnumeric.<pkg> where <pkg> is matrix, mlab, user_array, - linear_algebra, random_array, rng, rng_stats, and fft. - -\end_layout - -\begin_layout Enumerate -multiarray and umath (if you used them directly) are now numpy.core.multiarray - and numpy.core.umath, but it is more future proof to replace usages of these - internal modules with numpy.oldnumeric. -\end_layout - -\end_deeper -\begin_layout Enumerate -Method name changes and methods converted to attributes. - The alter_code1 module handles all these changes. - -\end_layout - -\begin_deeper -\begin_layout Enumerate - -\emph on -arr -\emph default -.typecode() --> -\emph on -arr -\emph default -.dtype.char -\end_layout - -\begin_layout Enumerate - -\emph on -arr -\emph default -.iscontiguous() --> -\emph on -arr -\emph default -.flags.contiguous -\end_layout - -\begin_layout Enumerate - -\emph on -arr -\emph default -.byteswapped() --> -\emph on -arr -\emph default -.byteswap() -\end_layout - -\begin_layout Enumerate - -\emph on -arr -\emph default -.toscalar() --> -\emph on -arr -\emph default -.item() -\end_layout - -\begin_layout Enumerate - -\emph on -arr -\emph default -.itemsize() --> -\emph on -arr -\emph default -.itemsize -\end_layout - -\begin_layout Enumerate - -\emph on -arr -\emph default -.spacesaver() eliminated -\end_layout - -\begin_layout Enumerate - -\emph on -arr -\emph default -.savespace() eliminated -\end_layout - -\end_deeper -\begin_layout Enumerate -Some of the typecode characters have changed to be more consistent with - other Python modules (array and struct). - You should only notice this change if you used the actual typecode characters - (instead of the named constants). - -\newline -The alter_code1 module will change uses of 'b' to 'B' for internal Numeric - functions that it knows about because NumPy will interpret 'b' to mean - a signed byte type (instead of the old unsigned). - It will also change the character codes when they are used explicitly in - the .astype method. - In the compatibility layer (and only in the compatibility layer), typecode-requ -iring function calls ( -\emph on -e.g. - -\emph default - zeros, array) understand the old typecode characters. - -\newline -The changes are (Numeric --> NumPy): -\end_layout - -\begin_deeper -\begin_layout Enumerate -'b' --> 'B' -\end_layout - -\begin_layout Enumerate -'1' --> 'b' -\end_layout - -\begin_layout Enumerate -'s' --> 'h' -\end_layout - -\begin_layout Enumerate -'w' --> 'H' -\end_layout - -\begin_layout Enumerate -'u' --> 'I' -\end_layout - -\end_deeper -\begin_layout Enumerate - -\emph on -arr. -\emph default -flat now returns an indexable 1-D iterator. - This behaves correctly when passed to a function, but if you expected methods - or attributes on -\emph on -arr. -\emph default -flat --- besides .copy() --- then you will need to replace -\emph on -arr -\emph default -.flat with -\emph on -arr. -\emph default -ravel() (copies only when necessary) or -\emph on -arr. -\emph default -flatten() (always copies). - The alter_code1 module will change -\emph on -arr -\emph default -.flat to -\emph on -arr -\emph default -.ravel() unless you used the construct -\emph on -arr -\emph default -.flat = obj or -\emph on -arr -\emph default -.flat[ind]. -\end_layout - -\begin_layout Enumerate -If you used type-equality testing on the objects returned from arrays, then - you need to change this to isinstance testing. - Thus type(a[0]) is float or type(a[0]) == float should be changed to isinstance -(a[0], float). - This is because array scalar objects are now returned from arrays. - These inherit from the Python scalars where they can, but define their - own methods and attributes. - This conversion is done by alter_code1 for the types (float, int, complex, - and ArrayType) -\end_layout - -\begin_layout Enumerate -If your code should produce 0-d arrays. - These no-longer have a length as they should be interpreted similarly to - real scalars which don't have a length. - -\end_layout - -\begin_layout Enumerate -Arrays cannot be tested for truth value unless they are empty (returns False) - or have only one element. - This means that if Z: where Z is an array will fail (unless Z is empty - or has only one element). - Also the 'and' and 'or' operations (which test for object truth value) - will also fail on arrays of more than one element. - Use the .any() and .all() methods to test for truth value of an array. - -\end_layout - -\begin_layout Enumerate -Masked arrays return a special nomask object instead of None when there - is no mask on the array for the functions getmask and attribute access - -\emph on -arr -\emph default -.mask -\end_layout - -\begin_layout Enumerate -Masked array functions have a default axis of None (meaning ravel), make - sure to specify an axis if your masked arrays are larger than 1-d. - -\end_layout - -\begin_layout Enumerate -If you used the construct -\family typewriter -arr.shape=<tuple> -\family default -, this will not work for array scalars (which can be returned from array - operations). - You cannot set the shape of an array-scalar (you can read it though). - As a result, for more general code you should use -\family typewriter -arr=arr.reshape(<tuple>) -\family default - which works for both array-scalars and arrays. - -\end_layout - -\begin_layout Standard -The alter_code1 script should handle the changes outlined in steps 1-5 above. - The final incompatibilities in 6-9 are less common and must be modified - by hand if necessary. - -\end_layout - -\begin_layout Subsection -Second-step changes -\end_layout - -\begin_layout Standard -During the second phase of migration (should it be necessary) the compatibility - layer is dropped. - This phase requires additional changes to your code. - There is another conversion module (alter_code2) which can help but it - is not complete. - The changes required to drop dependency on the compatibility layer are -\end_layout - -\begin_layout Enumerate -Importing -\end_layout - -\begin_deeper -\begin_layout Enumerate -numpy.oldnumeric --> numpy -\end_layout - -\begin_layout Enumerate -from numpy.oldnumeric import * --> from numpy import * (this may clobber - more names and therefore require further fixes to your code but then you - didn't do this regularly anyway did you). - The recommended procedure if this replacement causes problems is to fix - the use of from numpy.oldnumeric import * to extract only the required names - and then continue. -\end_layout - -\begin_layout Enumerate -numpy.oldnumeric.mlab --> None, the functions come from other places. -\end_layout - -\begin_layout Enumerate -numpy.oldnumeric.linear_algebra --> numpy.lilnalg with name changes to the - functions (made lower case and shorter). -\end_layout - -\begin_layout Enumerate -numpy.oldnumeric.random_array --> numpy.random with some name changes to the - functions. -\end_layout - -\begin_layout Enumerate -numpy.oldnumeic.fft --> numpy.fft with some name changes to the functions. -\end_layout - -\begin_layout Enumerate -numpy.oldnumeric.rng --> None -\end_layout - -\begin_layout Enumerate -numpy.oldnumeric.rng_stats --> None -\end_layout - -\begin_layout Enumerate -numpy.oldnumeric.user_array --> numpy.lib.user_array -\end_layout - -\begin_layout Enumerate -numpy.oldnumeric.matrix --> numpy -\end_layout - -\end_deeper -\begin_layout Enumerate -The typecode names are all lower-case and refer to type-objects corresponding - to array scalars. - The character codes are understood by array-creation functions but are - not given names. - All named type constants should be replaced with their lower-case equivalents. - Also, the old character codes '1', 's', 'w', and 'u' are not understood - as data-types. - It is probably easiest to manually replace these with Int8, Int16, UInt16, - and UInt32 and let the alter_code2 script convert the names to lower-case - typeobjects. - -\end_layout - -\begin_layout Enumerate -Keyword and argument changes -\end_layout - -\begin_deeper -\begin_layout Enumerate -All -\family typewriter -typecode= -\family default - keywords must be changed to -\family typewriter -dtype= -\family default -. - -\end_layout - -\begin_layout Enumerate -The -\family typewriter -savespace -\family default - keyword argument has been removed from all functions where it was present - (array, sarray, asarray, ones, and zeros). - The sarray function is equivalent to asarray. -\end_layout - -\end_deeper -\begin_layout Enumerate -The default data-type in NumPy is float unlike in Numeric (and numpy.oldnumeric) - where it was int. - There are several functions affected by this so that if your code was relying - on the default data-type, then it must be changed to explicitly add dtype=int. -\end_layout - -\begin_layout Enumerate -The nonzero function in NumPy returns a tuple of index arrays just like - the corresponding method. - There is a flatnonzero function that first ravels the array and then returns - a single index array. - This function should be interchangeable with the old use of nonzero. - -\end_layout - -\begin_layout Enumerate -The default axis is None (instead of 0) to match the methods for the functions - take, repeat, sum, average, product, sometrue, alltrue, cumsum, and cumproduct - (from Numeric) and also for the functions average, max, min, ptp, prod, - std, and mean (from MLab). -\end_layout - -\begin_layout Enumerate -The default axis is None (instead of -1) to match the methods for the functions - argmin, argmax, compress -\end_layout - -\begin_layout Subsection -Updating code that uses Numeric using alter_codeN -\end_layout - -\begin_layout Standard -Despite the long list of changes that might be needed given above, it is - likely that your code does not use any of the incompatible corners and - it should not be too difficult to convert from Numeric to NumPy. - For example all of SciPy was converted in about 2-3 days. - The needed changes are largely search-and replace type changes, and the - alter_codeN modules can help. - The modules have two functions which help the process: -\end_layout - -\begin_layout Description -convertfile (filename, orig=1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Convert the file with the given filename to use NumPy. - If orig is True, then a backup is first made and given the name filename.orig. - Then, the file is converted and the updated code written over the top of - the old file. - -\end_layout - -\begin_layout Description -convertall (direc=os.path.curdir, orig=1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Converts all the -\begin_inset Quotes eld -\end_inset - -.py -\begin_inset Quotes erd -\end_inset - - files in the given directory to use NumPy. - Backups of all the files are first made if orig is True as explained for - the convertfile function. - -\end_layout - -\begin_layout Description -convertsrc (direc=os.path.curdir, ext=None, orig=1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Replace -\family typewriter -''Numeric/arrayobject.h -\begin_inset Quotes erd -\end_inset - - -\family default - with -\family typewriter -''numpy/oldnumeric.h -\begin_inset Quotes erd -\end_inset - - -\family default - in all files ending in the list of extensions given by ext (if ext is None, - then all files are updated). - If orig is True, then first make a backup file with -\begin_inset Quotes eld -\end_inset - -.orig -\begin_inset Quotes erd -\end_inset - - as the extension. -\end_layout - -\begin_layout Description -converttree (direc=os.path.curdir) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Walks the tree pointed to by direc and converts all -\begin_inset Quotes eld -\end_inset - -.py -\begin_inset Quotes erd -\end_inset - - modules in each sub-directory to use NumPy. - No backups of the files are made. - Also, converts all .h and .c files to replace -\family typewriter -''Numeric/arrayobject.h -\begin_inset Quotes erd -\end_inset - - -\family default - with -\family typewriter -''numpy/oldnumeric.h -\begin_inset Quotes erd -\end_inset - - -\family default - so that NumPy is used. - -\end_layout - -\begin_layout Subsection -Changes to think about -\end_layout - -\begin_layout Standard -Even if you don't make changes to your old code. - If you are used to coding in Numeric, then you may need to adjust your - coding style a bit. - This list provides some helpful things to remember. - -\end_layout - -\begin_layout Enumerate -Switch from using typecode characters to bitwidth type names or c-type names - -\end_layout - -\begin_layout Enumerate -Convert use of uppercase type-names Int32, Float, etc., to lower case int32, - float, etc. -\end_layout - -\begin_layout Enumerate -Convert use of functions to method calls where appropriate but explicitly - specify any axis arguments for arrays greater than 1-d. - -\end_layout - -\begin_layout Enumerate -The names for standard computations like Fourier transforms, linear algebra, - and random-number generation have changed to conform to the standard of - lower-case names possibly separated by an underscore. -\end_layout - -\begin_layout Enumerate -Look for ways to take advantage of advanced slicing, but remember it always - returns a copy and may be slower at times. -\end_layout - -\begin_layout Enumerate -Remove any kludges you inserted to eliminate problems with Numeric that - are now gone. - -\end_layout - -\begin_layout Enumerate -Look for ways to take advantage of new features like expanded data-types - (record-arrays). - -\end_layout - -\begin_layout Enumerate -See if you can inherit from the ndarray directly, rather than using user_array.co -ntainer (UserArray). - However, if you were using UserArray in a multiple-inheritance hierarchy - this is going to be more difficult and you can continue to use the standard - container class in user_array (but notice the name change). - -\end_layout - -\begin_layout Enumerate -Watch your usage of scalars extracted from arrays. - Treating Numeric arrays like lists and then doing math on the elements - 1 by 1 was always about 2x slower than using real lists in Python. - This can now be 3x-6x slower than using lists in NumPy because of the increased - complexity of both the indexing of ndarrays and the math of array scalars. - If you must select individual scalars from NumPy, you can get some speed - increases by using the item method to get a standard Python scalar from - an N-d array and by using the itemset method to place a scalar into a particula -r location in the N-d array. - This complicates the appearance of the code, however. - Also, when using these methods inside a loop, be sure to assign the methods - to a local variable to avoid the attribute look-up at each loop iteration. - -\end_layout - -\begin_layout Standard -Throughout this book, warnings are inserted when compatibility issues with - old Numeric are raised. - While you may not need to make any changes to get code to run with the - ndarray object, you will likely want to make changes to take advantage - of the new features of NumPy. - If you get into a jam during the conversion process, you should be aware - that Numeric and NumPy can both be used together and they will not interfere - with each other. - In addition, if you have Numeric 24.0 or newer, they can even share the - same memory. - This makes it easy to use NumPy as well as third-party tools that have - not made the switch from Numeric yet. -\end_layout - -\begin_layout Section -Summary of differences with Numarray -\end_layout - -\begin_layout Standard -Conversion from Numarray can also be relatively painless, depending on how - dependent your code is on the specific structure of the Numarray ufuncs, - cfuncs, and various array-like objects. - The internals of Numarray can be quite different and so depending on how - intimately you used those internals adapting to NumPy can be more or less - difficult. - C-code that used the Numarray C-API can be easily adapted because NumPy - includes a Numarray-compatible C-API module. - All you need to do is replace usage of -\begin_inset Quotes eld -\end_inset - -numarray/libnumarray.h -\begin_inset Quotes erd -\end_inset - - with -\begin_inset Quotes eld -\end_inset - -numpy/libnumarray.h -\begin_inset Quotes erd -\end_inset - - and be sure the directory returned from the Python command numpy.get_numarray_in -clude() is included in the list of directories used for compilation. -\end_layout - -\begin_layout Standard -On the Python-side the largest number of differences are in the methods - and attributes of the array and the way array data-types are represented. - In addition, arrays containing Python Objects, strings, and records are - an integral part of the array object and not handled using a separate class - (although enhanced separate classes do exist for the case of character - arrays and record arrays). - -\end_layout - -\begin_layout Standard -As is the case with Numeric, there is a two-step process available for migrating - code written for Numarray to work with NumPy. - This process involves running functions in the modules alter_code1 and - alter_code2 located in the numarray sub-package of NumPy. - These modules have interfaces identical to the ones that convert Numeric - code, but they work to convert code written for numarray. - The first module will convert your code to use the numarray compatibility - module (numpy.numarray), while the second will try and help convert code - to move away from dependency on the compatibility module. - Because many users will probably be content to only use the first step, - the alter_code2 module for second-stage migration may not be as complete - as it otherwise could be. - -\end_layout - -\begin_layout Standard -Also, the alter_code1 module is not guaranteed to convert every piece of - working numarray code to use NumPy. - If your code relied on the internal module structure of numarray or on - how the class hierarchy was laid out, then it will need to be changed manually - to run with NumPy. - Of course you can still use your code with Numarray installed side-by-side - and the two array objects should be able to exchange data without copying. - -\end_layout - -\begin_layout Subsection -First-step changes -\end_layout - -\begin_layout Standard -The alter_code1 script makes the following import and attribute/method changes -\end_layout - -\begin_layout Subsubsection -Import changes -\end_layout - -\begin_layout Itemize -import numarray --> import numpy.numarray as numarray -\end_layout - -\begin_layout Itemize -import numarray.package --> import numpy.numarray.package as numarray_package - with all usages of numarray.package in the code replaced by numarray_package -\end_layout - -\begin_layout Itemize -import numarray as <name> --> import numpy.numarray s <name> -\end_layout - -\begin_layout Itemize -import numarray.package as <name> --> import numpy.numarray.package as <name> -\end_layout - -\begin_layout Itemize -from numarray import <names> --> from numpy.numarray import <names> -\end_layout - -\begin_layout Itemize -from numarray.package import <names> --> from numpy.numarray.package import - <names> -\end_layout - -\begin_layout Subsubsection -Attribute and method changes -\end_layout - -\begin_layout Itemize -.imaginary --> .imag -\end_layout - -\begin_layout Itemize -.flat --> probably .ravel() (Many usages will still work correctly because - you can index and assign to self.flat) -\end_layout - -\begin_layout Itemize -.byteswapped() --> .byteswap(False) -\end_layout - -\begin_layout Itemize -.byteswap() --> .byteswap(True) (Returns a reference to self instead of None). - -\end_layout - -\begin_layout Itemize -self.info() --> numarray.info(self) -\end_layout - -\begin_layout Itemize -.isaligned() --> .flags.aligned -\end_layout - -\begin_layout Itemize -.isbyteswapped() --> not .dtype.isnative (the byte-order is a property of the - data-type object not the array itself in NumPy). - -\end_layout - -\begin_layout Itemize -.iscontiguous() --> .flags.c_contiguous -\end_layout - -\begin_layout Itemize -.is_c_array() --> .dtype.isnative and .flags.carray -\end_layout - -\begin_layout Itemize -.is_fortran_contiguous() --> .flags.f_contiguous -\end_layout - -\begin_layout Itemize -.is_f_array() --> .dtype.isnative and .flags.farray -\end_layout - -\begin_layout Itemize -.itemsize() --> .itemsize -\end_layout - -\begin_layout Itemize -.nelements() --> .size -\end_layout - -\begin_layout Itemize -self.new(type) --> numarray.newobj(self, type) -\end_layout - -\begin_layout Itemize -.repeat(r) --> .repeat(r, axis=0) -\end_layout - -\begin_layout Itemize -.size() --> .size -\end_layout - -\begin_layout Itemize -.type() --> numarray.typefrom(self) -\end_layout - -\begin_layout Itemize -.typecode() --> .dtype.char -\end_layout - -\begin_layout Itemize -.stddev() --> .std() -\end_layout - -\begin_layout Itemize -.togglebyteorder() --> numarray.togglebyteorder(self) -\end_layout - -\begin_layout Itemize -.getshape() --> .shape -\end_layout - -\begin_layout Itemize -.setshape(obj) --> .shape = obj -\end_layout - -\begin_layout Itemize -.getflat() --> .ravel() -\end_layout - -\begin_layout Itemize -.getreal() --> .real -\end_layout - -\begin_layout Itemize -.setreal(obj) --> .real = obj -\end_layout - -\begin_layout Itemize -.getimag() --> .imag -\end_layout - -\begin_layout Itemize -.setimag(obj) --> .imag = obj -\end_layout - -\begin_layout Itemize -.getimaginary() --> .imag -\end_layout - -\begin_layout Itemize -.setimaginary(obj) --> .imag = obj -\end_layout - -\begin_layout Subsection -Second-step changes -\end_layout - -\begin_layout Standard -One of the notable differences is that several functions (array, arange, - fromfile, and fromstring) do not take the shape= keyword argument. - Instead you simply reshape the result using the reshape method. - Another notable difference is that instead of allowing typecode=, type=, - and dtype= variants for specifying the data-types, you must use the dtype= - keyword. - Other differences include -\end_layout - -\begin_layout Itemize -matrixmultiply(a,b) --> dot(a,b) -\end_layout - -\begin_layout Itemize -innerproduct(a,b) --> inner(a,b) -\end_layout - -\begin_layout Itemize -outerproduct(a,b) --> outer(a,b) -\end_layout - -\begin_layout Itemize -kroneckerproduct(a,b) --> kron(a,b) -\end_layout - -\begin_layout Itemize -tensormultiply(a,b) --> None -\end_layout - -\begin_layout Subsection -Additional Extension modules -\end_layout - -\begin_layout Standard -There are three extension packages that come included with numarray which - are now downloaded separately. - Stubs for these packages exist in numpy.numarray but they try and find the - actual code by looking at what is currently installed. - These packages are available in SciPy but can be installed separately as - well: -\end_layout - -\begin_layout Itemize -nd_image --> scipy.ndimage -\end_layout - -\begin_layout Itemize -convolve --> scipy.stsci.convolve -\end_layout - -\begin_layout Itemize -image --> scipy.stsci.image -\end_layout - -\begin_layout Standard -If you don't want to install all of scipy, you can grab just these packages - from SVN using -\end_layout - -\begin_layout LyX-Code -svn co http://svn.scipy.org/svn/scipy/trunk/Lib/ndimage ndimage -\end_layout - -\begin_layout LyX-Code -svn co http://svn.scipy.org/svn/scipy/trunk/Lib/stsci stsci -\end_layout - -\begin_layout Standard -and then run -\end_layout - -\begin_layout LyX-Code -cd ndimage; sudo python setup.py install -\end_layout - -\begin_layout LyX-Code -cd stsci; sudo python setup.py install -\end_layout - -\begin_layout Standard -On a Windows system, you can use the Tortoise SVN client which is integrated - into the Windows Explorer. - It can be downloaded from http://tortoisesvn.tigris.org. - Instructions on how to use it are also provided on that site. - After downloading the packages from SVN, installation will still require - a C-compiler (the mingw32 compiler works fine even with MSVC-compiled Python - as long as you specify --compiler=mingw32). - Alternatively you can download binary releases of scipy from http://www.scipy.org - to get the needed functionality or use the Enthon edition of Python. -\end_layout - -\begin_layout Chapter -The Array Object -\end_layout - -\begin_layout Quotation -Don't worry about people stealing your ideas. - If your ideas are any good, you'll have to ram them down people's throats. -\end_layout - -\begin_layout Right Address ---- -\emph on -Howard Aiken, IBM engineer -\end_layout - -\begin_layout Quotation -No idea is so antiquated that it was not once modern; no idea is so modern - that it will not someday be antiquated. -\end_layout - -\begin_layout Right Address ---- -\emph on -Ellen Glasgow -\end_layout - -\begin_layout Section - -\family typewriter -ndarray -\family default - Attributes -\end_layout - -\begin_layout Standard -Array -\begin_inset LatexCommand index -name "ndarray|(" - -\end_inset - - attributes reflect information that is intrinsic to the array itself. - Generally, accessing an array through its attributes allows you to get - and sometimes set intrinsic properties of the array without creating a - new array. - The exposed attributes are the core parts of an array and only some of - them can be reset meaningfully without creating a new array. - Table -\begin_inset LatexCommand ref -reference "cap:ndarray-attributes" - -\end_inset - - shows all the attributes -\begin_inset LatexCommand index -name "ndarray!attributes|(" - -\end_inset - - with a brief description. - Detailed information on each attribute is given below. -\end_layout - -\begin_layout Warning -Numeric Compatibility: you should check your old use of the .flat attribute. - This attribute now returns an iterator object which acts like a 1-d array - in terms of indexing. - while it does not share all the attributes or methods of an array, it will - be interpreted as an array in functions that take objects and convert them - to arrays. - Furthermore, Any changes in an array converted from a 1-d iterator will - be reflected back in the original array when the converted array is deleted. - -\end_layout - -\begin_layout Standard -\begin_inset Float table -wide false -sideways false -status open - -\begin_layout Standard -\begin_inset Caption - -\begin_layout Standard -\begin_inset LatexCommand label -name "cap:ndarray-attributes" - -\end_inset - -Attributes of the -\family typewriter -ndarray -\family default -. -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -vspace*{-0.2in} -\backslash -setlength{ -\backslash -extrarowheight}{0.25eM} -\end_layout - -\begin_layout Standard - -\end_layout - -\begin_layout Standard - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\align center -\begin_inset Tabular -<lyxtabular version="3" rows="18" columns="3"> -<features> -<column alignment="center" valignment="top" leftline="true" width="1in"> -<column alignment="center" valignment="top" leftline="true" width="1in"> -<column alignment="block" valignment="top" leftline="true" rightline="true" width="3in"> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family sans -\series bold -\size large -Attribute -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family sans -\series bold -\size large -Settable -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family sans -\series bold -\size large -Description -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -flags -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -No -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -special array-connected dictionary-like object with attributes showing the - state of flags in this array; only the flags WRITEABLE, ALIGNED, and UPDATEIFCO -PY can be modified by setting attributes of this object -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -shape -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Yes -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -tuple showing the array shape; setting this attribute re-shapes the array -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -strides -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Yes -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -tuple showing how many -\emph on -bytes -\emph default - must be jumped in the data segment to get from one entry to the next -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -ndim -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -No -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -number of dimensions in array -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -data -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Yes -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -buffer object loosely wrapping the array data (only works for single-segment - arrays) -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -size -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -No -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -total number of elements -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -itemsize -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -No -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -size (in bytes) of each element -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -nbytes -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -No -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -total number of bytes used -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -base -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -No -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -object this array is using for its data buffer, or None if it owns its own - memory -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -dtype -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Yes -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -data-type object for this array -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -real -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Yes -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -real part of the array; setting copies data to real part of current array -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -imag -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Yes -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -imaginary part, or read-only zero array if type is not complex; setting - works only if type is complex -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -flat -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Yes -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -one-dimensional, indexable iterator object that acts somewhat like a 1-d - array -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -ctypes -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -No -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -object to simplify the interaction of this array with the ctypes module -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -__array_interface__ -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -No -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -dictionary with keys (data, typestr, descr, shape, strides) for compliance - with Python side of array protocol -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -__array_struct__ -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -No -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -array interface on C-level -\end_layout - -\end_inset -</cell> -</row> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -__array_priority__ -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -No -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -always 0.0 for base type -\family typewriter -ndarray -\end_layout - -\end_inset -</cell> -</row> -</lyxtabular> - -\end_inset - - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Memory Layout attributes -\end_layout - -\begin_layout Description -flags -\begin_inset LatexCommand index -name "ndarray!attributes!flags" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Array flags -\begin_inset LatexCommand index -name "ndarray!flags|(" - -\end_inset - - provide information about how the memory area used for the array is to - be interpreted. - There are 6 Boolean flags in use which govern whether or not: -\end_layout - -\begin_deeper -\begin_layout Description -C_CONTIGUOUS\InsetSpace ~ -(C) the data is in a single, C-style contiguous segment; -\end_layout - -\begin_layout Description -F_CONTIGUOUS\InsetSpace ~ -(F) the data is in a single, Fortran-style contiguous segment; -\end_layout - -\begin_layout Description -OWNDATA\InsetSpace ~ -(O) the array owns the memory it uses or if it borrows it from another - object (if this is False, the base attribute retrieves a reference to the - object this array obtained its data from); -\end_layout - -\begin_layout Description -WRITEABLE\InsetSpace ~ -(W) the data area can be written to; -\end_layout - -\begin_layout Description -ALIGNED\InsetSpace ~ -(A) the data and strides are aligned appropriately for the hardware - (as determined by the compiler); -\end_layout - -\begin_layout Description -UPDATEIFCOPY\InsetSpace ~ -(U) this array is a copy of some other array (referenced by - -\family typewriter -.base -\family default -). - When this array is deallocated, the base array will be updated with the - contents of this array. -\end_layout - -\end_deeper -\begin_layout Description -\InsetSpace ~ - Only the -\series bold -UPDATEIFCOPY -\series default -, -\series bold -WRITEABLE -\series default -, and -\series bold -ALIGNED -\series default - flags can be changed by the user. - This can be done using the special array-connected, dictionary-like object - that the flags attribute returns. - By setting elements in this dictionary, the underlying array obect's flags - are altered. - Flags can also be changed using the method -\family typewriter -setflags -\family default -(...). - All flags in the dictionary can be accessed using their first (upper case) - letter as well as the full name. - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Certain logical combinations of flags can also be read using named keys - to the special flags dictionary. - These combinations are -\end_layout - -\begin_deeper -\begin_layout Description -FNC Returns F_CONTIGUOUS and not C_CONTIGUOUS -\end_layout - -\begin_layout Description -FORC Returns F_CONTIGUOUS or C_CONTIGUOUS (one-segment test). -\end_layout - -\begin_layout Description -BEHAVED\InsetSpace ~ -(B) Returns ALIGNED and WRITEABLE -\end_layout - -\begin_layout Description -CARRAY\InsetSpace ~ -(CA) Returns BEHAVED and C_CONTIGUOUS -\end_layout - -\begin_layout Description -FARRAY_(FA) Returns BEHAVED and F_CONTIGUOUS and not C_CONTIGUOUS -\end_layout - -\end_deeper -\begin_layout Note -The array flags cannot be set arbitrarily. - UPDATEIFCOPY can only be set False. - the ALIGNED flag can only be set True if the data is truly aligned. - The flag WRITEABLE can only be set True if the array owns its own memory - or the ultimate owner of the memory exposes a writeable buffer interface - (or is a string). - The exception for string is made so that unpickling can be done without - copying memory. - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Flags can also be set and read using attribute access with the lower-case - key equivalent (without first letter support). - Thus, for example, self.flags.c_contiguous returns whether or not the array - is C-style contiguous, and self.flags.writeable=True changes the array to - be writeable (if possible) -\begin_inset LatexCommand index -name "ndarray!flags|)" - -\end_inset - -. -\end_layout - -\begin_layout Description -shape -\begin_inset LatexCommand index -name "ndarray!attributes!shape" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The shape of the array is a tuple giving the number of elements in each - dimension. - The shape can be reset for single-segment arrays by setting this attribute - to another tuple. - The total number of elements cannot change. - However, a -1 may be used in a dimension entry to indicate that the array - length in that dimension should be computed so that the total number of - elements does not change. - -\family typewriter -a.shape=x -\family default - is equivalent to -\family typewriter -a=a.reshape(x) -\family default - except the latter can be used even if the array is not single-segment and - even if -\begin_inset Formula $a$ -\end_inset - - is an array scalar. - -\end_layout - -\begin_layout Note -Setting the shape attribute to () for a 1-element array will turn self into - a 0-dimensional array. - This is one of the few ways to get a 0-dimensional array in Python. - Most other operations will return an array scalar. - Other ways to get a 0-dimensional array in Python include calling array - with a scalar argument and calling the squeeze method of an array whose - shape is all 1's. - -\end_layout - -\begin_layout Description -strides -\begin_inset LatexCommand index -name "ndarray!attributes!strides" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The strides of an array is a tuple showing for each dimension how many - -\emph on -bytes -\emph default - must be skipped to get to the next element in that dimension. - Setting this attribute to another tuple will change the way the memory - is viewed. - This attribute can only be set to a tuple that will not cause the array - to access unavailable memory. - If an attempt is made to do so, ValueError is raised. -\end_layout - -\begin_layout Description -ndim -\begin_inset LatexCommand index -name "ndarray!attributes!ndim" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The number of dimensions of an array is sometimes called the rank of the - array. - Getting this attribute reveals the length of the shape tuple and the strides - tuple. - -\end_layout - -\begin_layout Description -data -\begin_inset LatexCommand index -name "ndarray!attributes!data" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - A buffer object referencing the actual data for this array if this array - is single-segment. - If the array is not single-segment, then an AttributeError is raised. - The buffer object is writeable depending on the status of self.flags.writeable. -\end_layout - -\begin_layout Description -size -\begin_inset LatexCommand index -name "ndarray!attributes!size" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The total number of elements in the array. -\end_layout - -\begin_layout Description -itemsize -\begin_inset LatexCommand index -name "ndarray!attributes!itemsize" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The number of bytes each element of the array requires. - -\end_layout - -\begin_layout Description -nbytes -\begin_inset LatexCommand index -name "ndarray!attributes!nbytes" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The total number of bytes used by the array. - This is equal to -\family typewriter -self.itemsize*self.size -\family default -. -\end_layout - -\begin_layout Description -base -\begin_inset LatexCommand index -name "ndarray!attributes!base" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - If the array does not own its own memory, then this attribute returns the - object whose memory this array is referencing. - The returned object may not be the original allocator of the memory, but - may be borrowing it from still another object. - If this array does own its own memory, then None is returned unless the - UPDATEIFCOPY flag is True in which case self.base is the array that will - be updated when self is deleted. - UPDATEIFCOPY gets set for an array that is created as a behaved copy of - a general array. - The intent is for the misaligned array to get any changes that occur to - the copy. - -\end_layout - -\begin_layout Subsection -Data Type attributes -\end_layout - -\begin_layout Standard -There are several ways to specify the kind of data that the array is composed - of. - The fullest description that preserves field information is always obtained - using an actual dtype object. - See Chapter -\begin_inset LatexCommand ref -reference "cha:Data-descriptor-objects" - -\end_inset - - for more discussion on data-type objects and acceptable arguments to construct - data-type objects. - Three commonly-used attributes of the data-type object returned are also - documented here. -\end_layout - -\begin_layout Description -dtype -\begin_inset LatexCommand index -name "ndarray!attributes!dtype" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - A data-type object that fully describes (including any defined fields) - each fixed-length item in the array. - Whether or not the data is in machine byte-order is also determined by - the data-type. - The data-type attribute can be set to anything that can be interpreted - as a data-type (see Chapter -\begin_inset LatexCommand ref -reference "cha:Data-descriptor-objects" - -\end_inset - - for more information). - Setting this attribute allows you to change the interpretation of the data - in the array. - The new data-type must be compatible with the array's current data-type. - The new data-type is compatible if it has the same itemsize as the current - data-type descriptor, or (if the array is a single-segment array) if the - the array with the new data-type fits in the memory already consumed by - the array. - -\end_layout - -\begin_layout Description -dtype.type -\end_layout - -\begin_layout Description -\InsetSpace ~ - A Python type object gives the typeobject whose instances represent elements - of the array. - This type object can be used to instantiate a scalar of that type. - -\end_layout - -\begin_layout Description -dtype.char -\end_layout - -\begin_layout Description -\InsetSpace ~ - A typecode character unique to each of the 21 built-in types. - -\end_layout - -\begin_layout Description -dtype.str -\end_layout - -\begin_layout Description -\InsetSpace ~ - This string consists of a required first character giving the -\begin_inset Quotes eld -\end_inset - -endianness -\begin_inset Quotes erd -\end_inset - - of the data ( -\begin_inset Quotes eld -\end_inset - -< -\begin_inset Quotes erd -\end_inset - - for little endian, -\begin_inset Quotes eld -\end_inset - -> -\begin_inset Quotes erd -\end_inset - - for big endian, and -\begin_inset Quotes eld -\end_inset - -| -\begin_inset Quotes erd -\end_inset - - for irrelevant), the second character is a code for the kind of data ('b' - for Boolean, 'i' for signed integer, 'u' for unsigned integer, 'f' for - floating-point, 'c' for complex floating point, 'O' for object, 'S' for - ASCII string, 'U' for unicode, and 'V' for void), the final characters - give the number of bytes each element uses. -\end_layout - -\begin_layout Subsection -Other attributes -\end_layout - -\begin_layout Description -T -\begin_inset LatexCommand index -name "ndarray!attributes!T" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Equivalent to self.transpose(). - For self.ndim < 2, it returns a view of self. - -\end_layout - -\begin_layout Warning -If arr is 0- or 1-dimensional, then arr.T will return a new ndarray which - refers to the same data as arr. - This is because transpose has the effect of reversing the shape attribute - of an array (whose 0-d and 1-d equivalent is to return the same array). - This may be surprising if you are thinking of your 1-d array as a -\begin_inset Quotes eld -\end_inset - -row -\begin_inset Quotes erd -\end_inset - - or a -\begin_inset Quotes eld -\end_inset - -column -\begin_inset Quotes erd -\end_inset - - vector and expected the .T attribute to return the other convention. - -\end_layout - -\begin_layout Description -real -\begin_inset LatexCommand index -name "ndarray!attributes!real" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The real part of an array. - For arrays that are not complex this attribute returns the array itself. - Setting this attribute allows setting just the real part of an array. - If the array is already real then setting this attribute is equivalent - to self[...] = values. -\end_layout - -\begin_layout Description -imag -\begin_inset LatexCommand index -name "ndarray!attributes!imag" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - A view of the imaginary part of an array. - For arrays that are not complex, this returns a read-only array of zeros. - Setting this array allows in-place alteration of the complex part of an - imaginary array. - If the array is not complex, then trying to set this attribute raises an - Error. - -\end_layout - -\begin_layout Description -flat -\begin_inset LatexCommand index -name "ndarray!attributes!flat" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an iterator object (numpy.flatiter) that acts like a 1-d version - of the array. - 1-d indexing works on this array and it can be passed in to most routines - as an array wherein a 1-d array will be constructed from it. - The new 1-d array will reference this array's data if this array is C-style - contiguous, otherwise, new memory will be allocated for the 1-d array, - the UPDATEIFCOPY flag will be set for the new array, and this array will - have its WRITEABLE flag set FALSE until the the last reference to the new - array disappears. - When the last reference to the new 1-d array disappears, the data will - be copied over to this non-contiguous array. - This is done so that a.flat effectively references the current array regardless - of whether or not it is contiguous or non-contiguous. - As an example, consider the following code: -\end_layout - -\begin_layout MyCode ->>> a = zeros((4,5)) -\newline ->>> b = ones(6) -\newline ->>> add(b,b,a[1:3,0:3].flat) -\newline -array([[ 2., - 2., 2.], -\newline - [ 2., 2., 2.]]) -\newline ->>> print a -\newline -[[ 0. - 0. - 0. - 0. - 0.] -\newline - [ 2. - 2. - 2. - 0. - 0.] -\newline - [ 2. - 2. - 2. - 0. - 0.] -\newline - [ 0. - 0. - 0. - 0. - 0.]] -\end_layout - -\begin_layout Description -\InsetSpace ~ - The numpy.flatiter object has two methods: -\series bold -__array__() -\series default - and -\series bold -copy() -\series default - and one attribute: -\series bold -base -\series default -. - The base attribute returns a reference to the underlying array. - -\end_layout - -\begin_layout Description -__array_priority__ -\begin_inset LatexCommand index -name "ndarray!attributes!\\_\\_array\\_priority\\_\\_" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The array priority attribute is a floating point number useful in mixed - operations involving two subtypes to decide which subtype is returned. - The base ndarray object has priority 0.0 and 1.0 is the default subtype priority. -\end_layout - -\begin_layout Subsection -Array Interface attributes -\end_layout - -\begin_layout Standard -The array interface -\begin_inset LatexCommand index -name "array interface" - -\end_inset - - (sometimes called array protocol) was created in 2005 as a means for array-like - Python objects to re-use each other's data buffers intelligently whenever - possible. - The ndarray object supports both the Python-side and the C-side of the - array interface. - The system is able to consume objects that expose the array interface, - and array objects can expose their inner workings to other objects that - support the array interface. - -\end_layout - -\begin_layout Description -__array_interface__ -\begin_inset LatexCommand index -name "ndarray!attributes!\\_\\_array\\_interface\\_\\_" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The python-side of the array interface. - It is a dictionary with the following attributes: -\end_layout - -\begin_deeper -\begin_layout Description -data A 2-tuple (dataptr, read-only flag). - The dataptr is a string giving the address (in hexadecimal format) of the - array data. - The read-only flag is True if the array memory is read-only. - -\end_layout - -\begin_layout Description -strides The strides tuple. - Same as -\series bold -strides -\series default - attribute except None is returned if the array is C-style contiguous. -\end_layout - -\begin_layout Description -shape The shape tuple. - Same as -\series bold -shape -\series default - attribute. -\end_layout - -\begin_layout Description -typestr A string giving the format of the data. - Same as -\series bold -dtype.str -\series default - attribute. - -\end_layout - -\begin_layout Description -descr A list of tuples providing the detailed description of this data type. - This information is obtained from the arrdescr attribute of the dtypedescr - object associated with each array. - For arrays with fields, this will return a valid array-protocol descriptor - list. - For arrays without defined fields, this returns [('',typestr)]. -\end_layout - -\end_deeper -\begin_layout Description -__array_struct__ -\begin_inset LatexCommand index -name "ndarray!attributes!\\_\\_array\\_struct\\_\\_" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - A PyCObject that wraps a pointer to a PyArrayInterface structure. - This is only useful on the C-level for rapid implementation of the array - interface, using a single attribute lookup. -\end_layout - -\begin_layout Description -ctypes -\begin_inset LatexCommand index -name "ndarray!attributes!ctypes|(" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - This attribute creates an object that makes it easier to use arrays when - calling out to shared libraries with the ctypes module. - The returned object has data, shape, and strides attributes which return - ctypes -\begin_inset LatexCommand index -name "ctypes" - -\end_inset - - objects that can be used as arguments to a shared library. - These attributes are: -\end_layout - -\begin_deeper -\begin_layout Description -data A pointer to the memory area of the array as a Python integer. - This memory area may contain data that is not aligned, or not in correct - byte-order. - The memory area may not even be writeable. - The array flags and data-type of this array should be respected when passing - this attribute to arbitrary C-code to avoid trouble that can include Python - crashing. - User Beware! The value of this attribute is exactly the same as -\family typewriter -self.__array_interface__['data'][0] -\family default -. -\end_layout - -\begin_layout Description -shape (c_intp*self.ndim) A ctypes array of length self.ndim where the base-type - is the C-integer corresponding to dtype('p') on this platform. - This base-type could be c_int, c_long, or c_longlong depending on the platform. - The c_intp type is defined accordingly in numpy.ctypeslib. - The ctypes array contains the shape of the underlying array. -\end_layout - -\begin_layout Description -strides (c_intp*self.ndim) A ctypes array of length self.ndim where the base-type - is the same as for the shape attribute. - This ctypes array contains the strides information from the underlying - array. - This strides information is important for showing how many bytes must be - jumped to get to the next element in the array. - -\end_layout - -\begin_layout Description -_as_parameter_ (c_void_p) Returns the data-pointer to the array as a ctypes - object. - Among other possible uses, this enables this ctypes object to be used directly - in a ctypes-loaded call to an arbitrary function. - Be sure to respect the flags on the array and the size and strides of the - array so as not to use this memory in-appropriately (see the -\series bold -ndpointer -\series default - function for how to return a class that can be used with the argtypes attribute - of ctypes functions). - -\end_layout - -\end_deeper -\begin_layout Warning -Be careful using the ctypes attribute --- especially on temporary arrays - or arrays constructed on the fly. - For example, calling (a+b).ctypes.data_as(ctypes.c_void_p) returns a pointer - to memory that is invalid because the array created as (a+b) is deallocated - before the next Python statement. - You can avoid this problem using either c=a+b or ct=(a+b).ctypes. - In the latter case, ct will hold a reference to the array until ct is deleted - or re-assigned. -\end_layout - -\begin_layout Description -\InsetSpace ~ - The ctypes object also has several methods which can alter how the shape, - strides, and data of the underlying object is returned. - -\end_layout - -\begin_deeper -\begin_layout Description -data_as (obj) Return the data pointer cast-to a particular c-types object. - For example, calling -\family typewriter -self._as_parameter_ -\family default - is equivalent to -\family typewriter -self.data_as(ctypes.c_void_p) -\family default -. - Perhaps you want to use the data as a pointer to a ctypes array of floating-poi -nt data: -\family typewriter -self.data_as(ctypes.POINTER(ctypes.c_double)) -\family default -. - -\end_layout - -\begin_layout Description -shape_as (obj) Return the shape tuple as an array of some other c-types - type. - For example: -\family typewriter -self.shape_as(ctypes.c_short) -\family default -. - -\end_layout - -\begin_layout Description -strides_as (obj) Return the strides tuple as an array of some other c-types - type. - For example: -\family typewriter -self.strides_as(ctypes.c_longlong) -\family default -. -\end_layout - -\end_deeper -\begin_layout Description -\InsetSpace ~ - If the ctypes module is not available, then the ctypes attribute of array - objects still returns something useful, but ctypes objects are not returned - and errors may be raised instead. - In particular, the object will still have the _as_parameter_ attribute - which will return an integer equal to the data -\begin_inset LatexCommand index -name "ndarray!attributes!ctypes|)" - -\end_inset - - attribute -\begin_inset LatexCommand index -name "ndarray!attributes|)" - -\end_inset - -. - -\end_layout - -\begin_layout Section - -\family typewriter -ndarray -\family default - Methods -\end_layout - -\begin_layout Standard -In NumPy, the -\family typewriter -ndarray -\family default - object has many methods -\begin_inset LatexCommand index -name "ndarray!methods|(" - -\end_inset - - which operate on or with the array in some fashion, typically returning - an array result. - In Numeric, many of these methods were only library calls. - These methods are explained in this chapter. - Whenever the array whose method is being called needs to be referenced - it will be referred to as -\emph on -this array -\emph default -, or -\emph on -self -\emph default -. - Keyword arguments will be shown. - Methods that only take one argument do not have keyword arguments. - Default values for one argument methods will be shown in braces {default}. - -\end_layout - -\begin_layout Warning -If you are converting code from Numeric, then you will need to make the - following (search and replace) conversions: -\family typewriter -.typecode() --> .dtype.char -\family default -; -\family typewriter -.iscontiguous() --> .flags.contiguous -\family default -; -\family typewriter -.byteswapped() --> .byteswap() -\family default -; -\family typewriter -.toscalar() --> .item() -\family default -; and -\family typewriter -.itemsize() --> .itemsize -\family default -. - The numpy.oldnumeric.alter_code1 module can automate this for you. -\end_layout - -\begin_layout Subsection -Array conversion -\end_layout - -\begin_layout Description -tolist -\begin_inset LatexCommand index -name "ndarray!methods!tolist" - -\end_inset - - () -\end_layout - -\begin_layout Description -\InsetSpace ~ - The contents of self as a nested list. -\end_layout - -\begin_layout MyCode ->>> a = array([[1,2,3],[4,5,6]]); print a.tolist() -\newline -[[1, 2, 3], [4, 5, 6]] -\end_layout - -\begin_layout Description -item -\begin_inset LatexCommand index -name "ndarray!methods!item" - -\end_inset - - (*args) -\end_layout - -\begin_layout Description -\InsetSpace ~ - If no arguments are passed in, then this method only works for arrays with - one element (a.size == 1). - In this case, it returns a standard Python scalar object (if possible) - copied from the first element of self. - When the data type of self is longdouble or clongdouble, this returns a - scalar array object because there is no available Python scalar that would - not lose information. - Void arrays return a buffer object for item() unless fields are defined - in which case a tuple is returned. -\end_layout - -\begin_layout MyCode ->>> asc = a[0,0].item() -\newline ->>> type(asc) -\newline -<type 'int'> -\newline ->>> asc -\newline -1 -\newline ->>> type(a[0,0]) -\newline -<type - 'numpy.int32'> -\end_layout - -\begin_layout Description -\InsetSpace ~ - If arguments are provided, then they indicate indices into the array (either - a flat index or an nd-index). - A standard Python scalar corresponding to the item at the given location - is then returned. - This is very similar to self[args] except instead of an array scalar, a - standard Python scalar is returned. - This can be useful for speeding up access to elements of the array and - doing arithmetic on elements of the array using Python's optimized math. - -\end_layout - -\begin_layout Description -itemset -\begin_inset LatexCommand index -name "ndarray!methods!itemset" - -\end_inset - - (*args) -\end_layout - -\begin_layout Description -\InsetSpace ~ - There must be at least 1 argument and define the last argument as item. - Then, this is equivalent to but faster than self[args] = item. - The item should be a scalar value and args must select a single item in - the array. -\end_layout - -\begin_layout Description -tostring -\begin_inset LatexCommand index -name "ndarray!methods!tostring" - -\end_inset - - (order='C') -\end_layout - -\begin_layout Description -\InsetSpace ~ - A Python string showing a copy of the raw contents of data memory. - The string can be produced in either 'C' or 'Fortran', or 'Any' order (the - default is 'C'-order). - 'Any' order means C-order unless the F_CONTIGUOUS flag in the array is - set, then 'Fortran' order. - -\end_layout - -\begin_layout Description -tofile -\begin_inset LatexCommand index -name "ndarray!methods!tofile" - -\end_inset - - (file=, sep='', format='') -\end_layout - -\begin_layout Description -\InsetSpace ~ - Write the contents of self to the open file object. - If file is a string, then open a file of that name first. - If sep is the empty string, then write the file in binary mode. - If sep is any other string, write the array in simple text mode separating - each element with the value of the sep string. - When the file is written in text mode, the format string can be used to - alter the appearance of each entry. - If format is the empty string, then it is equivalent to -\family typewriter - -\begin_inset Quotes eld -\end_inset - -%s -\begin_inset Quotes erd -\end_inset - - -\family default -. - Each element of the array will be converted to a Python scalar, -\family typewriter -o -\family default -, and written to the file as -\family typewriter - -\begin_inset Quotes eld -\end_inset - -format -\begin_inset Quotes erd -\end_inset - - % o -\family default -. - Note that writing an array to a file does not store any information about - the shape, type, or endianness of an array. - When written in binary mode, tofile is functionally equivalent to -\family typewriter -fid.write(self.tostring()) -\family default -. -\end_layout - -\begin_layout MyCode ->>> a.tofile('myfile.txt',sep=':',format='%03d') -\end_layout - -\begin_layout MyCode -Contents of myfile.txt -\end_layout - -\begin_layout MyCode -001:002:003:004:005:006 -\end_layout - -\begin_layout Description -dump -\begin_inset LatexCommand index -name "ndarray!methods!dump" - -\end_inset - - (file) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Pickle the contents of self to the file object represented by file. - Equivalent to cPickle.dump(self, file, 2) -\end_layout - -\begin_layout Description -dumps -\begin_inset LatexCommand index -name "ndarray!methods!dumps" - -\end_inset - - () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return pickled representation of self as a string. - Equivalent to cPickle.dumps(self, 2) -\end_layout - -\begin_layout Description -astype -\begin_inset LatexCommand index -name "ndarray!methods!astype" - -\end_inset - - ({None}) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Force conversion of this array to an array with the data type provided - as the argument. - If the argument is None, or equal to the data type of self, then return - a copy of the array. - -\end_layout - -\begin_layout Description -byteswap -\begin_inset LatexCommand index -name "ndarray!methods!byteswap" - -\end_inset - - ({False}) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Byteswap the elements of the array and return the byteswapped array. - If the argument is True, then byteswap in-place and return a reference - to self. - Otherwise, return a copy of the array with the elements byteswapped. - The data-type descriptor is not changed so the array will have changed - numbers. -\end_layout - -\begin_layout Description -copy -\begin_inset LatexCommand index -name "ndarray!methods!copy" - -\end_inset - - () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a copy of the array (which is always single-segment, and ALIGNED). - However, the data-type is preserved (including whether or not the data - is byteswapped). - -\end_layout - -\begin_layout Description -view -\begin_inset LatexCommand index -name "ndarray!methods!view" - -\end_inset - - ({None}) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a new array using the same memory area as self. - If the optional argument is given, it can be either a typeobject that is - a sub-type of the ndarray or an object that can be converted to a data-type - descriptor. - If the argument is a typeobject then a new array of that Python type is - returned that uses the information from self. - If the argument is a data-type descriptor, then a new array of the same - Python type as self is returned using the given data-type. - -\end_layout - -\begin_layout MyCode ->>> print a.view(single) -\newline -[[ 1.40129846e-45 2.80259693e-45 4.20389539e-45] -\newline - - [ 5.60519386e-45 7.00649232e-45 8.40779079e-45]] -\newline ->>> a.view(ubyte) -\newline -array([[1, - 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0], -\newline - [4, 0, 0, 0, 5, 0, 0, 0, 6, 0, - 0, 0]], dtype=uint8) -\end_layout - -\begin_layout Description -getfield -\begin_inset LatexCommand index -name "ndarray!methods!getfield" - -\end_inset - - (dtype=, offset=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a -\emph on -field -\emph default - of the given array as an array of the given data type. - A field is a view of the array's data at a certain byte offset interpreted - as a given data type. - The returned array is a reference into self, therefore changes made to - the returned array will be reflected in self. - This method is particularly useful for record arrays that use a void data - type, but it can also be used to extract the low (high)-order bytes of - other array types as well. - For example, using getfield, you could extract fixed-length substrings - from an array of strings. - -\end_layout - -\begin_layout MyCode ->>> a = array(['Hello','World','NumPy']) -\newline ->>> a.getfield('S2',1) -\newline -array(['el', - 'or', 'um'], -\newline - dtype='|S2') -\end_layout - -\begin_layout Description -setflags -\begin_inset LatexCommand index -name "ndarray!methods!setflags" - -\end_inset - - (write=None, align=None, uic=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Set array flags WRITEABLE, ALIGNED, and UPDATEIFCOPY, respectively. - The ALIGNED flag can only be set to True if the data is actually aligned - according to the type. - The UPDATEIFCOPY flag can never be set to True. - The flag WRITEABLE can only be set True if the array owns its own memory - or the ultimate owner of the memory exposes a writeable buffer interface - (or is a string). - The exception for string is made so that unpickling can be done without - copying memory. - -\end_layout - -\begin_layout Description -fill -\begin_inset LatexCommand index -name "ndarray!methods!fill" - -\end_inset - - (scalar) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Fill an array with the scalar value (appropriately converted to the type - of self). - If the scalar value is an array or a sequence, then only the first element - is used. - This method is usually faster than a[...]=scalar or self.flat=scalar, and always - interprets its argument as a scalar. -\end_layout - -\begin_layout Standard -\begin_inset Float table -wide false -sideways false -status open - -\begin_layout Standard -\begin_inset Caption - -\begin_layout Standard -Array conversion methods -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -setlength{ -\backslash -extrarowheight}{0.1eM} -\end_layout - -\begin_layout Standard - -\end_layout - -\begin_layout Standard - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\align center -\begin_inset Tabular -<lyxtabular version="3" rows="15" columns="3"> -<features> -<column alignment="center" valignment="top" leftline="true" width="0"> -<column alignment="center" valignment="top" leftline="true" width="30text%"> -<column alignment="center" valignment="top" leftline="true" rightline="true" width="0"> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family sans -\series bold -\size large -Method -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family sans -\series bold -\size large -Arguments -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family sans -\series bold -\size large -Description -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -astype -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(dtype {None}) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Cast to another data type -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -byteswap -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(inplace {False}) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Byteswap array elements -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -copy -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -() -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Copy array -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -dump -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(file) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Pickle to stream or file -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -dumps -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -() -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Get pickled string -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -fill -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(scalar) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Fill an array with scalar value -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -getfield -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(dtype=, offset=0) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Return a field of the array -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -setflags -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(write=None, align=None, uic=None) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Set array flags -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -tofile -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(file=, sep='', format='') -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Raw write to file -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -tolist -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -() -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Array as a nested list -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -item -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(*args) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Python scalar extraction -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -itemset -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(*args) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Insert scalar (last argument) into array -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -tostring -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(order='C') -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -String of raw memory -\end_layout - -\end_inset -</cell> -</row> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -view -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(obj) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -View as another data type or class -\end_layout - -\end_inset -</cell> -</row> -</lyxtabular> - -\end_inset - - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Array shape manipulation -\end_layout - -\begin_layout Standard -For reshape, resize, and transpose, the single tuple argument may be replaced - with -\begin_inset Formula $n$ -\end_inset - - integers which will be interpreted as an -\begin_inset Formula $n$ -\end_inset - --tuple. -\end_layout - -\begin_layout Description -reshape -\begin_inset LatexCommand index -name "ndarray!methods!reshape" - -\end_inset - - (newshape, order='C') -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an array that uses the same data as this array but has a new shape - given by the newshape tuple (or a scalar to reshape as 1-d). - The new shape must define an array with the same total number of elements. - If one of the elements of the new shape tuple is -1, then that dimension - will be determined such that the overall number of items in the array stays - constant. - If possible, the new array will reference the data of the old one. - If the data must be moved in order to accomplish the reshape, then then - the new array will contain a copy of the data in self. - The order argument specifies how the array data should be viewed during - the reshape (either in 'C' or 'FORTRAN' order). - This order argument specifies both how the intrinsic raveling to a 1-d - array should occur as well as how that 1-d array should be used to fill-up - the new output array. - -\end_layout - -\begin_layout Description -resize -\begin_inset LatexCommand index -name "ndarray!methods!resize" - -\end_inset - - (newshape, refcheck=1, order='C') -\end_layout - -\begin_layout Description -\InsetSpace ~ - Resize an array in-place. - This changes self (in-place) to be an array with the new shape, reallocating - space for the data area if necessary. - If the data memory must be changed because the number of new elements is - different than self.size, then an error will occur if this array does not - own its data or if another object is referencing this one. - Only a single-segment array can be resized. - The method returns None. - To bypass the reference count check, then set refcheck=0. - The purpose of the reference count check is to make sure you don't use - this array as a buffer for another Python object and then reallocate the - memory. - However, reference counts can increase in other ways so if you are sure - that you have not shared the memory for this array to another Python object, - then you may safely set refcheck=0. - -\end_layout - -\begin_layout Description -transpose -\begin_inset LatexCommand index -name "ndarray!methods!transpose" - -\end_inset - - (<None>) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an array view with the shape transposed according to the argument. - An argument of None is equivalent to range(self.ndim)[::-1]. - The argument can either be a tuple or multiple integer arguments. - This method returns a new array with permuted shape and strides attributes - using the same data as self. - -\end_layout - -\begin_layout MyCode ->>> a = arange(40).reshape((2,4,5)) -\newline ->>> b = a.transpose(2,0,1) -\newline ->>> print a.shape, - b.shape -\newline -(2, 4, 5) (5, 2, 4) -\newline ->>> print a.strides, b.strides -\newline -(80, 20, 4) (4, 80, - 20) -\newline ->>> print a -\newline -[[[ 0 1 2 3 4] -\newline - [ 5 6 7 8 9] -\newline - [10 11 12 13 14] -\newline - [15 - 16 17 18 19]] -\newline - -\newline - [[20 21 22 23 24] -\newline - [25 26 27 28 29] -\newline - [30 31 32 33 34] -\newline - [35 - 36 37 38 39]]] -\newline ->>> print b -\newline -[[[ 0 5 10 15] -\newline - [20 25 30 35]] -\newline - -\newline - [[ 1 6 11 16] -\newline - - [21 26 31 36]] -\newline - -\newline - [[ 2 7 12 17] -\newline - [22 27 32 37]] -\newline - -\newline - [[ 3 8 13 18] -\newline - [23 28 33 - 38]] -\newline - -\newline - [[ 4 9 14 19] -\newline - [24 29 34 39]]] -\end_layout - -\begin_layout Description -swapaxes -\begin_inset LatexCommand index -name "ndarray!methods!swapaxes" - -\end_inset - - (axis1, axis2) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an array view with axis1 and axis2 swapped. - This is a special case of the transpose method with argument equal to arg=range -(self.ndim); arg[axis1], arg[axis2] = arg[axis2], arg[axis1]. - See the -\series bold -rollaxis -\series default - function for a routine that transposes the array with the axes rolled instead - of swapped. - -\end_layout - -\begin_layout Description -flatten -\begin_inset LatexCommand index -name "ndarray!methods!flatten" - -\end_inset - - (order='C') -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a new 1-d array with data copied from self. - Equivalent to but slightly faster then a.flat.copy(). - -\end_layout - -\begin_layout Description -ravel -\begin_inset LatexCommand index -name "ndarray!methods!ravel" - -\end_inset - - (order='C') -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a 1-d version of self. - If self is single-segment, then the new array references self, otherwise, - a copy is made. -\end_layout - -\begin_layout Description -squeeze -\begin_inset LatexCommand index -name "ndarray!methods!squeeze" - -\end_inset - - () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an array with all unit-length dimensions squeezed out. -\end_layout - -\begin_layout Subsection -Array item selection and manipulation -\end_layout - -\begin_layout Standard -For array methods that take an axis keyword, it defaults to None. - If axis is None, then the array is treated as a 1-D array. - Any other value for axis represents the dimension along which the operation - should proceed. - -\end_layout - -\begin_layout Description -take -\begin_inset LatexCommand index -name "ndarray!methods!take" - -\end_inset - - (indices=, axis=None, out=None, mode='raise') -\end_layout - -\begin_layout Description -\InsetSpace ~ - The functionality of this method is available using the advanced indexing - ability of the -\family typewriter -ndarray -\family default - object. - However, for doing selection along a single axis it is usually faster to - use take. - If axis is not None, this method is equivalent to -\family typewriter -self[indxobj] -\family default - preceeded by -\family typewriter -indxobj=[slice(None)]*self.ndim; indxobj[ -\series bold -axis -\series default -] = -\family default - -\family typewriter -\series bold -indices -\family default -\series default -. - It returns the elements or sub-arrays from self indicated by the index - numbers in indices. - If axis is None, then this method is equivalent to -\family typewriter -self.flat[indices] -\family default -. - The out and mode arguments allow for specification of the output array - and how out-of-bounds indices will be handled ('raise': raise an error, - 'wrap': wrap around, 'clip': clip to range) -\end_layout - -\begin_layout Description -put -\begin_inset LatexCommand index -name "ndarray!methods!put" - -\end_inset - - (indices=, values=, mode='raise') -\end_layout - -\begin_layout Description -\InsetSpace ~ - Performs the equivalent of -\end_layout - -\begin_layout LyX-Code -for n in -\series bold -indices -\series default -: -\end_layout - -\begin_layout LyX-Code - self.flat[n] = -\series bold -values -\series default -[n] -\end_layout - -\begin_layout Description -\InsetSpace ~ - Values is repeated if it is too short. - The mode argument specifies what to do if n is too large. - -\end_layout - -\begin_layout Description -repeat -\begin_inset LatexCommand index -name "ndarray!methods!repeat" - -\end_inset - - (repeats=, axis=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Copy elements (or sub-arrays selected along axis) of self -\series bold -repeats -\series default - times. - The repeats argument must be a sequence of length self.shape[axis] or a - scalar. - The repeats argument dictates how many times the element (or sub-array) - will be repeated in the result array. - -\end_layout - -\begin_layout Description -choose -\begin_inset LatexCommand index -name "ndarray!methods!choose" - -\end_inset - - (choices, out=None, mode='raise') -\end_layout - -\begin_layout Description -\InsetSpace ~ - The array must be an integer (or bool) array with entries from -\begin_inset Formula $0$ -\end_inset - - to -\begin_inset Formula $n$ -\end_inset - -. - Choices is a tuple of -\begin_inset Formula $n$ -\end_inset - - choice arrays: -\begin_inset Formula $b0,\, b1,\,\ldots\,,\, bn$ -\end_inset - -. - (Alternatively, choices can be replaced with -\begin_inset Formula $n$ -\end_inset - - arguments where each argument is a choice array). - The return array will be formed from the elements of the choice arrays - according to the value of the elements of self. - In other words, the output array will merge the choice arrays together - by using the value of self at a particular position to select which choice - array should be used for the output at a particular position. - The out keyword allows specification of an output array and the clip keyword - allows different behavior when self contains entries outside the number - of choices. - The acceptable arguments to mode are 'raise' (RAISE), 'wrap' (WRAP), and - 'clip' (CLIP) ('raise' produces an error, 'wrap' converts the number into - range by periodic wrapping so that numbers <0 have -\begin_inset Formula $n$ -\end_inset - - repeatedly added and numbers >= -\begin_inset Formula $n$ -\end_inset - - have -\begin_inset Formula $n$ -\end_inset - - repeatedly subtracted, and 'clip' will clip all entries to be within the - range [0, -\begin_inset Formula $n$ -\end_inset - -). -\end_layout - -\begin_layout MyCode ->>> a = array([0,3,2,1]) -\newline ->>> a.choose([0,1,2,3],[10,11,12,13], -\newline -... - [20,21,22,23],[30,31,32,33]) -\newline -array([ 0, 31, 22, 13]) -\end_layout - -\begin_layout Description -sort -\begin_inset LatexCommand index -name "ndarray!methods!sort" - -\end_inset - - (axis=-1, kind='quick', order=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Sort the array in-place and return None. - The sort takes place over the given axis using an underlying sort algorithm - specified by kind. - The sorting algorithms available are 'quick', 'heap', and 'merge'. - For flexible types only the quicksort algorithm is available. - For arrays with fields defined, the order keyword allows specification - of the order in which to use the field names in the sort. - If order is a string then it is the field name to use to define the sort. - If order is a list (or tuple) of strings, then it specifies a lexicographic - ordering so that the first listed field name is compared first if that - results in equality, the second listed field name is used for the comparison - and so on. - If order is None, then arrays with fields use the first field for comparison. - -\end_layout - -\begin_layout MyCode ->>> a=array([[0.2,1.3,2.5],[1.5,0.1,1.4]]); -\newline ->>> b=a.copy(); b.sort(0); print b -\newline -[[ - 0.2 0.1 1.4] -\newline - [ 1.5 1.3 2.5]] -\newline ->>> b=a.copy(); b.sort(1); print b -\newline -[[ 0.2 1.3 2.5] -\newline - - [ 0.1 1.4 1.5]] -\end_layout - -\begin_layout Description -argsort -\begin_inset LatexCommand index -name "ndarray!methods!argsort" - -\end_inset - - (axis=-1, kind='quick', order=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an index array of the same size as self showing which indices along - the given axis should be selected to sort self along that axis. - Uses an underlying sort algorithm specified by kind. - The sorting algorithms available are 'quick', 'heap', and 'merge'. - For arrays with fields defined, the order keyword allows specification - of the order in which to use the field names in the sort. - If order is a string then it is the field name to use to define the sort. - If order is a list (or tuple) of strings, then it specifies a lexicographic - ordering so that the first listed field name is compared first if that - results in equality, the second listed field name is used for the comparison - and so on. - If order is None, then arrays with fields use the first field for comparison. - -\end_layout - -\begin_layout MyCode ->>> b=a.copy(); print b.argsort(0) -\newline -[[0 1 1] -\newline - [1 0 0]] -\newline ->>> b=a.copy(); print b.argsort(1 -) -\newline -[[0 1 2] -\newline - [1 2 0]] -\end_layout - -\begin_layout Tip -Complex valued arrays sort lexicographically by comparing first the real - parts and then the imaginary parts if the real parts are the same. -\end_layout - -\begin_layout Description -searchsorted -\begin_inset LatexCommand index -name "ndarray!methods!searchsorted" - -\end_inset - - (values, side='left') -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an index array (dtype=intp) of the same shape as values showing - the index where the value would fit in self. - The index is such that self[index-1] -\begin_inset Formula $<$ -\end_inset - - value -\begin_inset Formula $\le$ -\end_inset - - self[index] when side is 'left'. - In this formula self[self.size]= -\begin_inset Formula $\infty$ -\end_inset - - and self[-1]= -\begin_inset Formula $-\infty$ -\end_inset - -. - Therefore, if value is larger than all elements of self, then index is - self.size. - If value is smaller than all elements of self, then index is 0. - Self must be a sorted 1-d array. - If elements of self are repeated, the index of the first occurrence is - used. - If side is 'right', then the search rule is switched so that the -\begin_inset Formula $<$ -\end_inset - - sign is on the -\begin_inset Quotes eld -\end_inset - -right -\begin_inset Quotes erd -\end_inset - - instead of the left in the search rule. - In other words, the index returned is such that self[index-1] -\begin_inset Formula $\le$ -\end_inset - -value -\begin_inset Formula $<$ -\end_inset - - self[index]. -\end_layout - -\begin_layout MyCode ->>> b=a.ravel(); b.sort() -\newline ->>> b.searchsorted([0.0, 1.35, 2.0, 3.0]) -\newline -array([0, 3, - 5, 6]) -\end_layout - -\begin_layout Description -nonzero -\begin_inset LatexCommand index -name "ndarray!methods!nonzero" - -\end_inset - - () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the -\begin_inset Formula $n$ -\end_inset - --dimensional indices for elements of the -\begin_inset Formula $n$ -\end_inset - --dimensional array self that are nonzero into an -\begin_inset Formula $n$ -\end_inset - --tuple of equal-length index arrays. - In particular, notice that a 0-dimensional array always returns an empty - tuple. - -\end_layout - -\begin_layout MyCode ->>> x = arange(15); y=x.reshape(3,5) -\newline ->>> (x>8).nonzero() -\newline -(array([ 9, 10, 11, - 12, 13, 14]),) -\newline ->>> (y>8).nonzero() -\newline -(array([1, 2, 2, 2, 2, 2]), array([4, 0, - 1, 2, 3, 4])) -\end_layout - -\begin_layout Description -compress -\begin_inset LatexCommand index -name "ndarray!methods!compress" - -\end_inset - - (condition=, axis=None, out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This method expects condition to be a one-dimensional mask array of the - same length as self.shape[axis]. - If the array is less than self.shape[axis], then False is assumed for the - missing elements. - The method returns the elements (or sub-arrays along the given axis) of - self where condition is true. - The shape of the return array is self.shape with the axis dimension replaced - by the number of True elements of condition. - The same effect can often be accomplished using array indexing. -\end_layout - -\begin_layout MyCode ->>> x=array([0,1,2,3]) -\newline ->>> x.compress(x > 2) -\newline -array([3]) -\newline ->>> x[x>2] -\newline -array([3]) -\end_layout - -\begin_layout Description -diagonal -\begin_inset LatexCommand index -name "ndarray!methods!diagonal" - -\end_inset - - (offset=0, axis1=0, axis2=1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - If self is 2-d, return the -\series bold -offset -\series default - (from the main diagonal) diagonal of self. - If self is larger than 2-d, then return an array constructed from all the - diagonals created from all the 2-d sub-arrays formed using all of axis1 - and axis2. - The offset parameter is with respect to axis2. - The shape of the returned array is found by removing the axis1 and axis2 - entries from self.shape and then appending the length of the offset diagonal - of each 2-d sub-array. -\end_layout - -\begin_layout MyCode ->>> a=arange(25).reshape(5,5); print a -\newline -[[ 0 1 2 3 4] -\newline - [ 5 6 7 8 9] -\newline - - [10 11 12 13 14] -\newline - [15 16 17 18 19] -\newline - [20 21 22 23 24]] -\newline ->>> print a.diagonal() -\newline -[ - 0 6 12 18 24] -\newline ->>> print a.diagonal(1) -\newline -[ 1 7 13 19] -\newline ->>> print a.diagonal(-1) -\newline -[ - 5 11 17 23] -\end_layout - -\begin_layout Standard -\begin_inset Float table -wide false -sideways false -status open - -\begin_layout Standard -\begin_inset Caption - -\begin_layout Standard -Array item selection and shape manipulation methods. - If axis is an argument, then the calculation is performed along that axis. - An axis value of None means the array is flattened before calculation proceeds. -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -setlength{ -\backslash -extrarowheight}{0.25eM} -\end_layout - -\begin_layout Standard - -\end_layout - -\begin_layout Standard - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\align center -\begin_inset Tabular -<lyxtabular version="3" rows="18" columns="3"> -<features> -<column alignment="center" valignment="top" leftline="true" width="0"> -<column alignment="center" valignment="top" leftline="true" width="50text%"> -<column alignment="block" valignment="top" leftline="true" rightline="true" width="30text%"> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family sans -\series bold -\size large -Method -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family sans -\series bold -\size large -Arguments -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family sans -\series bold -\size large -Description -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -argsort -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -argsort (axis=None, kind='quick') -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Indices showing how to sort array. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -choose -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -choose (c0, c1 , ..., cn, out=None, clip='raise') -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Choose from different arrays based on value of self. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -compress -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(condition=, axis=None, out=None) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Elements of self where condition is true. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -diagonal -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(offset=0, axis1=0, axis2=1) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Return a diagonal from self. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -flatten -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(order='C') -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -A 1-d copy of self. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -nonzero -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -() -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -True where self is not zero. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -put -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(indices=, values=, mode='raise') -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Place values at 1-d index locations of self. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -ravel -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(order='C') -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -1-d version of self (no data copy if self is C-style contiguous). -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -repeat -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(repeats=, axis=None) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Repeat elements of self. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -reshape -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(d1,d2,...,dn, order='C') -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Return reshaped version of self. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -resize -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(d1,d2,...,dn, refcheck=1, order='Any') -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Resize self in-place. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -searchsorted -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(values) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Show where values would be placed in self (assumed sorted). -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -sort -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(axis=None, kind='quick') -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Copy of self sorted along axis. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -squeeze -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -() -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Squeeze out all length-1 dimensions. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -swapaxes -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(axis1, axis2) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Swap two dimensions of self. - -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -take -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(indices=, axis=None, out=None, mode='raise') -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Select elements of self along axis according to indices. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -transpose -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(permute <None>) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Rearrange shape of self according to permute. -\end_layout - -\end_inset -</cell> -</row> -</lyxtabular> - -\end_inset - - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Array calculation -\end_layout - -\begin_layout Standard -Many of these methods take an argument named axis. - In such cases, if axis is None (the default), the array is treated as a - 1-d array and the operation is performed over the entire array. - This behavior is also the default if self is a 0-dimensional array or array - scalar. - If axis is an integer, then the operation is done over the given axis (for - each 1-d subarray that can be created along the given axis). - The parameter dtype specifies the data type over which a reduction operation - (like summing) should take place. - The default reduce data type is the same as the data type of self. - To avoid overflow, it can be useful to perform the reduction using a larger - data type. - For several methods, an optional out argument can be provided and the result - will be placed into the output array given. - The out argument must be an ndarray and have the same number of elements. - It can be of a different type in which case casting will be performed. - -\end_layout - -\begin_layout Description -max -\begin_inset LatexCommand index -name "ndarray!methods!max" - -\end_inset - - (axis=None, out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the largest value in self. - This is a better way to compute the maximum over an array, than using max(self). - The latter uses the generic sequence interface to self. - This will be slower, and will try to get an answer by comparing whole sub-array -s of self. - This will be incorrect for arrays larger than 1-d. -\end_layout - -\begin_layout Description -argmax -\begin_inset LatexCommand index -name "ndarray!methods!argmax" - -\end_inset - - (axis=None, out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the (first, 1-d) index of the largest value in self. -\end_layout - -\begin_layout Description -min -\begin_inset LatexCommand index -name "ndarray!methods!min" - -\end_inset - - (axis=None, out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the smallest value in self. - This is a better way to compute the minimum over an array, than using min(self). - The latter uses the generic sequence interface to self. - This will be slower, and will try to get an answer by comparing whole sub-array -s of self. - This will be incorrect for arrays larger than 1-d. -\end_layout - -\begin_layout Description -argmin -\begin_inset LatexCommand index -name "ndarray!methods!argmin" - -\end_inset - - (axis=None, out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the (first, 1-d) index of the smallest value in self. -\end_layout - -\begin_layout Description -ptp -\begin_inset LatexCommand index -name "ndarray!methods!ptp" - -\end_inset - - (axis=None, out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the difference of the largest to the smallest value in self. - Equivalent to self.max(axis) - self.min(axis) -\end_layout - -\begin_layout Description -clip -\begin_inset LatexCommand index -name "ndarray!methods!clip" - -\end_inset - - (min=,max=, out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a new array where any element in self less than min is set to min - and any element less than max is set to max. - Equivalent to self[self<min]=min; self[self>max]=max. -\end_layout - -\begin_layout Description -conj -\begin_inset LatexCommand index -name "ndarray!methods!conj" - -\end_inset - - (out=None) -\end_layout - -\begin_layout Description -conjugate -\begin_inset LatexCommand index -name "ndarray!methods!conjugate" - -\end_inset - - (out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the conjugate of elements of the array. -\end_layout - -\begin_layout Description -round -\begin_inset LatexCommand index -name "ndarray!methods!round" - -\end_inset - - (decimals=0, out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Round the elements of the array to the nearest decimal. - For decimals < 0, the rounding is done to the nearest tens, hundreds, etc. - Rounding of exactly the half-interval is to the nearest even integer. - This is the only difference with standard Python rounding. -\end_layout - -\begin_layout Description -trace -\begin_inset LatexCommand index -name "ndarray!methods!trace" - -\end_inset - - (offset=0, axis1=0, axis2=1, dtype=None, out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Perform a summation along each diagonal specified by offset, axis1, and - axis2. - Equivalent to diagonal(offset,axis1,axis2).sum(axis=-1, dtype=dtype) -\end_layout - -\begin_layout Description -sum -\begin_inset LatexCommand index -name "ndarray!methods!sum" - -\end_inset - - (axis=None, dtype=None, out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the sum -\begin_inset Formula \[ -\sum_{i=0}^{N-1}\textrm{self}[\underbrace{:,\ldots,:}_{\textrm{axis}},i]\] - -\end_inset - - where axis ':' objects are placed before the -\begin_inset Formula $i.$ -\end_inset - - -\end_layout - -\begin_layout Description -cumsum -\begin_inset LatexCommand index -name "ndarray!methods!cumsum" - -\end_inset - - (axis=None, dtype=None, out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the cumulative sum. - If ret is the return array of the same shape as -\begin_inset Formula $\textrm{self},$ -\end_inset - - then -\begin_inset Formula \[ -\textrm{ret}[\underbrace{:,\ldots,:}_{\textrm{axis}},j]=\sum_{i=0}^{j}\textrm{self}[\underbrace{:,\ldots,:}_{\textrm{axis}},i].\] - -\end_inset - - -\end_layout - -\begin_layout Description -mean -\begin_inset LatexCommand index -name "ndarray!methods!mean" - -\end_inset - - (axis=None, dtype=None, out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the average value caculated as -\begin_inset Formula \[ -\frac{1}{N}\sum_{i=0}^{N-1}\textrm{self}[\underbrace{:,\ldots,:}_{\textrm{axis}},i]\] - -\end_inset - - where -\begin_inset Formula $N$ -\end_inset - - is self.shape[axis] and axis ':' objects are placed before the -\begin_inset Formula $i.$ -\end_inset - - The sum is done in the data-type of self unless self is an integer or Boolean - data-type and then it is done over the float data-type. - -\end_layout - -\begin_layout Description -var -\begin_inset LatexCommand index -name "ndarray!methods!var" - -\end_inset - - (axis=None, dtype=None, out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the variance of the data calculated as -\begin_inset Formula \[ -\frac{1}{N}\sum_{i=0}^{N-1}\left(\textrm{self}[\underbrace{:,\ldots,:}_{\textrm{axis}},i]-\mu\right)^{2}\] - -\end_inset - - where -\begin_inset Formula $N$ -\end_inset - - is self.shape[axis] and -\begin_inset Formula $\mu$ -\end_inset - - is the mean (restored to the same number of dimensions as self with -\begin_inset Formula $\mu$ -\end_inset - - copied along the axis dimension). - This is equivalent to (self**2).mean - self.mean()**2 and ((self-self.mean())**2).m -ean(). - The value of -\begin_inset Formula $N-1$ -\end_inset - - was not chosen for normalization because while it gives an -\begin_inset Quotes eld -\end_inset - -unbiased -\begin_inset Quotes erd -\end_inset - - estimate, it is not always prudent to return unbiased estimates as they - may have larger mean-square error. - The sum is done using a float data-type if self has integer or Boolean - data-type, otherwise it is done using the same data-type as self. - -\end_layout - -\begin_layout Description -std -\begin_inset LatexCommand index -name "ndarray!methods!std" - -\end_inset - - (axis=None, dtype=None, out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the standard deviation calculated as -\begin_inset Formula \[ -\sqrt{\frac{1}{N}\sum_{i=0}^{N-1}\left(\textrm{self}[\underbrace{:,\ldots,:}_{\textrm{axis}},i]-\mu\right)^{2}}\] - -\end_inset - - where -\begin_inset Formula $N$ -\end_inset - - is self.shape[axis] and -\begin_inset Formula $\mu$ -\end_inset - - is the mean (restored to the same number of dimensions as self with -\begin_inset Formula $\mu$ -\end_inset - - copied along the axis dimension). - The sum is done using the same data-type as self unless self is an integer - or Boolean data-type and then it is done using a float data-type. - -\end_layout - -\begin_layout Description -prod -\begin_inset LatexCommand index -name "ndarray!methods!prod" - -\end_inset - - (axis=None, dtype=None, out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the product calculated as -\begin_inset Formula \[ -\prod_{i=0}^{N-1}\textrm{self}[\underbrace{:,\ldots,:}_{\textrm{axis}},i].\] - -\end_inset - - -\end_layout - -\begin_layout Description -cumprod -\begin_inset LatexCommand index -name "ndarray!methods!cumprod" - -\end_inset - - (axis=None, dtype=None, out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the cumulative product so that the return array, ret, is the same - shape as self and -\begin_inset Formula \[ -\textrm{ret}[\underbrace{:,\ldots,:}_{\textrm{axis}},j]=\prod_{i=0}^{j}\textrm{self}[\underbrace{:,\ldots,:}_{\textrm{axis}},i].\] - -\end_inset - - -\end_layout - -\begin_layout Description -all -\begin_inset LatexCommand index -name "ndarray!methods!all" - -\end_inset - - (axis=None, out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return True if all entries along axis evaluate True, otherwise return False. -\end_layout - -\begin_layout Description -any -\begin_inset LatexCommand index -name "ndarray!methods!any" - -\end_inset - - (axis=None, out=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return True if any entries along axis evaluate True, otherwise return False -\begin_inset LatexCommand index -name "ndarray!methods|)" - -\end_inset - -. -\end_layout - -\begin_layout Standard -\begin_inset Float table -wide false -sideways false -status open - -\begin_layout Standard -\begin_inset Caption - -\begin_layout Standard -Array object calculation methods. - If axis is an argument, then the calculation is performed along that axis. - An axis value of None means the array is flattened before calculation proceeds. - All of these methods can take an optional out= argument which can specify - the output array to write the results into. - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset ERT -status collapsed - -\begin_layout Standard - - -\backslash -setlength{ -\backslash -extrarowheight}{0.5eM} -\end_layout - -\begin_layout Standard - -\end_layout - -\begin_layout Standard - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\align center -\begin_inset Tabular -<lyxtabular version="3" rows="18" columns="3"> -<features> -<column alignment="center" valignment="top" leftline="true" width="0"> -<column alignment="center" valignment="top" leftline="true" width="30text%"> -<column alignment="center" valignment="top" leftline="true" rightline="true" width="0"> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family sans -\series bold -\size large -Method -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family sans -\series bold -\size large -Arguments -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\family sans -\series bold -\size large -Description -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -all -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(axis=None) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -true if all entries are true. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -any -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(axis=None) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -true if any entries are true. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -argmax -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(axis=None) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -index of largest value. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -argmin -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(axis=None) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -index of smallest value. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -clip -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(min=, max=) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -self[self>max]=max; self[self<min]=min -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -conj -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -() -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -complex conjugate -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -cumprod -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(axis=None, dtype=None) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -cumulative product -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -cumsum -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(axis=None, dtype=None) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -cumulative sum -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -max -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(axis=None) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -maximum of self -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -mean -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(axis=None, dtype=None) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -mean of self -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -min -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(axis=None) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -minimum of self -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -prod -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(axis=None, dtype=None) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -multiply elements of self together -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -ptp -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(axis=None) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -self.max(axis)-self.min(axis) -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -var -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(axis=None, dtype=None) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -variance of self -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -std -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(axis=None, dtype=None) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -standard deviation of self -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -sum -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(axis=None, dtype=None) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -add elements of self together -\end_layout - -\end_inset -</cell> -</row> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard - -\series bold -trace -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -(offset, axis1=0, axis2=0, dtype=None) -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -sum along a diagonal -\end_layout - -\end_inset -</cell> -</row> -</lyxtabular> - -\end_inset - - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Section -Array Special Methods -\end_layout - -\begin_layout Standard -Methods -\begin_inset LatexCommand index -name "ndarray!special methods|(" - -\end_inset - - in this chapter are not generally meant to be called directly by the user. - They are called by Python and are used to customize behavior of the ndarray - object as it interacts with the Python language and standard library. - -\end_layout - -\begin_layout Subsection -Methods for standard library functions -\end_layout - -\begin_layout Description -__copy__ -\begin_inset LatexCommand index -name "ndarray!special methods!copy" - -\end_inset - - () -\end_layout - -\begin_layout Description -\InsetSpace ~ - To allow copy.copy(a) to perform a shallow copy of an array. - Exactly the same as self.copy() (contents of object arrays are not copied). - -\end_layout - -\begin_layout Description -__deepcopy__ -\begin_inset LatexCommand index -name "ndarray!special methods!deepcopy" - -\end_inset - - (memodict) -\end_layout - -\begin_layout Description -\InsetSpace ~ - To allow copy.deepcopy(a) to perform a deep copy. - This is the same as a shallow copy unless self is an object array. - Then, after the shallow copy is made, a copy.deepcopy(item) is called for - every item in the object array. - -\end_layout - -\begin_layout Description -__reduce__ -\begin_inset LatexCommand index -name "ndarray!special methods!reduce" - -\end_inset - - () -\end_layout - -\begin_layout Description -__setstate__ -\begin_inset LatexCommand index -name "ndarray!special methods!setstate" - -\end_inset - - (shape, typestr, isfortran, data) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Pickling support for arrays is provided by these two methods. - When an array needs to be pickled, the __reduce__() method is called to - provide a 3-tuple of already-pickleable objects. - To construct a new object from the pickle, the first two elements of the - 3-tuple are used to construct a new (0-length) array of the correct type - and the last element of the 3-tuple, which is itself a 4-tuple of (shape, - typestr, isfortran, data) is passed to the __setstate__ method of the newly - created array to restore its contents. - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The reduce method returns a 3-tuple consisting of (callable, args, state) - where callable is a simple constructor function that handles subclasses - of the ndarray. - Also, args is a 3-tuple of arguments to pass to this constructor function - (type(self), (0,), self.dtypechar), and state is a 4-tuple of information - giving the object's state (self.shape, self.dtypedescr, isfortran, string_or_list -). - In this tuple, isfortran is a Bool stating whether the following flattened - data is in Fortran order or not, and string_or_list is a string formed - by self.tostring() if the data type is not object. - If the data type of self is an object array, then string_or_list is a flat - list equivalent to self.ravel().tolist(). - -\end_layout - -\begin_layout Description -\InsetSpace ~ - On load from a pickle, the pickling code uses the first two elements from - the tuple returned by reduce to construct an empty 0-dimensional subclass - of the correct type. - The last element is then passed to the __setstate__ method of the newly - created array to restore its contents. - -\end_layout - -\begin_layout Note -When data is a string, the __setstate__ method will directly use the string - memory as the array memory (new.base will point to the string). - The typestr contains enough information to decode how the memory should - be interpreted. -\end_layout - -\begin_layout Subsection -Basic customization -\end_layout - -\begin_layout Description -__new__ -\begin_inset LatexCommand index -name "ndarray!special methods!new" - -\end_inset - - (subtype, shape=, dtype=long_, buffer=None, offset=0, strides=None, order=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This method creates a new ndarray. - It is typically only used in the __new__ method of a subclass. - This method is called to construct a new array whenever the object name - is called, -\family typewriter -a=ndarray(...) -\family default -. - It supports two basic modes of array creation: -\end_layout - -\begin_layout Enumerate -a single-segment array of the specified shape and data-type from newly allocated - memory; -\end_layout - -\begin_deeper -\begin_layout Enumerate -uses shape, dtype, strides, and order arguments; others are ignored; -\end_layout - -\begin_layout Enumerate -The order argument allows specification of a Fortran-style contiguous memory - segment (order='Fortran'); -\end_layout - -\begin_layout Enumerate -If strides is given, then it specifies the new strides of the array (and - the order keyword is ignored). - The strides will be checked for consistency with the dimension size so - that steps outside of the memory won't occur. -\end_layout - -\end_deeper -\begin_layout Enumerate -an array of the given shape and data type using the provided object, buffer, - which must export the buffer interface. - -\end_layout - -\begin_deeper -\begin_layout Enumerate -all arguments can be used; -\end_layout - -\begin_layout Enumerate -strides can be given and will be checked for consistency with the shape, - data type, and available memory in buffer; -\end_layout - -\begin_layout Enumerate -order indicates whether the data buffer should be interpreted as Fortran-style - contiguous (order='Fortran') or not; -\end_layout - -\begin_layout Enumerate -offset can be used to start the array data at some offset in the buffer. - -\end_layout - -\end_deeper -\begin_layout Note -The ndarray uses the default no-op __init__ -\begin_inset LatexCommand index -name "ndarray!special methods!init" - -\end_inset - - function because the array is completely initialized after __new__ is called. -\end_layout - -\begin_layout Description -__array__ -\begin_inset LatexCommand index -name "ndarray!special methods!array" - -\end_inset - - (dtype {None}) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This is a special method that should always return an object of type ndarray. - Useful for subclasses that need to get to the ndarray object. - -\end_layout - -\begin_layout Description -__array_wrap__ -\begin_inset LatexCommand index -name "ndarray!special methods!array\\_wrap" - -\end_inset - - (arr) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This is a special method that always returns an object of the same Python - type as self using the array passed as an argument. - This is mainly useful for subclasses as it is an easy way to get the subclass - back from an ndarray. -\end_layout - -\begin_layout Description -__lt__ -\begin_inset LatexCommand index -name "ndarray!special methods!lt" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__le__ -\begin_inset LatexCommand index -name "ndarray!special methods!le" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__gt__ -\begin_inset LatexCommand index -name "ndarray!special methods!gt" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__ge__ -\begin_inset LatexCommand index -name "ndarray!special methods!ge" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__eq__ -\begin_inset LatexCommand index -name "ndarray!special methods!eq" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__ne__ -\begin_inset LatexCommand index -name "ndarray!special methods!ne" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Defined to support rich comparisons (<, <=, >, >=, ==, !=) on ndarrays - using universal functions. - -\end_layout - -\begin_layout Description -__str__ -\begin_inset LatexCommand index -name "ndarray!special methods!str" - -\end_inset - - () -\end_layout - -\begin_layout Description -__repr__ -\begin_inset LatexCommand index -name "ndarray!special methods!repr" - -\end_inset - - () -\end_layout - -\begin_layout Description -\InsetSpace ~ - These functions print the array when called by str(self) and repr(self) - respectively. - Array printing can be changed using set_string_function(..). - Default array printing has been borrowed from numarray whose printing code - was written by Perry Greenfield and J. - Todd Miller. - By default, arrays print such that -\end_layout - -\begin_layout Enumerate -The last axis is always printed left to right. -\end_layout - -\begin_layout Enumerate -The next-to-last axis is printed top to bottom. -\end_layout - -\begin_layout Enumerate -Remaining axes are printed top to bottom with increasing numbers of separators. -\end_layout - -\begin_layout Description -\InsetSpace ~ - Five parameters of the printing can be set using keyword arguments with - -\family typewriter -set_printoptions(...) -\family default -. - The parameters -\begin_inset LatexCommand index -name "set\\_printoptions" - -\end_inset - - can all be retrieved using -\family typewriter -get_printoptions() -\family default -. - These printing options -\begin_inset LatexCommand index -name "get\\_printoptions" - -\end_inset - - are -\end_layout - -\begin_deeper -\begin_layout Description -precision the number of digits of precision for floating point output (default - 8); -\end_layout - -\begin_layout Description -threshold total number of array elements which triggers summarization rather - than full representation (default 1000); -\end_layout - -\begin_layout Description -edgeitems number of array items in summary at beginning an end of each dimension - (default 3); -\end_layout - -\begin_layout Description -linewidth the number of characters per line for the purpose of inserting - line breaks (default 71); -\end_layout - -\begin_layout Description -suppress Boolean indicating whether or not to suppress printing of small - floating point values using scientific notation (default False). - -\end_layout - -\end_deeper -\begin_layout Description -__nonzero__ -\begin_inset LatexCommand index -name "ndarray!special methods!nonzero" - -\end_inset - - () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Truth-value testing for the array as a whole. - It is called whenever the truth value of the ndarray as a whole object - is required. - This raises an error if the number of elements in the the array is larger - than 1 because the truth value of such arrays is ambiguous. - Use .any() and .all() instead to be clear about what is meant in such cases. - If the number of elements is 0 then False is returned. - If there is one element in the array, then the truth-value of this element - is returned. -\end_layout - -\begin_layout Subsection -Container customization -\end_layout - -\begin_layout Description -__len__ -\begin_inset LatexCommand index -name "ndarray!special methods!len" - -\end_inset - - () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns self.shape[0]. - It is called in response to len(self). - Use self.size to get the total number of elements in the array. -\end_layout - -\begin_layout Description -\InsetSpace ~ - Notice that the default Python iterator for sequences is used when arrays - are used in places that expect an iterator. - This iterator returns successively self[0], self[1], ..., self[self.__len__()]. - Use self.flat to get an iterator that walks through the entire array one - element at a time. -\end_layout - -\begin_layout Description -__getitem__ -\begin_inset LatexCommand index -name "ndarray!special methods!getitem" - -\end_inset - - (key) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Called when evaluating self[key] construct. - Items from the array can be selected using this customization. - This construct has both standard and extended indexing abilities which - are explained in Section -\begin_inset LatexCommand ref -reference "sec:Array-indexing" - -\end_inset - -. - A named field can be retrieved if key is a string and fields are defined - in the dtypedescr object associated with this array. - -\end_layout - -\begin_layout Description -__setitem__ -\begin_inset LatexCommand index -name "ndarray!special methods!setitem" - -\end_inset - - (key, value) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Called when evaluating self[key]=value. - Items in the array can be set using this construct. - This construct is explained in Section -\begin_inset LatexCommand ref -reference "sec:Array-indexing" - -\end_inset - -. - A named field can be set if key is a string and fields are defined in the - dtypedescr object associated with this array. - -\end_layout - -\begin_layout Description -__getslice__ -\begin_inset LatexCommand index -name "ndarray!special methods!getslice" - -\end_inset - - (i, j) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Equivalent to self.__getitem__(slice(i,j)) but defined mainly so that C - code can use the sequence interface. - Called to evaluate self[i:j] -\end_layout - -\begin_layout Description -__setslice__ -\begin_inset LatexCommand index -name "ndarray!special methods!setslice" - -\end_inset - - (i, j, value) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Equivalent to self.__setitem__(slice(i,j), value) but defined mainly so - C code can use the sequence interface. - Called to evaluate self[i:j] = value. -\end_layout - -\begin_layout Description -__contains__ -\begin_inset LatexCommand index -name "ndarray!special methods!contains" - -\end_inset - - (item) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Called to determine truth value of the -\family typewriter -item in self -\family default - construct. - Returns the equivalent of (self==item).any() -\end_layout - -\begin_layout Subsection -Arithmetic customization -\end_layout - -\begin_layout Subsubsection -Binary -\end_layout - -\begin_layout Description -__add__ -\begin_inset LatexCommand index -name "ndarray!special methods!add" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__sub__ -\begin_inset LatexCommand index -name "ndarray!special methods!sub" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__mul__ -\begin_inset LatexCommand index -name "ndarray!special methods!mul" - -\end_inset - - (self, other) -\end_layout - -\begin_layout Description -__div__ -\begin_inset LatexCommand index -name "ndarray!special methods!div" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__truediv__ -\begin_inset LatexCommand index -name "ndarray!special methods!truediv" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__floordiv__ -\begin_inset LatexCommand index -name "ndarray!special methods!floordiv" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__mod__ -\begin_inset LatexCommand index -name "ndarray!special methods!mod" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__divmod__ -\begin_inset LatexCommand index -name "ndarray!special methods!divmod" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__pow__ -\begin_inset LatexCommand index -name "ndarray!special methods!pow" - -\end_inset - - (other[,modulo]) -\end_layout - -\begin_layout Description -__lshift__ -\begin_inset LatexCommand index -name "ndarray!special methods!lshift" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__rshift__ -\begin_inset LatexCommand index -name "ndarray!special methods!rshift" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__and__ -\begin_inset LatexCommand index -name "ndarray!special methods!and" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__or__ -\begin_inset LatexCommand index -name "ndarray!special methods!or" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__xor__ -\begin_inset LatexCommand index -name "ndarray!special methods!xor" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -\InsetSpace ~ - These methods are defined for ndarrays to implement the operations ( -\family typewriter -+ -\family default -, -\family typewriter -- -\family default -, -\family typewriter -* -\family default -, -\family typewriter -/, -\family default - -\family typewriter -/, -\family default - -\family typewriter -// -\family default -, -\family typewriter -% -\family default -, -\family typewriter -divmod() -\family default -, -\family typewriter -** -\family default - or -\family typewriter -pow() -\family default -, -\family typewriter -<<, -\family default - -\family typewriter ->> -\family default -, -\family typewriter -& -\family default -, -\family typewriter -^ -\family default -, -\family typewriter -| -\family default -). - This is done using calls to the corresponding universal function object - (add, subtract, multiply, divide, true_divide, floor_divide, remainder, - divide and remainder, power, left_shift, right_shift, bitwise_and, bitwise_xor, - bitwise_or). - These implement element-by-element operations for arrays that are broadcastable - to the same shape. - -\end_layout - -\begin_layout Itemize -any third argument to -\family typewriter -pow() -\family default - is silently ignored as the underlying ufunc (power) only takes two arguments. -\end_layout - -\begin_layout Itemize -the three division operators are all defined, div is active by default, - truediv is active when __future__.division is in effect. -\end_layout - -\begin_layout Note -Because it is a built-in type (written in C), the __r<op>__ special methods - are not directly defined for the ndarray. -\end_layout - -\begin_layout Subsubsection -In-place -\end_layout - -\begin_layout Description -__iadd__ -\begin_inset LatexCommand index -name "ndarray!special methods!iadd" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__isub__ -\begin_inset LatexCommand index -name "ndarray!special methods!isub" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__imul__ -\begin_inset LatexCommand index -name "ndarray!special methods!imul" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__idiv__ -\begin_inset LatexCommand index -name "ndarray!special methods!idiv" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__itruediv__ -\begin_inset LatexCommand index -name "ndarray!special methods!itruediv" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__ifloordiv__ -\begin_inset LatexCommand index -name "ndarray!special methods!ifloordiv" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__imod__ -\begin_inset LatexCommand index -name "ndarray!special methods!imod" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__ipow__ -\begin_inset LatexCommand index -name "ndarray!special methods!ipow" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__ilshift__ -\begin_inset LatexCommand index -name "ndarray!special methods!ilshift" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__irshift__ -\begin_inset LatexCommand index -name "ndarray!special methods!irshift" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__iand__ -\begin_inset LatexCommand index -name "ndarray!special methods!iand" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__ixor__ -\begin_inset LatexCommand index -name "ndarray!special methods!ixor" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -__ior__ -\begin_inset LatexCommand index -name "ndarray!special methods!ior" - -\end_inset - - (other) -\end_layout - -\begin_layout Description -\InsetSpace ~ - These methods are implemented to handle the inplace operatiors ( -\family typewriter -+= -\family default -, -\family typewriter --= -\family default -, -\family typewriter -*= -\family default -, -\family typewriter -/= -\family default -, -\family typewriter -/= -\family default -, -\family typewriter -//= -\family default -, -\family typewriter -%= -\family default -, -\family typewriter -** -\family default -=, -\family typewriter -<< -\family default -=, -\family typewriter ->>= -\family default -, -\family typewriter -&= -\family default -, -\family typewriter -^= -\family default -, -\family typewriter -|= -\family default -). - The inplace operators are implemented using the corresponding ufunc and - its ability to take an output argument (which is set as self). - Using inplace operations can save space and time and is therefore encouraged - whenever appropriate. - -\end_layout - -\begin_layout Warning -In place operations will perform the calculation using the precision decided - by the data type of the two operands, but will silently downcast the result - (if necessary) so it can fit back into the array. - Therefore, for mixed precision calculations, a <op>= B can be different - than a = a <op> B. - For example, suppose a=ones((3,3)). - Then a+=3j is different than a=a+3j While they both perform the same computatio -n, a+=3j casts the result to fit back in a, while a=a+3j re-binds the name - a to the result. -\end_layout - -\begin_layout Subsubsection -Unary operations -\end_layout - -\begin_layout Description -__neg__ -\begin_inset LatexCommand index -name "ndarray!special methods!neg" - -\end_inset - - (self) -\end_layout - -\begin_layout Description -__pos__ -\begin_inset LatexCommand index -name "ndarray!special methods!pos" - -\end_inset - - (self) -\end_layout - -\begin_layout Description -__abs__ -\begin_inset LatexCommand index -name "ndarray!special methods!abs" - -\end_inset - - (self) -\end_layout - -\begin_layout Description -__invert__ -\begin_inset LatexCommand index -name "ndarray!special methods!invert" - -\end_inset - - (self) -\end_layout - -\begin_layout Description -\InsetSpace ~ - These functions are called in response to the unary operations ( -\family typewriter -- -\family default -, -\family typewriter -+ -\family default -, -\family typewriter -abs() -\family default -, -\family typewriter -~ -\family default -). - With the exception of __pos__, these are implemented using ufuncs (negative, - absolute, invert). - The unary -\family typewriter -+ -\family default - operator, however simply calls self.copy(), and can therefore be used to - get a copy of an array. - -\end_layout - -\begin_layout Description -__complex__ -\begin_inset LatexCommand index -name "ndarray!special methods!complex" - -\end_inset - - (self) -\end_layout - -\begin_layout Description -__int__ -\begin_inset LatexCommand index -name "ndarray!special methods!int" - -\end_inset - - (self) -\end_layout - -\begin_layout Description -__long__ -\begin_inset LatexCommand index -name "ndarray!special methods!long" - -\end_inset - - (self) -\end_layout - -\begin_layout Description -__float__ -\begin_inset LatexCommand index -name "ndarray!special methods!float" - -\end_inset - - (self) -\end_layout - -\begin_layout Description -__oct__ -\begin_inset LatexCommand index -name "ndarray!special methods!oct" - -\end_inset - - (self) -\end_layout - -\begin_layout Description -__hex__ -\begin_inset LatexCommand index -name "ndarray!special methods!hex" - -\end_inset - - (self) -\end_layout - -\begin_layout Description -\InsetSpace ~ - These functions are also defined for the -\family typewriter -ndarray -\family default - object to handle the operations -\family typewriter -complex() -\family default -, -\family typewriter -int() -\family default -, -\family typewriter -long() -\family default -, -\family typewriter -float() -\family default -, -\family typewriter -oct() -\family default -, and -\family typewriter -hex() -\family default -. - They work only on arrays that have one element in them and return the appropria -te scalar -\begin_inset LatexCommand index -name "ndarray!special methods|)" - -\end_inset - -. - -\end_layout - -\begin_layout Tip -The function called to implement many arithmetic special methods for arrays - can be modified using the function set_numeric_ops. - This function is called with keyword arguments indicating which operation(s) - to replace. - A dictionary is returned containing showing the old functions. - By default, these functions are set to the corresponding ufunc. - -\end_layout - -\begin_layout Section -Array indexing -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand label -name "sec:Array-indexing" - -\end_inset - - -\end_layout - -\begin_layout Standard -More powerful array -\begin_inset LatexCommand index -name "indexing|(" - -\end_inset - - indexing -\begin_inset LatexCommand index -name "ndarray!special methods!getitem" - -\end_inset - - was an important extension introduced by numarray, and was therefore an - important part of the development of NumPy. - In particular, the desire to select arbitrary elements based on their position - in the array, and according to a mask was desirable. - -\end_layout - -\begin_layout Standard -There are two kinds of indexing available using the -\family typewriter -X[obj] -\family default - syntax: basic slicing, and advanced indexing -\begin_inset LatexCommand index -name "ndarray!special methods!setitem" - -\end_inset - -. - For the description of this syntax given below, X is the array to-be-sliced - and obj is the -\emph on -selection -\emph default - object. - Furthermore, define -\begin_inset Formula $N\equiv$ -\end_inset - -X.ndim. - These two methods of slicing have different behavior and are triggered - depending on obj. - Adding additional functionality yet remaining compatible with old uses - of slicing complicated the rules a little. - Hopefully, after studying this section, you will have a firm grasp of what - kind of selection will be initiated depending on the selection object. -\end_layout - -\begin_layout Tip -in Python X[(exp1, exp2, ..., expN)] is equivalent to X[exp1, exp2, ..., expN] - as the latter is just syntactic sugar for the former. -\end_layout - -\begin_layout Subsection -Basic Slicing -\end_layout - -\begin_layout Standard -Basic slicing -\begin_inset LatexCommand index -name "ndarray!special methods!getslice" - -\end_inset - - extends Python's basic concept of slicing -\begin_inset LatexCommand index -name "ndarray!special methods!setslice" - -\end_inset - - to N dimensions. - Basic slicing occurs when obj is a slice object (constructed by start:stop:step - notation inside of brackets), an integer, or a tuple of slice objects and - integers. - Ellipsis and newaxis objects can be interspersed with these as well. - In order to remain backward compatible with a common usage in Numeric, - basic slicing is also initiated if the selection object is any sequence - (such as a list) containing slice objects, the ellipsis -\begin_inset LatexCommand index -name "ellipsis" - -\end_inset - - object, or the newaxis -\begin_inset LatexCommand index -name "newaxis" - -\end_inset - - object, but no integer arrays or other embedded sequences. - -\end_layout - -\begin_layout Standard -The standard rules of sequence slicing apply to basic slicing on a per-dimension - basis (including using a step index). - Some useful concepts to remember include: -\end_layout - -\begin_layout Itemize -The basic slice syntax is ' -\begin_inset Formula $i:j:k$ -\end_inset - -' where -\begin_inset Formula $i$ -\end_inset - - is the starting index, -\begin_inset Formula $j$ -\end_inset - - is the stopping index, and -\begin_inset Formula $k$ -\end_inset - - is the step ( -\begin_inset Formula $k\neq0$ -\end_inset - -). - This selects the -\begin_inset Formula $m$ -\end_inset - - elements (in the corresponding dimension) with index values -\begin_inset Formula $i,\, i+k,\,\ldots,\, i+(m-1)k$ -\end_inset - - where -\begin_inset Formula $m=q+(r\neq0)$ -\end_inset - - where -\begin_inset Formula $q$ -\end_inset - - and -\begin_inset Formula $r$ -\end_inset - - are the quotient and remainder obtained by dividing -\begin_inset Formula $j-i$ -\end_inset - - by -\begin_inset Formula $k$ -\end_inset - -: -\begin_inset Formula $j-i=qk+r$ -\end_inset - -, so that -\begin_inset Formula $i+\left(m-1\right)k<j.$ -\end_inset - - -\end_layout - -\begin_layout Itemize -Assume -\begin_inset Formula $n$ -\end_inset - - is the number of elements in the dimension being sliced. - Then, if -\begin_inset Formula $i$ -\end_inset - - is not given it defaults to 0 for -\begin_inset Formula $k>0$ -\end_inset - - and -\begin_inset Formula $n$ -\end_inset - - for -\begin_inset Formula $k<0$ -\end_inset - -. - If -\begin_inset Formula $j$ -\end_inset - - is not given it defaults to -\begin_inset Formula $n$ -\end_inset - - for -\begin_inset Formula $k>0$ -\end_inset - - and -\begin_inset Formula $-1$ -\end_inset - - for -\begin_inset Formula $k<0$ -\end_inset - -. - If -\begin_inset Formula $k$ -\end_inset - - is not given it defaults to 1. - Note that '::' is the same as ':' and means select all indices along this - axis. - -\end_layout - -\begin_layout Itemize -If the number of objects in the selection tuple is less than -\begin_inset Formula $N$ -\end_inset - -, then ':' is assumed for any remaining dimensions. -\end_layout - -\begin_layout Itemize -Ellipsis expand to the number of ':' objects needed to make a selection - tuple of the same length as X.ndim. - Only one ellipsis is expanded, any others are interpreted as more ':' -\end_layout - -\begin_layout Itemize -Each newaxis object in the selection tuple serves to expand the dimensions - of the resulting selection by one unit-length dimension. - The added dimension is the position of the newaxis object in the selection - tuple. - -\end_layout - -\begin_layout Itemize -An integer, -\begin_inset Formula $i$ -\end_inset - -, returns the same values as -\begin_inset Formula $i:i+1$ -\end_inset - - -\series bold -except -\series default - the dimensionality of the returned object is reduced by 1. - In particular, a selection tuple with the -\begin_inset Formula $p^{\textrm{th}}$ -\end_inset - - element an integer (and all other entries ':') returns the corresponding - sub-array with dimension -\begin_inset Formula $N-1$ -\end_inset - -. - If -\begin_inset Formula $N=1,$ -\end_inset - - then the returned object is an Array Scalar. - These objects are explained in Chapter -\begin_inset LatexCommand ref -reference "cha:Scalar-objects" - -\end_inset - -. -\end_layout - -\begin_layout Itemize -If the selection tuple has all entries ':' except the -\begin_inset Formula $p^{\textrm{th}}$ -\end_inset - - entry which is a slice object -\begin_inset Formula $i:j:k$ -\end_inset - -, then the returned array has dimension -\begin_inset Formula $N$ -\end_inset - - formed by concatenating the sub-arrays returned by integer indexing of - elements -\begin_inset Formula $i$ -\end_inset - -, -\begin_inset Formula $i+k$ -\end_inset - -, -\begin_inset Formula $i+(m-1)k<j$ -\end_inset - -, -\end_layout - -\begin_layout Itemize -Basic slicing with more than one non-':' entry in the slicing tuple, acts - like repeated application of slicing using a single non-':' entry, where - the non-':' entries are successively taken (with all other non-':' entries - replaced by ':'). - Thus, X[ind1,...,ind2,:] acts like X[ind1][...,ind2,:] under basic slicing. - Note this is NOT true for advanced slicing. - -\end_layout - -\begin_layout Itemize -You may use slicing to set values in the array, but (unlike lists) you can - never grow the array. - The size of the value to be set in X[obj] = value must be (broadcastable) - to the same shape as X[obj]. - -\end_layout - -\begin_layout Standard -Basic slicing always returns another -\emph on -view -\begin_inset LatexCommand index -name "ndarray!view" - -\end_inset - - -\emph default - of the array. - In other words, the returned array from a basic slicing operation uses - the same data as the original array. - This can be confusing at first, but it is faster and can save memory. - A copy can always be obtained if needed using the unary + operator (which - has lower precedence than slicing) or the .copy() method. - -\end_layout - -\begin_layout Tip -Remember that a slicing tuple can always be constructed as obj and used - in the x[obj] notation. - Slice objects can be used in the construction in place of the [start:stop:step] - notation. - For example, -\family typewriter -x[1:10:5,::-1] -\family default - can also be implemented as -\family typewriter -obj=(slice(1,10,5), slice(None,None,-1)); X[obj] -\family default -. - This can be useful for constructing generic code that works on arrays of - arbitrary dimension. -\end_layout - -\begin_layout Subsection -Advanced selection -\end_layout - -\begin_layout Standard -Advanced selection is triggered when the selection object, obj, is a non-tuple - sequence object, an ndarray (of data type integer or bool), or a tuple - with at least one sequence object or ndarray (of data type integer or bool). - There are two types of advanced indexing: integer and Boolean. - Advanced selection always returns a copy of the data (contrast with basic - slicing that returns a view). - -\end_layout - -\begin_layout Subsubsection -Integer -\end_layout - -\begin_layout Standard -Integer indexing allows selection of arbitrary items in the array based - on their -\begin_inset Formula $N$ -\end_inset - --dimensional index. - This kind of selection occurs when advanced selection is triggered and - the selection object is not an array of data type bool. - For the discussion below, when the selection object is not a tuple, it - will be referred to as if it had been promoted to a 1-tuple, which will - be called the selection tuple. - The rules of advanced integer-style indexing are: -\end_layout - -\begin_layout Itemize -if the length of the selection tuple is larger than -\begin_inset Formula $N$ -\end_inset - -(=X.ndim) an error is raised. -\end_layout - -\begin_layout Itemize -all sequences and scalars in the selection tuple are converted to intp indexing - arrays. - -\end_layout - -\begin_layout Itemize -all selection tuple objects must be convertible to intp arrays, or slice - objects, or the Ellipsis (...) object. -\end_layout - -\begin_layout Itemize -Exactly one Ellipsis object will be expanded, any other Ellipsis objects - will be treated as full slice (':') objects. - The Ellipsis object is replaced with as many full slice (':') objects as - needed to make the length of the selection tuple -\begin_inset Formula $N$ -\end_inset - -. - -\end_layout - -\begin_layout Itemize -If the selection tuple is smaller than -\begin_inset Formula $N$ -\end_inset - -, then as many ':' objects as needed are added to the end of the selection - tuple so that the modified selection tuple has length -\begin_inset Formula $N$ -\end_inset - -. -\end_layout - -\begin_layout Itemize -The shape of all the integer indexing arrays must be broadcastable to the - same shape. - Arrays are broadcastable if any of the following are satisfied -\end_layout - -\begin_deeper -\begin_layout Enumerate -The arrays all have exactly the same shape. -\end_layout - -\begin_layout Enumerate -The arrays all have the same number of dimensions and the length of each - dimensions is either a common length or 1. -\end_layout - -\begin_layout Enumerate -The arrays that have too few dimensions can have their shapes pre-pended - with a dimension of length 1 to satisfy property 2. - -\end_layout - -\end_deeper -\begin_layout Itemize -The shape of the output (or the needed shape of the object to be used for - setting) is the broadcasted shape. - -\end_layout - -\begin_deeper -\begin_layout Description -Example: If a.shape is (5,1), b.shape is (1,6), c.shape is (6,) and d.shape - is () so that d is a scalar, then a, b, c, and d are all broadcastable - to dimension (5,6). - The array -\begin_inset Quotes eld -\end_inset - -a -\begin_inset Quotes erd -\end_inset - - acts like a (5,6) array where a[:,0] is broadcast to the other columns, - -\begin_inset Quotes eld -\end_inset - -b -\begin_inset Quotes erd -\end_inset - - acts like a (5,6) array where b[0,:] is broadcast to the other rows, -\begin_inset Quotes eld -\end_inset - -c -\begin_inset Quotes erd -\end_inset - - acts like a (1,6) array and therefore a (5,6) where c[:] is broadcast to - every row, and finally -\begin_inset Quotes eld -\end_inset - -d -\begin_inset Quotes erd -\end_inset - - acts like a (5,6) array where the single values is repeated. - -\end_layout - -\end_deeper -\begin_layout Itemize -After expanding any ellipses and filling out any missing (':') objects in - the selection tuple, then let -\begin_inset Formula $N_{t}$ -\end_inset - - be the number of indexing arrays, and let -\begin_inset Formula $N_{s}=N-N_{t}$ -\end_inset - - be the number of slice objects. - Note that -\begin_inset Formula $N_{t}>0$ -\end_inset - - (or we wouldn't be doing advanced integer indexing). - -\end_layout - -\begin_layout Itemize -If -\begin_inset Formula $N_{s}=0$ -\end_inset - - then the -\begin_inset Formula $M$ -\end_inset - --dimensional result is constructed by varying the index tuple -\begin_inset Formula $\left(i_{1},\ldots,i_{M}\right)$ -\end_inset - - over the range of the result shape and for each value of the index tuple - setting: -\begin_inset Formula \[ -\textrm{result[$i_{1},\ldots,i_{M}$]=X[ind$_{1}$[$i_{1},\ldots i_{M}$], ind$_{2}$[$i_{1},\ldots,i_{M}$], \, etc.,\, ind$_{N}$[$i_{1},\ldots,i_{M}$]}.\] - -\end_inset - - -\end_layout - -\begin_deeper -\begin_layout Description -Example: Suppose the shape of the broadcasted indexing arrays is 3-dimensional - and -\begin_inset Formula $N$ -\end_inset - - is 2. - Then the result is found by letting -\begin_inset Formula $i,j,k$ -\end_inset - - run over the shape found by broadcasting -\begin_inset Formula $\textrm{ind}_{1},$ -\end_inset - - and -\begin_inset Formula $\textrm{ind}_{2},$ -\end_inset - -and for each -\begin_inset Formula $i,j,k$ -\end_inset - - setting result[ -\begin_inset Formula $i,j,k$ -\end_inset - -] = X[ -\begin_inset Formula $\textrm{ind}_{1}[i,j,k]$ -\end_inset - -, -\begin_inset Formula $\textrm{ind}_{2}[i,j,k]$ -\end_inset - -]. - -\end_layout - -\end_deeper -\begin_layout Itemize -If -\begin_inset Formula $N_{s}>0$ -\end_inset - -, then partial indexing is done. - This can be somewhat mind-boggling to understand, but if you think in terms - of the shapes of the arrays involved, it can be easier to grasp what happens. - In simple cases ( -\emph on -i.e. - -\emph default - one indexing array and -\begin_inset Formula $N-1$ -\end_inset - - slice objects) it does exactly what you would expect (concatenation of - repeated application of basic slicing). - The rule for partial indexing is that the shape of the result (or the interpret -ed shape of the object to be used in setting) is the shape of X with the - indexed subspace replaced with the broadcasted indexing subspace. - If the index subspaces are right next to each other, then the broadcasted - indexing space directly replaces all of the indexed subspaces in X. - If the indexing subspaces are separated (by slice objects), then the broadcaste -d indexing space is first, followed by the sliced subspace of X. - -\end_layout - -\begin_deeper -\begin_layout Description -Example\InsetSpace ~ -1: Suppose X.shape is (10,20,30) and ind is a (2,3,4) indexing intp - array, then result=X[...,ind,:] has shape (10,2,3,4,30) because the (20,)-shaped - subspace has been replaced with a (2,3,4)-shaped broadcasted indexing subspace. - If we let -\begin_inset Formula $i,j,k$ -\end_inset - - loop over the (2,3,4)-shaped subspace then result[...,i,j,k,:] = X[...,ind[i,j,k],:]. - This example produces the same result as X.take(ind,axis=-2). - -\end_layout - -\begin_layout Description -Example\InsetSpace ~ -2: Now let X.shape be (10,20,30,40,50) and suppose -\begin_inset Formula $\textrm{ind}_{1}$ -\end_inset - - and -\begin_inset Formula $\textrm{ind}_{2}$ -\end_inset - - are broadcastable to the shape (2,3,4). - Then X[:,ind -\begin_inset Formula $_{1}$ -\end_inset - -,ind -\begin_inset Formula $_{2}$ -\end_inset - -] has shape (10,2,3,4,40,50) because the (20,30)-shaped subspace from X - has been replaced with the (2,3,4) subspace from the indices. - However, X[:,ind -\begin_inset Formula $_{1}$ -\end_inset - -,:,ind -\begin_inset Formula $_{2}$ -\end_inset - -,:] has shape (2,3,4,10,30,50) because there is no unambiguous place to - drop in the indexing subspace, thus it is tacked-on to the beginning. - It is always possible to use .transpose() to move the sups pace anywhere - desired. - This example cannot be replicated using take. - -\end_layout - -\end_deeper -\begin_layout Subsubsection -Boolean -\end_layout - -\begin_layout Standard -This advanced selection occurs when obj is an array object of Boolean type - (such as may be returned from comparison operators). - It is always equivalent to (but faster than) X[obj.nonzero()] where as described - above obj.nonzero() returns a tuple (of length obj.ndim) of integer index - arrays showing the True elements of obj. - -\end_layout - -\begin_layout Standard -The special case when obj.ndim == X.ndim is worth mentioning. - In this case X[obj] returns a 1-dimensional array filled with the elements - of X corresponding to the True values of obj. - It The search order will be C-style (last index varies the fastest). - If obj has True values at entries that are outside of the bounds of X, - then an index error will be raised. -\end_layout - -\begin_layout Standard -You can also use Boolean arrays as element of the selection tuple. - In such instances, they will always be interpreted as nonzero(obj) and - the equivalent integer indexing will be done. - In general you can think of indexing with Boolean arrays as indexing with - nonzero(<Boolean>). -\end_layout - -\begin_layout Warning -the definition of advanced selection means that X[(1,2,3),] is fundamentally - different than X[(1,2,3)]. - The latter is equivalent to X[1,2,3] which will trigger basic selection - while the former will trigger advanced selection. - Be sure to understand why this is True. - You should also recognize that x[[1,2,3]] will trigger advanced selection, - but X[[1,2,slice(None)]] will trigger basic selection. -\end_layout - -\begin_layout Subsection -Flat Iterator indexing -\end_layout - -\begin_layout Standard -As mentioned previously, X.flat returns an iterator that will iterate over - the entire array (in C-contiguous style with the last index varying the - fastest). - This iterator object can also be indexed using basic slicing or advanced - indexing as long as the selection object is not a tuple. - This should be clear from the fact that X.flat is a 1-dimensional view. - X.flat can be used for integer indexing using 1-dimensional C-style-flat - indices. - The shape of any returned array is therefore the shape of the integer indexing -\begin_inset LatexCommand index -name "indexing|)" - -\end_inset - - object -\begin_inset LatexCommand index -name "ndarray|)" - -\end_inset - -. - -\end_layout - -\begin_layout Chapter -Basic Routines -\end_layout - -\begin_layout Quotation -Do not pray for tasks equal to your powers; pray for powers equal to your - tasks. - Then the doing of your work shall be no miracle, but you shall be the miracle. -\end_layout - -\begin_layout Right Address ---- -\emph on -Phillips Brooks -\end_layout - -\begin_layout Quote -Education isn't how much you have committed to memory, or even how much - you know. - It's being able to differentiate between what you do know and what you - don't. -\end_layout - -\begin_layout Right Address ---- -\emph on -Anatole France -\end_layout - -\begin_layout Section -Creating arrays -\end_layout - -\begin_layout Description -array -\begin_inset LatexCommand index -name "array" - -\end_inset - - (object=, dtype=None, copy=True, order=None, subok=False, ndmin=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Create a new ndarray of data type, dtype (or determined from object if - dtype is None). - The shape of the new array will be determined from object. - If copy is True, then ensure a copy of the object is made. - If copy is False, then the returned object is a copy of the array only - if dtype is not equivalent to the data type of object. - If order is 'Fortran' then the resulting array will be in Fortran order, - otherwise it is in C order. - If subok (subclasses are O.K.) is True then pass through subclasses of the - array object if possible. - If subok is False then only ndarray objects may be returned. - The ndmin parameter specifies that the returned array must have at least - the given number of dimensions. - -\end_layout - -\begin_layout Description -asarray -\begin_inset LatexCommand index -name "asarray" - -\end_inset - - (object=, dtype=None, order=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Exactly the same as array(...) except the default copy argument is False, - and subok is always False. - Using this function always returns the base class ndarray. - -\end_layout - -\begin_layout Description -asanyarray -\begin_inset LatexCommand index -name "asanyarray" - -\end_inset - - (object, dtype=None, order=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Thin wrapper around array(...) with subok=1. - You should use this routine if you are only making use of the array attributes, - and believe the calculations that will follow would work with any subclass - of the array. - Use of this routine increases the chance that array subclasses will interact - seamlessly with your function --- returning the same subclasses. - -\end_layout - -\begin_layout Description -require -\begin_inset LatexCommand index -name "require" - -\end_inset - - (object, dtype=None, requirements=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Require a Python object to be an ndarray (or a sub-class) of the given - data-type if it can be cast safely, otherwise raise an error. - The requirements, if given, are a sequence containing the requested combination - of the flags 'C_CONTIGUOUS' ('C'), 'F_CONTIGUOUS' ('F'), 'ALIGNED' ('A'), - 'WRITEABLE' ('W'), 'OWNDATA' ('O'), and the special directive 'ENSUREARRAY' - ('E'). - These strings dictate which flags should be set on the return array (note - only one of 'F_CONTIGUOUS' or 'C_CONTIGUOUS' should be used and 'F_CONTIGUOUS' - over-rides 'C_CONTIGUOUS'). - The special directive 'ENSUREARRAY' makes sure that a base-class ndarray - is returned instead of allowing sub-classes to pass through. - This function is particularly useful in a Python interface to C-code (say - called using ctypes -\begin_inset LatexCommand index -name "ctypes" - -\end_inset - -). - -\end_layout - -\begin_layout Description -arange -\begin_inset LatexCommand index -name "arange" - -\end_inset - - (start=, stop=None, step=1, dtype=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Function similar to Python's built-in range() function except it returns - an ndarray object. - Return a 1-d array of data type, dtype (or determined from the start, stop, - and step objects if None), that starts at start, ends -\emph on -before -\emph default - stop and is incremented by step. - The returned array has length -\begin_inset Formula $n$ -\end_inset - - where -\begin_inset Formula \[ -n=\left\lceil \frac{\textrm{stop}-\textrm{start}}{\textrm{step}}\right\rceil \] - -\end_inset - - with element -\begin_inset Formula $i$ -\end_inset - - equal to -\begin_inset Formula $\textrm{start}+i\cdot\textrm{step}.$ -\end_inset - - If stop is None, then the first argument is interpreted as stop and start - is 0. - -\end_layout - -\begin_layout Note -By definition of the ceiling function (denoted by -\begin_inset Formula $\left\lceil x\right\rceil $ -\end_inset - -), we know that -\begin_inset Formula $x\leq\left\lceil x\right\rceil <x+1$ -\end_inset - -, therefore this definition of the length of arange guarantees that -\begin_inset Formula $\textrm{start}+n\cdot\textrm{step}\geq\textrm{stop}$ -\end_inset - - as well as -\begin_inset Formula $\textrm{start}+(n-1)\cdot\textrm{step}<\textrm{stop}$ -\end_inset - -. - -\end_layout - -\begin_layout Description -isfortran -\begin_inset LatexCommand index -name "isfortran" - -\end_inset - - (arr) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Equivalent to -\family typewriter -arr.flags.fnc -\family default - and therefore returns True only if arr is Fortran-contiguous but not also - C-contiguous. -\end_layout - -\begin_layout Description -empty -\begin_inset LatexCommand index -name "empty" - -\end_inset - - (shape=, dtype=int, order='C') -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an uninitialized array of data type, dtype, and given shape. - The memory layout defaults to C-style contiguous, but can be made Fortran-style - contiguous with a 'Fortran' order keyword. -\end_layout - -\begin_layout Description -empty_like -\begin_inset LatexCommand index -name "empty\\_like" - -\end_inset - - (arr) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Syntactic sugar for empty(a.shape, a.dtype, isfortran(arr)) -\end_layout - -\begin_layout Description -zeros -\begin_inset LatexCommand index -name "zeros" - -\end_inset - - (shape=, dtype=int, order='C') -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an array of data type dtype and given shape filled with zeros. - The memory layout may be altered from the default C-style contiguous with - the order keyword. -\end_layout - -\begin_layout Description -zeros_like -\begin_inset LatexCommand index -name "zeros\\_like" - -\end_inset - - (arr) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Syntactic sugar for zeros(a.shape, a.dtype, isfortran(arr)) -\end_layout - -\begin_layout Description -ones -\begin_inset LatexCommand index -name "ones" - -\end_inset - - (shape=, dtype=int, order='C') -\end_layout - -\begin_layout Description -\InsetSpace ~ - Syntactic sugar for a = zeros(shape, dtype, order); a+= 1. - -\end_layout - -\begin_layout Description -fromstring -\begin_inset LatexCommand index -name "fromstring" - -\end_inset - - (string=,dtype=int, count=-1, sep='') -\end_layout - -\begin_layout Description -\InsetSpace ~ - If sep is '', then return a new 1-d array with data-type descriptor given - by dtype and with memory initialized (copied) from the raw binary data - in string. - If count is non-negative, the new array will have count elements (with - a -\family typewriter -ValueError -\family default - raised if count requires more data than the string offers), otherwise the - size of the string must be a multiple of the itemsize implied by dtype, - and count will be the length of the string divided by the itemsize. - -\end_layout - -\begin_layout Description -\InsetSpace ~ - If sep is not '', then interpret the string in ASCII mode with the provided - separator and convert the string to an array of numbers. - Any additional white-space will be ignored. -\end_layout - -\begin_layout Description -fromfile -\begin_inset LatexCommand index -name "fromfile" - -\end_inset - - (file=, dtype=int, count=-1, sep='') -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a 1-d array of data type, dtype, from a file (open file object or - string with the name of a file to read). - The file will be read in binary mode if sep is the empty string. - Otherwise, the file will be read in text mode with sep providing the separator - string between the entries. - If count is -1, then the size will be determined from the file, otherwise, - up to count items will be read from the file. - If fewer than count items are read, then a RunTimeWarning is issued indicating - the number of items read. -\end_layout - -\begin_layout Description -frombuffer -\begin_inset LatexCommand index -name "frombuffer" - -\end_inset - - (buffer, dtype=intp, count=-1, offset=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Very similar to (binary-mode) fromstring in interpretation of the arguments, - except buffer can be any object exposing the buffer interface (or any object - with a __buffer__ attribute that returns a buffer exposing the buffer protocol). - The new array shares memory with the buffer object. - The new array will be read-only if the buffer does not expose a writeable - buffer. - -\end_layout - -\begin_layout Description -fromiter -\begin_inset LatexCommand index -name "fromiter" - -\end_inset - - (iterator_or_generator, dtype=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Construct an array from an iterator or a generator. - Only handles 1-dimensional cases. - By default the data-type is determined from the objects returned from the - iterator. - -\end_layout - -\begin_layout Description -load -\begin_inset LatexCommand index -name "load" - -\end_inset - - (file) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Load a NumPy binary file (.npy), a NumPy binary zipfile (.npz), or a pickled - Python object from an open file. - If file is a string, then open a file with that name first. - Which kind of file should be loaded is determined by the magic bytes at - the front of the file (not by filename extension). - See -\shape italic -save -\shape default - and -\shape italic -savez -\shape default - for functions which write .npy and .npz files from NumPy arrays. - If file is a binary zipfile, then an instance of NpzObj is returned. - This object is a simple wrapper around the zip-file which allows extraction - of the arrays stored within it. - The .files attribute of the NpzObj returns a list of all arrays in the archive. - These arrays are accessible through a dictionary-like interface (obj['name']) - or through attribute lookup through the .f attribute of the returned object - (obj.f.name). - If the file is a NumPy binary file (.npy), then the array itself is returned - from this function. - If the file contains a pickled object, then that object is returned. - -\end_layout - -\begin_layout Description -loads -\begin_inset LatexCommand index -name "loads" - -\end_inset - - (str) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Load a pickled array from a string. - Equivalent to cPickle.loads(str). - This function will likely be deprecated in the future. - Use cPickle instead. -\end_layout - -\begin_layout Description -save -\begin_inset LatexCommand index -name "save" - -\end_inset - - (file, arr) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Save the array into a file which can be a string or an open file-like object. - If the file is given as a string, then it will have .npy appended if it - does not already end with that extension. - The .npy file format is NumPy-specific and is documented in the numpy.lib.format - module. - It only stores a single array. - -\end_layout - -\begin_layout Description -savez -\begin_inset LatexCommand index -name "savez" - -\end_inset - - (file, *args, **kwds) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Save a sequence of arrays into a NumPy binary zipfile (.npz). - An .npz file is a regular zip-file containing multiple .npy files. - If keywords are given, then the keyword names are used as filenames (with - the .npy extension added) in the zip-file with the corresponding values - being converted to arrays and stored in the specified filename. - Any non-keyword arguments that are passed in results in the names arr_0, - arr_1, etc. - being used in the zip-file (if a keyword by one of those names also exists, - then a ValueError is raised). - -\end_layout - -\begin_layout Description -loadtxt -\end_layout - -\begin_layout Description -savetxt -\end_layout - -\begin_layout Description -DataSource -\end_layout - -\begin_layout Description -indices -\begin_inset LatexCommand index -name "indices" - -\end_inset - - (dimensions, dtype=intp) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an array of dtype representing -\begin_inset Formula $n$ -\end_inset - -(=len(dimensions)) grids of indices each with variation in a single direction. - The returned array has shape ( -\begin_inset Formula $n$ -\end_inset - -,)+dimensions. - Compare with mgrid. - -\end_layout - -\begin_layout MyCode ->>> indices((2,3)) -\newline -array([[[0, 0, 0], -\newline - [1, 1, 1]], -\newline - -\newline - [[0, 1, 2], -\newline - - [0, 1, 2]]]) -\end_layout - -\begin_layout Description -fromfunction -\begin_inset LatexCommand index -name "fromfunction" - -\end_inset - - (function, dimensions, **kwargs) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Construct an array from a function called on a tuple of index grids. - The function should be able to take array arguments and process them like - ufuncs (use vectorize if it doesn't). - The function should accept as many arguments as there are dimensions which - is a sequence of numbers indicating the length of the desired output for - each axis. - Keyword arguments to function may also be passed in as keywords to fromfunction. -\end_layout - -\begin_layout MyCode ->>> print fromfunction(lambda i,j: i+j, (2,3)) -\newline -[[ 0. - 1. - 2.] -\newline - [ 1. - 2. - 3.]] -\end_layout - -\begin_layout Description -identity -\begin_inset LatexCommand index -name "identity" - -\end_inset - - (n, dtype=intp) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a 2-d array of shape (n,n) and data type, dtype with ones along - the main diagonal. - -\end_layout - -\begin_layout Description -where -\begin_inset LatexCommand index -name "where" - -\end_inset - - (condition[, x, y]) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns an array shaped like condition, that has the elements of x and - y respectively where condition is respectively true or false. - If x and y are not given, then it is equivalent to nonzero(condition). -\end_layout - -\begin_layout Description -flatnonzero -\begin_inset LatexCommand index -name "flatnonzero" - -\end_inset - - (arr) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return indices that are non-zero in a flattened version of arr. - Equivalent to a.ravel().nonzero()[0]. -\end_layout - -\begin_layout Description -putmask -\begin_inset LatexCommand index -name "putmask" - -\end_inset - - (arr=, mask=, values=) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Performs the equivalent of -\end_layout - -\begin_layout LyX-Code -for n, obj in enumerate( -\series bold -mask -\series default -.flat): -\end_layout - -\begin_layout LyX-Code - if obj: -\end_layout - -\begin_layout LyX-Code - self.flat[n] = -\series bold -values -\series default -[n] -\end_layout - -\begin_layout Description -\InsetSpace ~ - The values array is repeated if it is too short. - In particular, this means that indexing on the values array is modular - it's length, which might be surprising you are expecting putmask to work - the same as arr[mask]=values. -\end_layout - -\begin_layout Description -lexsort -\begin_inset LatexCommand index -name "lexsort" - -\end_inset - - (keys=, axis=-1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an array of indices similar to argsort except sorting is done using - all of the provided keys. - First a sort is computed using key[0], then the indices are further altered - by sorting on key[1]. - This is repeated until sorting has been performed on all of the keys. - This is a useful function for multiple-field sorting. -\end_layout - -\begin_layout MyCode ->>> a = [1,2,1,3,1,5]; b = [0,4,5,6,2,3] -\newline ->>> ind = lexsort((b,a)) -\newline ->>> print - take(a,ind) -\newline -[1 1 1 2 3 5] -\newline ->>> print take(b,ind) -\newline -[0 2 5 4 6 3] -\end_layout - -\begin_layout Description -\InsetSpace ~ - Notice the order the keys had to be used in order to get a lexicographical - sorting order. - To clarify, suppose three equal-length sequences are fields of an underlying - data-type: (f1,f2,f3). - If we want to sort first on f1 and then on f2 and then on f3, the indices - that would accomplish that sort are obtained as lexsort((f3,f2,f1)). -\end_layout - -\begin_layout Section -Operations on two or more arrays -\end_layout - -\begin_layout Description -concatenate -\begin_inset LatexCommand index -name "concatenate" - -\end_inset - - (seq=, axis=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Construct a new array from elements of the sequence object seq concatenated - along the given axis. - The elements of the sequence object must have compatible types and be the - same shape. - If axis is None, then flatten each element of seq before concatenating - together to construct a 1-d array. -\end_layout - -\begin_layout Description -correlate -\begin_inset LatexCommand index -name "correlate" - -\end_inset - - (x, y, mode='valid') -\end_layout - -\begin_layout Description -\InsetSpace ~ - Compute the 1-d cross correlation of x and y keeping portions determined - by mode which may be 'valid' (0), 'same' (1), or 'full' (2). - The 'full' cross-correlation between two 1-d arrays is computed as -\begin_inset Formula \[ -z\left[n\right]=\sum_{i=\max\left(n-M,0\right)}^{\min\left(n,K\right)}x\left[i\right]y\left[n+i\right],\] - -\end_inset - -for -\begin_inset Formula $n=0\ldots K+M$ -\end_inset - - where -\begin_inset Formula $K$ -\end_inset - -=len( -\begin_inset Formula $x$ -\end_inset - -)-1 and -\begin_inset Formula $M$ -\end_inset - -=len( -\begin_inset Formula $y$ -\end_inset - -)-1, and we assume -\begin_inset Formula $K\geq M$ -\end_inset - - (without loss of generality because we can interchange the roles of -\begin_inset Formula $x$ -\end_inset - - and -\begin_inset Formula $y$ -\end_inset - - without effect). - For this formula to work, we assume that -\begin_inset Formula $x[i]=0$ -\end_inset - - when -\begin_inset Formula $i\notin\left[0,K-1\right]$ -\end_inset - - and -\begin_inset Formula $y[j]=0$ -\end_inset - - when -\begin_inset Formula $j\neq[0,M-1]$ -\end_inset - -. - -\end_layout - -\begin_layout Description -\InsetSpace ~ - If mode is 'same' then only the -\begin_inset Formula $K$ -\end_inset - - middle values are returned starting at -\begin_inset Formula $n=\left\lfloor \frac{M-1}{2}\right\rfloor $ -\end_inset - -. - If the flag has a value of 'valid' then only the middle -\begin_inset Formula $K-M+1=\left(K+1\right)-\left(M+1\right)+1$ -\end_inset - - output values are returned starting at -\begin_inset Formula $n=M.$ -\end_inset - - -\end_layout - -\begin_layout Description -convolve -\begin_inset LatexCommand index -name "convolve" - -\end_inset - - (x, y, mode='valid') -\end_layout - -\begin_layout Description -\InsetSpace ~ - Convolution is very similar to correlation except it is defined with one - sequence reversed: -\begin_inset Formula \[ -z\left[n\right]=\sum_{i}x[i]y[n-i].\] - -\end_inset - - The mode keyword has the same effect as it does for correlation. - Convolution ('full') between two 1-d arrays implements polynomial multiplicatio -n where the array entries are viewed as coefficients for polynomials. -\end_layout - -\begin_deeper -\begin_layout Description -Example: Consider that -\begin_inset Formula $(x^{3}+4x^{2}+2)$ -\end_inset - - -\begin_inset Formula $\left(x^{4}+3x+1\right)$ -\end_inset - -= -\begin_inset Formula $x^{7}+4x^{6}+5x^{4}+13x^{3}+4x^{2}+6x+2.$ -\end_inset - - This can be determined by using the code -\family typewriter -convolve([1,4,0,2], [1,0,0,3,1]) -\family default - which returns -\family typewriter -[1,4,0,5,13,4,6,2]. - -\family default - Notice the one-to-one alignment between the elements of the arrays and - the coefficients on powers of -\begin_inset Formula $x$ -\end_inset - - in the polynomial. - -\end_layout - -\end_deeper -\begin_layout Description -outer -\begin_inset LatexCommand index -name "outer" - -\end_inset - - (a, b) -\end_layout - -\begin_layout Description -\InsetSpace ~ - compute an outerproduct which is syntactic sugar for a.ravel() [:,newaxis] - * b.ravel() [newaxis,:] (after first converting a and b to ndarrays). -\end_layout - -\begin_layout MyCode ->>> print outer([1,2,3],[10,100,1000]) -\newline -[[ 10 100 1000] -\newline - [ 20 200 2000] -\newline - - [ 30 300 3000]] -\end_layout - -\begin_layout Description -inner -\begin_inset LatexCommand index -name "inner" - -\end_inset - - (a, b) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Computes the inner product between two arrays. - This is an array that has shape a.shape[:-1] + b.shape[:-1] with elements - computed as the sum of the product of the elements from the last dimensions - of a and b. - In particular, let -\begin_inset Formula $I$ -\end_inset - - and -\begin_inset Formula $J$ -\end_inset - - be the super -\begin_inset Foot -status open - -\begin_layout Standard -A super index is 0 or more integer indices used to index into an N-dimensional - array. - How many indices a super index represents should be implied by context. -\end_layout - -\end_inset - - indices selecting the 1-dimensional arrays -\begin_inset Formula $a[I,:]$ -\end_inset - - and -\begin_inset Formula $b[J,:]$ -\end_inset - -, then the resulting array, -\begin_inset Formula $r$ -\end_inset - -, is -\begin_inset Formula \[ -r[I,J]=\sum_{k}a[I,k]b[J,k].\] - -\end_inset - - -\end_layout - -\begin_layout Description -dot -\begin_inset LatexCommand index -name "dot" - -\end_inset - - (a, b) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Computes the dot (matrix) product between two arrays. - The product-sum is over the last dimension of -\begin_inset Formula $a$ -\end_inset - - and the second-to-last dimension of -\begin_inset Formula $b$ -\end_inset - -. - Specifically, if -\begin_inset Formula $I$ -\end_inset - - and -\begin_inset Formula $J$ -\end_inset - - are super indices for -\begin_inset Formula $a[I,:]$ -\end_inset - - and -\begin_inset Formula $b[J,:,j]$ -\end_inset - - so that -\begin_inset Formula $j$ -\end_inset - - is the index of the last dimension of -\begin_inset Formula $b$ -\end_inset - -. - Then, the shape of the resulting array is a.shape[:-1] + b.shape[:-2] + (b.shape[- -1],) with elements. - -\begin_inset Formula \[ -r[I,J,j]=\sum_{k}a[I,k]b[J,k,j],\] - -\end_inset - - -\end_layout - -\begin_layout Description -\begin_inset LatexCommand index -name "vdot" - -\end_inset - -vdot (a, b) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Computes the dot product between two arrays (flattened into one-dimensional - vectors) after conjugating the first vector. - This is an inner-product following the physicists convention of conjugating - the first argument. -\begin_inset Formula \[ -r=\sum_{k}\overline{\textrm{a.flat}[k]}\textrm{b.flat}[k].\] - -\end_inset - - -\end_layout - -\begin_layout Description -tensordot -\begin_inset LatexCommand index -name "tensordot" - -\end_inset - - (a, b, axes=(-1,0)) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Computes a dot-product between two arrays where the sum is taken over the - axes specified by the 2-sequence which can have either scalar or sequence - entries. - The axes specified are summed over and the remaining axes are used to construct - the result. - So, for example, if -\begin_inset Formula $a$ -\end_inset - - is -\begin_inset Formula $3\times4\times5$ -\end_inset - - and -\begin_inset Formula $b$ -\end_inset - - is -\begin_inset Formula $4\times3\times2$ -\end_inset - - then if axes=([1,0],[0,1]) (or axes=([0,1],[1,0])) the result will be -\begin_inset Formula $5\times2$ -\end_inset - -. - Let -\begin_inset Formula $I$ -\end_inset - - represent the indices of the un-summed axes in -\begin_inset Formula $a$ -\end_inset - -, let -\begin_inset Formula $J$ -\end_inset - - represent the indices of the un-summed axes in -\begin_inset Formula $b$ -\end_inset - - and let -\begin_inset Formula $K$ -\end_inset - - represent the the indices of the axes summed over in both -\begin_inset Formula $a$ -\end_inset - - and -\begin_inset Formula $b$ -\end_inset - -. - Also, let -\begin_inset Formula $a_{t}$ -\end_inset - - represent a transposed version of -\begin_inset Formula $a$ -\end_inset - - where the axes to be summed over are pushed to the end, and let -\begin_inset Formula $b_{t}$ -\end_inset - - represent a transposed version of -\begin_inset Formula $b$ -\end_inset - - where the axes to be summed over are pushed to the front. - Then, using -\begin_inset Formula $\sum_{K}$ -\end_inset - - to represent a multi-index sum, the result can be written as -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -r[I,J]=\sum_{K}a_{t}[I,K]b_{t}[K,J]\] - -\end_inset - - -\end_layout - -\begin_layout Description -cross -\begin_inset LatexCommand index -name "cross" - -\end_inset - - (a, b, axisa=-1, axisb=-1, axisc=-1, axis=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns the cross product of two (arrays of) vectors. - The cross product is performed over the axes of the input arrays indicated - by the axisa, and axisb arguments. - For both arrays, the axis used must have dimension either 2 or 3. - If both axes used have dimension 2, then only the z-component of the equivalent - 3-d cross product is returned. - Otherwise, the entire vector is returned. - The axisc argument gives the axis of the vectors in the returned cross-product - result. - If axis is not None, then it is assumed that axisa=axisb=axisc=axis (regardless - of what else is specified). - -\end_layout - -\begin_layout Description -allclose -\begin_inset LatexCommand index -name "allclose" - -\end_inset - - (a, b, rtol= -\begin_inset Formula $10^{-5}$ -\end_inset - -, atol= -\begin_inset Formula $10^{-8}$ -\end_inset - -) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns true if all components of a and b are equal subject to the given - relative and absolute tolerances. - This returns true if every element of a and b satisfy -\begin_inset Formula \[ -\left|a-b\right|<\textrm{atol}+\textrm{rtol}\left|b\right|.\] - -\end_inset - - -\end_layout - -\begin_layout Section -Printing arrays -\end_layout - -\begin_layout Description -array2string -\begin_inset LatexCommand index -name "array2string" - -\end_inset - - (a) -\end_layout - -\begin_layout Description -\InsetSpace ~ - The default printing mechanism uses this function to produce a string from - an array. - -\end_layout - -\begin_layout Description -set_printoptions -\begin_inset LatexCommand index -name "set\\_printoptions" - -\end_inset - - (precision=None, theshold=None, edgeitems=None, linewidth=None, suppress=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Set options associated with representing an array. -\end_layout - -\begin_deeper -\begin_layout Description -precision the default number of digits of precision for floating point output - (default 8); -\end_layout - -\begin_layout Description -threshold total number of array elements which triggers printing only the - -\begin_inset Quotes eld -\end_inset - -ends -\begin_inset Quotes erd -\end_inset - - of the array rather than a full representation (default 1000); -\end_layout - -\begin_layout Description -edgeitems number of array elements in summary at beginning and end of each - dimension (default 3); -\end_layout - -\begin_layout Description -linewidth the number of characters per line (default 75); -\end_layout - -\begin_layout Description -suppress Boolean value indicating whether or not to suppress printing of - small floating point values using scientific notation (default False). -\end_layout - -\end_deeper -\begin_layout Description -get_printoptions -\begin_inset LatexCommand index -name "get\\_printoptions" - -\end_inset - - () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns the values of precision, threshold, edgeitems, linewidth, and suppress - that control printing of arrays. -\end_layout - -\begin_layout Description -set_string_function -\begin_inset LatexCommand index -name "set\\_string\\_function" - -\end_inset - - (func, repr=1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Set the function to use in response to str(array) or repr(array). - By default this function is array2string. - The function passed in must take an array argument and return a string. - If func is None, then the print function is reset to a simple internal - function. - -\end_layout - -\begin_layout Section -Functions redundant with methods -\end_layout - -\begin_layout Standard -Several functions are available primarily for purposes of backward compatibility - with old Numeric, and are therefore redundant. - The functions are all simple wrappers for asarray(a).<function>(*args, **kwds), - or are replaceable by attribute access. - The following list documents them. - It is not recommended that these functions be used in new programs, but - there are no plans for removing them as in functional form they work with - arbitrary sequences which is sometimes desirable. - The functions that mirror methods and attributes are: -\series bold -take -\series default - -\begin_inset LatexCommand index -name "take" - -\end_inset - -, -\series bold -reshape -\series default - -\begin_inset LatexCommand index -name "reshape" - -\end_inset - -, -\series bold -squeeze -\series default - -\begin_inset LatexCommand index -name "squeeze" - -\end_inset - -, -\series bold -choose -\series default - -\begin_inset LatexCommand index -name "choose" - -\end_inset - -, -\series bold -repeat -\series default - -\begin_inset LatexCommand index -name "repeat" - -\end_inset - -, -\series bold -put -\series default - -\begin_inset LatexCommand index -name "put" - -\end_inset - -, -\series bold -swapaxes -\series default - -\begin_inset LatexCommand index -name "swapaxes" - -\end_inset - -, -\series bold -transpose -\series default - -\begin_inset LatexCommand index -name "transpose" - -\end_inset - -, -\series bold -real -\series default - -\begin_inset LatexCommand index -name "real" - -\end_inset - -, -\series bold -imag -\series default - -\begin_inset LatexCommand index -name "imag" - -\end_inset - -, -\series bold -sort -\series default - -\begin_inset LatexCommand index -name "sort" - -\end_inset - -, -\series bold -argsort -\series default - -\begin_inset LatexCommand index -name "argsort" - -\end_inset - -, -\series bold -amax -\begin_inset LatexCommand index -name "amax" - -\end_inset - -, argmax -\series default - -\begin_inset LatexCommand index -name "argmax" - -\end_inset - -, -\series bold -amin -\begin_inset LatexCommand index -name "amin" - -\end_inset - - -\series default -, -\series bold -argmin -\series default - -\begin_inset LatexCommand index -name "argmin" - -\end_inset - -, -\series bold -ptp -\series default - -\begin_inset LatexCommand index -name "ptp" - -\end_inset - -, -\series bold -alen -\series default - -\begin_inset LatexCommand index -name "alen" - -\end_inset - -, -\series bold -searchsorted -\series default - -\begin_inset LatexCommand index -name "searchsorted" - -\end_inset - -, -\series bold -diagonal -\series default - -\begin_inset LatexCommand index -name "diagonal" - -\end_inset - -, -\series bold -trace -\series default - -\begin_inset LatexCommand index -name "trace" - -\end_inset - -, -\series bold -ravel -\series default - -\begin_inset LatexCommand index -name "ravel" - -\end_inset - -, -\series bold -nonzero -\series default - -\begin_inset LatexCommand index -name "nonzero" - -\end_inset - -, -\series bold -shape -\series default - -\begin_inset LatexCommand index -name "shape" - -\end_inset - -, -\series bold -compress -\series default - -\begin_inset LatexCommand index -name "compress" - -\end_inset - -, -\series bold -clip -\series default - -\begin_inset LatexCommand index -name "clip" - -\end_inset - -, -\series bold -std -\series default - -\begin_inset LatexCommand index -name "std" - -\end_inset - -, -\series bold -var -\series default - -\begin_inset LatexCommand index -name "var" - -\end_inset - -, -\series bold -mean -\series default - -\begin_inset LatexCommand index -name "mean" - -\end_inset - -, -\series bold -sum -\series default - -\begin_inset LatexCommand index -name "sum" - -\end_inset - -, -\series bold -cumsum -\series default - -\begin_inset LatexCommand index -name "cumsum" - -\end_inset - -, -\series bold -product -\series default - -\begin_inset LatexCommand index -name "product" - -\end_inset - -, -\series bold -cumproduct -\series default - -\begin_inset LatexCommand index -name "cumproduct" - -\end_inset - -, -\series bold -sometrue -\begin_inset LatexCommand index -name "sometrue" - -\end_inset - - -\series default - (method is .any), -\series bold -alltrue -\begin_inset LatexCommand index -name "alltrue" - -\end_inset - - -\series default - (method is .all), -\series bold -around -\begin_inset LatexCommand index -name "around" - -\end_inset - - -\series default - (method is .round), -\series bold -rank -\begin_inset LatexCommand index -name "rank" - -\end_inset - - -\series default - (attribute is .ndim), -\series bold -shape -\series default - -\begin_inset LatexCommand index -name "shape" - -\end_inset - -, -\series bold -size -\begin_inset LatexCommand index -name "size" - -\end_inset - - -\series default - (.size or .shape[axis]), and -\series bold -copy -\series default - -\begin_inset LatexCommand index -name "copy" - -\end_inset - -. - -\end_layout - -\begin_layout Section -Dealing with data types -\end_layout - -\begin_layout Description -dtype (obj, align=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a data-type object from any object. - See Chapter -\begin_inset LatexCommand ref -reference "cha:Data-descriptor-objects" - -\end_inset - - for a more detailed explanation of what can be interpreted as a data-type - object and the meaning of the align keyword. - -\end_layout - -\begin_layout Description -maximum_sctype (arg) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns the array-scalar type of highest precision of the same general - kind as arg which can be any recognized form for describing a data-type. -\end_layout - -\begin_layout Description -issctype (obj) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns True if obj is an array data type (or a recognized alias for one) -\end_layout - -\begin_layout Description -obj2sctype (obj, default=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns the array type object corresponding to obj which can be an array - type already, a python type object, an actual array, or any recognized - alias for an array type object. - If no suitable data type object can be determined, return default. -\end_layout - -\begin_layout Description -sctype2char (sctype) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the typecode character associated with an array-scalar type dtype. - The first argument is first converted to a dtype if it needs to be. - -\end_layout - -\begin_layout Tip -the type attribute of data-type objects are actual Python type objects subclasse -d in a hierarchy of types. - This can often be useful to check data types generically. - For example, issubclass(dtype.type, integer) can check to see if the data - type is one of the 10 different integer types. - The issubclass function, however, raises an error if either argument is - not an actual type object. - NumPy defines _(arg1, arg2) that will return false instead of raise an - error. - Alternatively, dtype.kind is a character describing the class of the data-type - so dtype.kind in 'iu' would also check to see if the data-type is an integer - type. -\end_layout - -\begin_layout Description -can_cast (from=d1, to=d2) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return Boolean value indicating whether or not data type d1 can be cast - to data type d2 safely (without losing precision or information). - -\end_layout - -\begin_layout Chapter -Additional Convenience Routines -\end_layout - -\begin_layout Quotation -A committee is twelve men doing the work of one. -\end_layout - -\begin_layout Right Address ---- -\emph on -John F. - Kennedy -\end_layout - -\begin_layout Quotation -Your mind can only hold one thought at a time. - Make it a positive and constructive one. -\end_layout - -\begin_layout Right Address ---- -\emph on -H. - Jackson Brown Jr. - -\end_layout - -\begin_layout Section -Shape functions -\end_layout - -\begin_layout Description -atleast_1d -\begin_inset LatexCommand index -name "atleast\\_1d" - -\end_inset - - (a1,a2,...,an) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Force a sequence of arrays (including array scalars) to each be at least - 1-d. - -\end_layout - -\begin_layout Description -atleast_2d -\begin_inset LatexCommand index -name "atleast\\_2d" - -\end_inset - - (a1,a2,...,an) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Force a sequence of arrays (including array scalars) to each be at least - 2-d. - Dimensions of length 1 are pre-pended to reach a two-dimensional array. -\end_layout - -\begin_layout Description -atleast_3d -\begin_inset LatexCommand index -name "atleast\\_3d" - -\end_inset - - (a1,a2,...,an) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Force a sequence of arrays (including array_scalars) to each be at least - 3-d. - Dimensions of length 1 are pre-pended to reach a two-dimensional array. -\end_layout - -\begin_layout Description -roll -\begin_inset LatexCommand index -name "roll" - -\end_inset - - (arr, shift, axis=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a new array with the contents of arr shifted (rolled) by the amount - given in the integer argument shift along the axis specified. - If axis is None, then the shift takes place in the ravelled array (but - the returned array has the same shape as arr). - Elements that shift outside the array are rolled back into the array from - the opposite side. - -\end_layout - -\begin_layout Description -rollaxis -\begin_inset LatexCommand index -name "rollaxis" - -\end_inset - - (arr, axis, start) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return arr transposed so that the provided axis is inserted into the shape - before start with the other dimensions rolled. - Thus, if arr.shape is (i,j,k,l) then rollaxis(arr, 2, 0) has shape (k,i,j,l) - and rollaxis(arr, 1, 3) has shape (i,k,j,l). -\end_layout - -\begin_layout Description -vstack -\begin_inset LatexCommand index -name "vstack" - -\end_inset - - (seq) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Stack a sequence of arrays along the first axis (row wise). - Arrays in seq must have the same shape along all dimensions but the first. - Rebuilds array divided by vsplit. - All 1-d arrays will be stacked row-wise. -\end_layout - -\begin_layout Description -hstack -\begin_inset LatexCommand index -name "hstack" - -\end_inset - - (seq) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Stack a sequence of arrays along the second axis (column wise). - Arrays in seq must have the same shape along all dimensions but the second. - Rebuilds array divided by hsplit. - Notice that 1-d arrays will be appended into a new 1-d array. - Use column_stack to get a 2-d array from 1-d arrays. - If some arrays are already 2-d, then the 1-d arrays need to have a dimension - added to the end ( -\emph on -e.g. - -\emph default - -\family typewriter -y[:,newaxis] -\family default -) in order to stack correctly. - -\end_layout - -\begin_layout Description -column_stack -\begin_inset LatexCommand index -name "column\\_stack" - -\end_inset - - (seq) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Stack a sequence of arrays as columns into a 2-d array. - 1-d arrays are converted to 2-d arrays and transposed. - All arrays must have shapes so that the resulting array is well defined. - Compare with -\series bold -hstack -\series default -. -\end_layout - -\begin_layout Description -row_stack -\begin_inset LatexCommand index -name "row\\_stack" - -\end_inset - - (seq) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Stack a sequence of 1-d arrays as rows into a 2-d array (alias for -\series bold -vstack -\series default -). - -\end_layout - -\begin_layout Description -dstack -\begin_inset LatexCommand index -name "dstack" - -\end_inset - - (seq) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Stack a sequence of arrays along the third axis (depth wise). - Arrays in seq must have the same shape along all dimensions but the third. - Rebuilds array divided by vsplit. -\end_layout - -\begin_layout Description -array_split -\begin_inset LatexCommand index -name "array\\_split" - -\end_inset - - (ary, i_or_s, axis=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Divide ary into a list of sub-arrays along the specified axis. - The i_or_s argument stands for indices_or_sections. - If i_or_s is an integer, ary is divided into that many equally-sized arrays. - If it is impossible to make an even split, each of the leading arrays in - the returned list have one additional member. - If i_or_s is a list of sorted integer, its entries define the indexes where - ary is split. - An empty list for i_or_s results in a single sub-array equal to the original - array. -\end_layout - -\begin_layout Description -split -\begin_inset LatexCommand index -name "split" - -\end_inset - - (ary, i_or_s, axis=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - The same as array_split() except if i_or_s is an integer and it is impossible - to make an even split, an error is raised. -\end_layout - -\begin_layout Description -hsplit -\begin_inset LatexCommand index -name "hsplit" - -\end_inset - - (ary, i_or_s) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Split a single array into multiple columns of sub-arrays (along the first - axis if 1-d or along the second second if >1-d). - Only works on arrays of 1 or more dimension. - -\end_layout - -\begin_layout Description -vsplit -\begin_inset LatexCommand index -name "vsplit" - -\end_inset - - () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Split a single array into multiple rows of sub-arrays (along the first - axis). - Only works on arrays of 2 or more dimensions. -\end_layout - -\begin_layout Description -dsplit -\begin_inset LatexCommand index -name "dsplit" - -\end_inset - - () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Split a single array into multiple sub-arrays along the third axis (depth). - Only works on arrays of 3 or more dimensions. -\end_layout - -\begin_layout Description -apply_along_axis -\begin_inset LatexCommand index -name "apply\\_along\\_axis" - -\end_inset - - (func1d, axis, arr, *args) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Execute func1d(arr[sel_i], *args) where func1d takes 1-d arrays and arr - is an N-d array, where sel_i is a selection object sufficient to select - a 1-d sub-array along the given axis. - The function is executed for all 1-d arrays along axis in arr. - -\end_layout - -\begin_layout Description -apply_over_axes -\begin_inset LatexCommand index -name "apply\\_over\\_axes" - -\end_inset - - (func, a, axes) -\end_layout - -\begin_layout Description -\InsetSpace ~ - For each axis in the axes sequence, call func as -\family typewriter -res=func(a, axis) -\family default -. - If res is the same shape as a then set -\family typewriter -a=res -\family default - and continue. - if -\family typewriter -res.ndim = a.ndim -1 -\family default -, then insert a dimension before axis and continue. - -\end_layout - -\begin_layout Description -expand_dims -\begin_inset LatexCommand index -name "expand\\_dims" - -\end_inset - - (a, axis) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Expand the shape of array a by including newaxis -\series bold -before -\series default - the given axis. -\end_layout - -\begin_layout Description -resize -\begin_inset LatexCommand index -name "resize" - -\end_inset - - (a, new_shape) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns a new array with the specified shape which can be any size. - The new array is filled with repeated copies of a. - This function is similar in spirit to a.resize(new_shape) except that it - fills in the new array with repeated copies and returns a new array. - -\end_layout - -\begin_layout Description -kron -\begin_inset LatexCommand index -name "kron" - -\end_inset - - (a, b) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a composite array with blocks from -\emph on -b -\emph default - scaled by elements of -\emph on -a -\emph default -. - The number of dimensions of -\emph on -a -\emph default - and -\emph on -b -\emph default - should be the same. - If not, then the input with fewer dimensions is pre-pended with ones (broadcast -) to the same shape as the input with more dimensions. - The return array has this same number of dimensions with shape given by - the product of the shape of -\emph on -a -\emph default - and the shape of -\emph on -b -\emph default -. - If either a or b is a scalar then this function is equivalent to multiply(a,b). - -\end_layout - -\begin_layout Description -\InsetSpace ~ - For example, if -\emph on -a -\emph default - and -\emph on -b -\emph default - are is 1-d the result is -\begin_inset Formula \[ -\left[\begin{array}{cccc} -a[0]*b & a[1]*b & \cdots & a[-1]*b\end{array}\right]\] - -\end_inset - - while if -\emph on -a -\emph default - and -\emph on -b -\emph default - are 2-d, the result is -\begin_inset Formula \[ -\left[\begin{array}{cccc} -a[0,0]*b & a[0,1]*b & \cdots & a[0,-1]*b\\ -a[1,0]*b & a[1,1]*b & \cdots & a[1,-1]*b\\ -\vdots & \vdots & \ddots & \vdots\\ -a[-1,0]*b & a[-1,1]*b & \cdots & a[-1,-1]*b\end{array}\right]\] - -\end_inset - - -\end_layout - -\begin_deeper -\begin_layout Description -Example: -\end_layout - -\end_deeper -\begin_layout MyCode ->>> kron([1,10,100],[5,6,7]) -\newline -array([ 5, 6, 7, 50, 60, 70, 500, 600, - 700]) -\newline ->>> kron([[1,10],[100,1000]],[[2,3],[4,5]]) -\newline -array([[ 2, 3, 20, - 30], -\newline - [ 4, 5, 40, 50], -\newline - [ 200, 300, 2000, 3000], -\newline - - [ 400, 500, 4000, 5000]]) -\end_layout - -\begin_layout Description -tile -\begin_inset LatexCommand index -name "tile" - -\end_inset - - (a, reps) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Tile an -\begin_inset Formula $N$ -\end_inset - --dimensional array using the shape information in reps to create a larger - -\begin_inset Formula $N$ -\end_inset - --dimensional array. - This is equivalent to kron(ones(reps, a.dtype), a). - The number of dimensions of a and the length of shape should be the same - or else 1's will be pre-pended to make them the same. - -\end_layout - -\begin_deeper -\begin_layout Description -Example: -\end_layout - -\end_deeper -\begin_layout MyCode ->>> tile([5,6,7],(1,2,3)) -\newline -array([[[5, 6, 7, 5, 6, 7, 5, 6, 7], -\newline - [5, - 6, 7, 5, 6, 7, 5, 6, 7]]]) -\end_layout - -\begin_layout Section -Basic functions -\end_layout - -\begin_layout Description -average -\begin_inset LatexCommand index -name "average" - -\end_inset - - (a, axis=None, weights=None, returned=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Computes the average along the indicated axis. - If axis is None, average over the entire array. - Inputs can be integer or floating types; result is type float. - If weights are given, the result is sum(a*weights)/sum(weights). - Therefore, weights must have shape equal to a.shape or be 1-d with length - a.shape[axis]. - Integer weights are converted to float. - If returned is True, then return a tuple showing both the result and the - sum of the weights (or count of the values). - The shape of these two results will be the same. - -\end_layout - -\begin_layout Description -cov -\begin_inset LatexCommand index -name "cov" - -\end_inset - - (x, y=None, rowvar=1, bias=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Compute the covariance matrix of data in x. - If x is a vector and y is None, then this function is equivalent to asarray(x).v -ar(). - Otherwise, x is interpreted as observations of several random variables. - If rowvar is True (default), then the variables are in the rows and the - observations of the variables are in the columns. - Otherwise, the variables are in the columns and the observations are in - the rows. - If y is given then it is treated as another variable or set of variables - to be added to x. - By default, a so-called unbiased estimate of the covariance matrix is made. - If bias is non-zero, then a biased normalization factor (with better mean-squar -e error performance) is used instead. - If -\begin_inset Formula $\mathbf{X}$ -\end_inset - - is a random vector, then the covariance matrix is defined as -\begin_inset Formula \[ -\mathbf{C}=E\left[\left(\mathbf{X}-E\mathbf{X}\right)\left(\mathbf{X}-E\mathbf{X}\right)^{H}\right].\] - -\end_inset - - It can be approximated as -\begin_inset Formula \[ -\mathbf{C}\approx\frac{1}{P}\sum_{i=0}^{N-1}\left(\mathbf{x}_{i}-\bar{\mathbf{x}}\right)\left(\mathbf{x}_{i}-\bar{\mathbf{x}}\right)^{H}\] - -\end_inset - - where -\begin_inset Formula $\mathbf{x}_{i}$ -\end_inset - - is an observation of -\begin_inset Formula $\mathbf{X}$ -\end_inset - - (as a column-vector), -\begin_inset Formula $N$ -\end_inset - - is the number of observations made and -\begin_inset Formula $P=N-1$ -\end_inset - - for an unbiased estimate or -\begin_inset Formula $P=N$ -\end_inset - - for a biased (but lower mean-squared error) estimate. - -\end_layout - -\begin_layout Description -corrcoef -\begin_inset LatexCommand index -name "corrcoef" - -\end_inset - - (x, y=None, rowvar=1, bias=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Estimate the correlation coefficient of x. - By default, each row of x contains a random variable with observations - of the random variable in the columns of x. - (If rowvar is False, the each column is a random variable with observations - in the rows). - The y argument can be used to append additional variables to x. - The -\begin_inset Formula $i^{\textrm{th}}$ -\end_inset - - row and -\begin_inset Formula $j^{\textrm{th}}$ -\end_inset - - column of the correlation coefficient matrix is defined as -\begin_inset Formula \[ -\rho_{ij}=\frac{C_{ij}}{\sqrt{C_{ii}C_{jj}}}\] - -\end_inset - - where -\begin_inset Formula $\mathbf{C}$ -\end_inset - - is the covariance matrix. - The rowvar and bias arguments are passed on to the cov function to estimate - -\begin_inset Formula $\mathbf{C}.$ -\end_inset - - -\end_layout - -\begin_layout Description -msort -\begin_inset LatexCommand index -name "msort" - -\end_inset - - (a) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a new array, sorted along the first axis. - Equivalent to b=a.copy(); b.sort(0) -\end_layout - -\begin_layout Description -median -\begin_inset LatexCommand index -name "median" - -\end_inset - - (m) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns the median of m along its first dimension. -\end_layout - -\begin_layout Description -bincount -\begin_inset LatexCommand index -name "bincount" - -\end_inset - - (list=, weights=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - The list argument is a 1-d integer array. - Let -\begin_inset Formula $r$ -\end_inset - - be the returned 1-d array whose length is (list.max()+1). - If weights is None, then -\begin_inset Formula $r[i]$ -\end_inset - - is the number of occurrences of -\begin_inset Formula $i$ -\end_inset - - in list. - If weight is present, then the -\begin_inset Formula $i^{\textrm{th}}$ -\end_inset - - element is -\begin_inset Formula \[ -r[i]=\sum_{j:\textrm{list}\left[j\right]=i}\textrm{weights}[j].\] - -\end_inset - - Notice that if weights is None, it is equivalent to a weights array of - all 1. - The length of weights must be the same as the length of list. - -\end_layout - -\begin_layout Description -digitize -\begin_inset LatexCommand index -name "digitize" - -\end_inset - - (x=,bins=) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an array of integers the same length as x with values -\begin_inset Formula $i$ -\end_inset - - such that -\begin_inset Formula $\textrm{bins}\left[i-1\right]\leq x<\textrm{bins}\left[i\right]$ -\end_inset - - if bins is monotonically increasing, or -\begin_inset Formula $\textrm{bins}[i]\leq x<\textrm{bins}[i-1]$ -\end_inset - - if bins is monotonically decreasing. - When -\begin_inset Formula $x$ -\end_inset - - is beyond the bounds of bins, return either -\begin_inset Formula $i=0$ -\end_inset - - or -\begin_inset Formula $i=$ -\end_inset - -len(bins) as appropriate. -\end_layout - -\begin_layout Description -histogram -\begin_inset LatexCommand index -name "histogram" - -\end_inset - - (x=, bins=None, range=None, normed=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Construct a histogram for the data in x (treated as one-dimensional array - of type float). - If bins is not a sequence, then bins should be the number of bins which - will be constructed ranging from range[0] to range[1] or x.min() to x.max() - if range is None. - If normed is True, then the histogram will be normalized and comparable - with a probability density function, otherwise it will be a count of the - number of items in each bin. - The return value is the tuple (n, bins) where n is the histogram. -\end_layout - -\begin_layout Description -histogram2d -\begin_inset LatexCommand index -name "histogram2d" - -\end_inset - - (x, y, bins=10, range=None, normed=False) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Compute the two-dimensional histogram for a dataset (x,y) given the bins. - Returns (histogram, xedges, yedges). - The bins argument can be either the number of bins or a sequence of the - bin edges if the x and y directions should have the same bins. - If the bins argument is a sequence of length 2, then separate bin edges - will be computed. - The first element can be either the number of bins or the bin edges for - the x-direction. - The second element is interpreted as the number of bins or the bin edges - for the y-direction. - The returned histogram array, H, is a count of the number of samples in - each bin. - The array is oriented such that H[i,j] is the number of samples falling - into binx[j] and biny[i] (notice the association x<->j and y<->i). - Setting normed to True returns a density rather than a bin-count. - The range argument allows specifying lower and upper bin edges (in a sequence - of length 2 with 2-length sequences in each entry). - The default is [[x.min(), x.max()],[y.min(), y.max()]]. - -\end_layout - -\begin_layout Description -histogramdd -\begin_inset LatexCommand index -name "histogramdd" - -\end_inset - - (sample, bins=10, range=None, normed=False) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Compute the -\begin_inset Formula $D$ -\end_inset - --dimensional histogram for a (vector) dataset contained in sample give the - bins. - The dataset is a sequence of -\begin_inset Formula $D$ -\end_inset - - arrays or an -\begin_inset Formula $N\times D$ -\end_inset - - array where -\begin_inset Formula $N$ -\end_inset - - is the number of samples and -\begin_inset Formula $D$ -\end_inset - - is the number of dimensions. - Returns (histogram, edges) where histogram is a -\begin_inset Formula $D$ -\end_inset - --dimensional array of shape given by the number of bins selected in each - axis containing the number of counts that a point in the sample data fell - into the volume bin specified. - The edges sequence has -\begin_inset Formula $D$ -\end_inset - --entries to specify the edge boundaries for each dimension. - The bins argument is a sequence of edge arrays or a sequence of the number - of bins. - If a scalar is given, it is assumed to be the number of bins for all dimensions. - The range is a length- -\begin_inset Formula $D$ -\end_inset - - sequence containing lower and upper bin edges which default to the min - and maximum of the respective datasets. - If normed is True, then a density rather than a bin-count is returned. - -\end_layout - -\begin_layout Description -logspace -\begin_inset LatexCommand index -name "logspace" - -\end_inset - - (start, stop, num=50, endpoint=True,base=10.0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Evenly spaced samples on a logarithmic scale. - Returns num evenly spaced (in logspace) samples from base**start to base**stop. - If endpoint is True, then the last sample is base**stop. -\end_layout - -\begin_layout Description -linspace -\begin_inset LatexCommand index -name "linspace" - -\end_inset - - (start, stop, num=50, endpoint=True, retstep=False): -\end_layout - -\begin_layout Description -\InsetSpace ~ - Evenly spaced samples. - Returns num evenly spaced samples from start to stop. - If endpoint is True, then the last sample is stop. - If retstep is True, then return the computed step size. -\end_layout - -\begin_layout Description -meshgrid -\begin_inset LatexCommand index -name "meshgrid" - -\end_inset - - (x, y) -\end_layout - -\begin_layout Description -\InsetSpace ~ - For 1-d arrays x, y with lengths Nx=len(x) and Ny = len(y), return X, Y - where X and Y are (Ny, Nx) shaped arrays with the elements of x and y repeated - to fill the array. - -\end_layout - -\begin_layout MyCode ->>> X,Y = meshgrid([1,2,3], [4,5,6,7]); print X; print Y -\newline -[[1 2 3] -\newline - [1 2 3] -\newline - - [1 2 3] -\newline - [1 2 3]] -\newline -[[4 4 4] -\newline - [5 5 5] -\newline - [6 6 6] -\newline - [7 7 7]] -\end_layout - -\begin_layout Description -select -\begin_inset LatexCommand index -name "select" - -\end_inset - - (condlist, choicelist, default=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns an array comprised from different elements of choicelist depending - on the list of conditions. - The condlist argument is a list of Boolean condition arrays. - The choicelist argument is a list of choice arrays (of the same size as - the arrays in condlist). - The result has the same size as the arrays in choicelist. - If condlist is [ -\begin_inset Formula $c_{0},\ldots,c_{N-1}$ -\end_inset - -], then choicelist must be of length -\begin_inset Formula $N$ -\end_inset - -. - The elements of choicelist can then be represented as [ -\begin_inset Formula $v_{0},\ldots,v_{N-1}$ -\end_inset - -]. - The default choice if none of the conditions are met is given as the default - argument. - The conditions are tested in order and the first one satisfied is used - to select the choice. - In other words, the elements of the output array are found from the following - tree (evaluated on an element-by-element basis) -\end_layout - -\begin_layout LyX-Code - -\series bold -if -\series default - -\begin_inset Formula $c_{0}$ -\end_inset - -: -\begin_inset Formula $v_{0}$ -\end_inset - - -\newline - -\series bold -elif -\series default - -\begin_inset Formula $c_{1}$ -\end_inset - -: -\begin_inset Formula $v_{1}$ -\end_inset - - -\newline -... -\newline - -\series bold -elif -\series default - -\begin_inset Formula $c_{N-1}$ -\end_inset - -: -\begin_inset Formula $v_{N-1}$ -\end_inset - - -\newline - -\series bold -else -\series default -: default -\end_layout - -\begin_layout Description -piecewise -\begin_inset LatexCommand index -name "piecewise" - -\end_inset - - (x, condlist, funclist, *args, **kw) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Compute a piecewise-defined function. - A piecewise defined function is -\begin_inset Formula \[ -f\left(x\right)=\left\{ \begin{array}{cc} -f_{1}\left(x\right) & x\in S_{1},\\ -f_{2}\left(x\right) & x\in S_{2},\\ -\vdots & \vdots\\ -f_{n}\left(x\right) & x\in S_{n}.\end{array}\right.\] - -\end_inset - -where -\begin_inset Formula $S_{1}$ -\end_inset - - are sets. - Thus, the function is defined differently over different sub-domains of - the input. - Such a function can be computed using -\family typewriter -select -\family default - but such an implementation means calling each -\begin_inset Formula $f_{i}$ -\end_inset - - over the entire region of -\begin_inset Formula $x.$ -\end_inset - - The piecewise call guarantees that each function -\begin_inset Formula $f_{i}$ -\end_inset - - will only be called over those values of -\begin_inset Formula $x$ -\end_inset - - in -\begin_inset Formula $S_{i}.$ -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Arguments: x is the array of values over which to call the function; condlist - is a sequence of Boolean (indicator) arrays (or a single Boolean array) - of the same shape as -\begin_inset Formula $x$ -\end_inset - - that defines the sets (True indicates that element of -\begin_inset Formula $x$ -\end_inset - - is in the set). - If needed, to match the length of funclist, an -\begin_inset Quotes eld -\end_inset - -otherwise -\begin_inset Quotes erd -\end_inset - - set will be added to condlist. - This otherwise set is defined as -\begin_inset Formula $S_{n}=\overline{\bigcup S_{i}}.$ -\end_inset - - The argument funclist is a list of functions to be called (or items to - be inserted) corresponding to the conditions. - Each of these functions can take extra arguments and key-word arguments - which are passed in as *args, and **kw using standard Python syntax. - Each of these functions should return vector output for vector input. - If the function is a scalar, then it will simply be inserted where appropriate - into the output. - It is the equivalent of a constant function. - -\end_layout - -\begin_deeper -\begin_layout Description -Example: Suppose we want to compute -\begin_inset Formula $f\left(x\right)=x^{2}\Pi\left(\frac{x}{3}\right)+u\left(x-5\right)$ -\end_inset - - where -\begin_inset Formula $\Pi\left(x\right)=1$ -\end_inset - - only when -\begin_inset Formula $\left|x\right|\leq1$ -\end_inset - - and -\begin_inset Formula $u\left(x\right)=1$ -\end_inset - - only when -\begin_inset Formula $x\geq0.$ -\end_inset - - This could be done using the code: -\end_layout - -\end_deeper -\begin_layout MyCode ->>> f1 = lambda x: x*x -\newline ->>> x = r_[-4:6:20j] -\newline ->>> y = piecewise(x,abs(x)<=3,[f1,0])+ -piecewise(x,x>=0,[1,0]) -\newline ->>> set_printoptions(precision=4); print y -\newline -[ 0. - 0. - 8.687 5.8615 3.59 1.8726 0.7091 0.0997 -\newline - 1.0443 1.5429 2.5956 4.2022 - 6.3629 9.0776 1. - 1. - 1. -\newline - 1. - 1. - 1. - ] -\end_layout - -\begin_layout Description -trim_zeros -\begin_inset LatexCommand index -name "trim\\_zeros" - -\end_inset - - (filt, trim='fb'): -\end_layout - -\begin_layout Description -\InsetSpace ~ - Trim the leading ('f' in trim) and trailing ('b' in trim) zeros from a - sequence according to the trim keyword. - -\end_layout - -\begin_layout Description -trapz -\begin_inset LatexCommand index -name "trapz" - -\end_inset - - (y, x=None, dx=1.0, axis=-1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - If -\begin_inset Formula $\mathbf{y}$ -\end_inset - - contains samples of a function: -\begin_inset Formula $y_{i}=f\left(x_{i}\right)$ -\end_inset - - then trapz can be used to approximate the integral of the function using - the trapezoidal rule. - If the sampling is not evenly spaced use -\begin_inset Formula $\mathbf{x}$ -\end_inset - - to pass in the sample positions. - Otherwise, only the sample-spacing is needed in dx. - The trapz function can work with many functions at a time stored in an - -\begin_inset Formula $N$ -\end_inset - --dimensional array. - The axis argument controls which axis defines the sampling axis (the other - dimensions are different functions). - The number of dimensions of the returned result is -\begin_inset Formula $y$ -\end_inset - -.ndim - 1. -\end_layout - -\begin_layout Description -diff -\begin_inset LatexCommand index -name "diff" - -\end_inset - - (x, n=1, axis=-1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Calculates the -\begin_inset Formula $n^{\textrm{th}}$ -\end_inset - - order, discrete difference along the given axis. -\end_layout - -\begin_layout Description -gradient -\begin_inset LatexCommand index -name "gradient" - -\end_inset - - (f, *varargs) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Calculate the gradient of an N-d scalar function, f. - Uses central differences on the interior and first differences on boundaries - to give the same shape for each component of the gradient. - The varargs variable can contain 0, 1, or N scalars corresponding to the - sample distances in each direction (default 1.0). - If f is N-d, then N arrays are returned each of the same shape as f, giving - the derivative of f with respect to each dimension. - -\end_layout - -\begin_layout Description -angle -\begin_inset LatexCommand index -name "angle" - -\end_inset - - (z, deg=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the angle of a complex number z (in degrees if deg is True). -\end_layout - -\begin_layout Description -unwrap -\begin_inset LatexCommand index -name "unwrap" - -\end_inset - - (p, discont=pi, axis=-1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Unwraps radian phase p by changing absolute jumps greater than discont - to their -\begin_inset Formula $2\pi$ -\end_inset - - complement along the given axis. - -\end_layout - -\begin_layout Description -sort_complex -\begin_inset LatexCommand index -name "sort\\_complex" - -\end_inset - - (x) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This is syntactic sugar for asarray(x).sort().astype(<cmplx_type>) where - cmplx_type is csingle if x.dtype is integral with fewer bits than intp, - clongfloat if x.dtype.type is longfloat, and cdouble for all other types. - The sorting is done by comparing the real part of the array, and then the - imaginary part if the real parts are the same. - -\end_layout - -\begin_layout Description -disp -\begin_inset LatexCommand index -name "disp" - -\end_inset - - (mesg, device=None, linefeed=1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Display a message to device (defaults to sys.stdout) with or without a closing - linefeed. -\end_layout - -\begin_layout Description -unique -\begin_inset LatexCommand index -name "unique" - -\end_inset - - (seq) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns unique items in the 1-dimensional seq. -\end_layout - -\begin_layout Description -extract -\begin_inset LatexCommand index -name "extract" - -\end_inset - - (condition, arr) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Equivalent to arr.compress(condition.flat) and arr.flat[bool_(condition.flat)] - which extracts the elements of (flattened) arr according to the elements - of (flattened) condition that are True. - -\end_layout - -\begin_layout Description -place -\begin_inset LatexCommand index -name "place" - -\end_inset - - (arr, mask, vals) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Inverse of extract. - Equivalent to arr[abool(mask)] = vals but it uses a different algorithm. - -\end_layout - -\begin_layout Description -delete -\begin_inset LatexCommand index -name "delete" - -\end_inset - - (arr, indices, axis=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a new array with the sub-arrays indicated by indices along axis - removed. - If axis is None, then first ravel the array and set axis to -1. - The indices argument describes which sub-arrays along the given axis should - be removed. - It can be an integer, a slice object, or a sequence of integers. - A new array is created with the corresponding sub-arrays are removed. - -\end_layout - -\begin_layout Description -insert -\begin_inset LatexCommand index -name "insert" - -\end_inset - - (arr, indices, values, axis=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Create a new array with values inserted into arr before indices. - If axis is None, then first ravel the array and set axis to -1. - The indices argument describes which indices along the provided axis the - values should be inserted before. - It can be an integer, a slice object, or a sequence of integers. - The values argument must be broadcastable to the shape implied by where - they will be inserted. - -\end_layout - -\begin_layout Description -append -\begin_inset LatexCommand index -name "append" - -\end_inset - - (arr, values, axis=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a new array with values appended to the end of the array along axis. - -\end_layout - -\begin_layout Description -nansum -\begin_inset LatexCommand index -name "nansum" - -\end_inset - - (x, axis=None) -\end_layout - -\begin_layout Description -nanmax -\begin_inset LatexCommand index -name "nanmax" - -\end_inset - - (x, axis=None) -\end_layout - -\begin_layout Description -nanargmax -\begin_inset LatexCommand index -name "nanargmax" - -\end_inset - - (x, axis=None) -\end_layout - -\begin_layout Description -nanargmin -\begin_inset LatexCommand index -name "nanargmin" - -\end_inset - - (x, axis=None) -\end_layout - -\begin_layout Description -nanmin -\begin_inset LatexCommand index -name "nanmin" - -\end_inset - - (x, axis=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - These functions perform their respective operations over the given axis - (or the entire array if axis is None), after replacing any nans with appropriat -e values so as not to affect the calculation. - -\end_layout - -\begin_layout Description -vectorize -\begin_inset LatexCommand index -name "vectorize" - -\end_inset - - (pyfunc, otypes=None, doc=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This creates a class whose instances have a call method that invokes a - ufunc that has been dynamically built to call the python function pyfunc - internally. - The output types can be controlled by the otypes argument. - If it is None, then the output types will be determined upon first call - to the function using the provided inputs. - This can be reset, by re-setting the otypes attribute to -\begin_inset Quotes eld -\end_inset - - -\begin_inset Quotes erd -\end_inset - -. - The normal rules of array broadcasting are followed by the returned object. -\end_layout - -\begin_layout MyCode ->>> def myfunc(a,b): -\newline -... - if (a>b): return a -\newline -... - else: return b-1 -\newline ->>> vecfunc = vectorize(myfunc) -\newline ->>> vecfunc([[1,2,3],[5,6,9] -],[7,4,5]) -\newline -array([[6, 3, 4], -\newline - [6, 6, 9]]) -\end_layout - -\begin_layout Description -asarray_chkfinite -\begin_inset LatexCommand index -name "asarray\\_chkfinite" - -\end_inset - - (x) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Like asarray(x) except an error is raised if any of the values in x are - not finite. - -\end_layout - -\begin_layout Description -round_ -\begin_inset LatexCommand index -name "round\\_" - -\end_inset - - (x, decimals=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an array with all the elements of x rounded to decimals places. - Returns x if array is not floating point and rounds both the real and imaginary - parts separately if array is complex. - Rounds in the same way as standard python except for half-way values are - rounded to the nearest -\emph on -even -\emph default - number. -\end_layout - -\begin_layout Description -packbits (array, axis=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Pack an integer array of logical data (zero/non-zero) into bits of a uint8 - data-type along the dimension given by axis. - This dimension is shrunk by a factor of 8 (rounded up). - Each element in the input is converted to a bit in the output which is - set to 1 or 0 depending on whether the input is non-zero or not. - Thus, every 8-element chunk of the input is converted to a single byte - in the output. - If axis is None, then the bit-packing is done on the entire array as if - it were raveled. -\end_layout - -\begin_layout Description -unpackbits (array, axis=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Unpack bits of an array of uint8 data-type into a single uint8 byte for - each bit along the dimension given by axis. - This dimension is thus expanded 8-fold, but otherwise the output has the - same shape as the input. - If axis is None, then the input is treated as a 1-d array and expanded - 8-fold so that each bit of the input is given an output byte. - -\end_layout - -\begin_layout Description -add_docstring -\begin_inset LatexCommand index -name "add\\_docstring" - -\end_inset - - (obj, doc) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Adds a docstring to a built-in object, obj, that does not have a docstring - defined already. - The obj can be a built-in function-or-method, a typeobject, a method descriptor -, a getset descriptor, or a member descriptor. - This is useful for improving the documentation of objects defined in C-compiled - code without re-compiling. - If the object already has a docstring, a RuntimeError is raised. - If the object is not a supported type the code can add a docstring to, - a TypeError is raised. - -\end_layout - -\begin_layout Description -add_newdoc -\begin_inset LatexCommand index -name "add\\_newdoc" - -\end_inset - - (place, obj, doc) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Adds a docstring to the -\emph on -obj -\emph default - imported from -\emph on -place -\emph default - using exec 'from %s import %s' % (place, obj). - Thus, both place and obj should be strings. - If doc is a string, then a single docstring is added to obj from place. - If doc is a 2-tuple, then obj must be an object with attributes that need - to be commented. - The first element of the doc tuple is the attribute to be commented on - and the second element is the actual docstring. - If doc is a list, then it must be composed of elements that are 2-tuples - indicating that obj has several attributes that need to be documented. - -\end_layout - -\begin_layout Section -Polynomial functions -\end_layout - -\begin_layout Standard -There are two interfaces for dealing with polynomials -\begin_inset LatexCommand index -name "polynomials" - -\end_inset - -: a class-based interface, and a collection of functions to deal with a - polynomials represented as a simple list of coefficients. - This latter representation results from the is a one-to-one correspondence - between a length- -\begin_inset Formula $\left(n+1\right)$ -\end_inset - - sequence of coefficients -\begin_inset Formula $a_{n}\equiv a[n]$ -\end_inset - - and an -\begin_inset Formula $n^{\textrm{th}}$ -\end_inset - - order polynomial: -\begin_inset Formula \[ -p\left(x\right)=a_{0}x^{n}+a_{1}x^{n-1}+\cdots+a_{n-1}x+a_{n}.\] - -\end_inset - - Most of the functions below operate on and return a simple sequence of - coefficients representing a polynomial. - There is, however, a simple polynomial class that provides some utility - for doing simple algebra on polynomials. - -\end_layout - -\begin_layout Description -poly1d -\begin_inset LatexCommand index -name "poly1d" - -\end_inset - - (c_or_r, r=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This construction returns an instance of a simple polynomial class. - It can take either a list of coefficients on polynomial powers, or a sequence - of roots (if r=1). - The returned polynomial can be added, subtracted, multiplied, divided, - and taken to integer powers, resulting in new polynomials. - -\end_layout - -\begin_deeper -\begin_layout Description -.r roots of the polynomial -\end_layout - -\begin_layout Description -.o order of the polynomial -\end_layout - -\begin_layout Description -.c polynomial coefficients as an array (also -\series bold -__array__() -\series default - ) -\end_layout - -\begin_layout Description -__call__(x) evaluate the polynomial at x (can be an array) -\end_layout - -\begin_layout Description -__getitem__(x) p[k] returns the coefficient on the kth power of x (backwards - from indexing the coefficient array) -\end_layout - -\end_deeper -\begin_layout MyCode ->>> p=poly1d([2,5,7]) -\newline ->>> print p -\newline -2 -\newline -2 x + 5 x + 7 -\newline ->>> print p*[1,3,1] -\newline -4 - 3 2 -\newline -2 x + 11 x + 24 x + 26 x + 7 -\newline ->>> print p([0.5,0.6,3]) -\newline -[ 10. - 10.72 40. - ] -\newline ->>> print p.r -\newline -[-1.25+1.3919j -1.25-1.3919j] -\end_layout - -\begin_layout Description -poly -\begin_inset LatexCommand index -name "poly" - -\end_inset - - (roots_or_matrix) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a sequence of coefficients representing a polynomial given the sequence - of roots as an argument. - Alternatively, if the argument is a 2-d array, then return the characteristic - polynomial of the matrix. - -\end_layout - -\begin_layout Description -roots -\begin_inset LatexCommand index -name "roots" - -\end_inset - - (poly) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the roots of the polynomial represented by coefficients in poly -\end_layout - -\begin_layout Description -polyint -\begin_inset LatexCommand index -name "polyint" - -\end_inset - - (poly, m=1, k=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an exact -\begin_inset Formula $m^{\textrm{th}}$ -\end_inset - --order integral of the polynomial represented in poly. - If k is None, then use 0 for the integrating constants. - Otherwise, use the scalars in the sequence k as integrating constants. - Also available as .integ (m=1,k=0) method of poly1d objects. -\end_layout - -\begin_deeper -\begin_layout Description -Example: -\begin_inset Formula \begin{eqnarray*} -p\left(x\right) & = & x^{2}+3x+4\\ -\int\int p\left(x\right) & = & \frac{1}{12}x^{4}+\frac{1}{2}x^{3}+2x^{2}+k_{0}x+k_{1}\end{eqnarray*} - -\end_inset - - -\end_layout - -\end_deeper -\begin_layout MyCode ->>> print polyint([1,3,4],m=2,k=[5,3]) -\newline -[ 0.0833 0.5 2. - 5. - 3. - ] -\end_layout - -\begin_layout Description -polyder -\begin_inset LatexCommand index -name "polyder" - -\end_inset - - (poly, m) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an exact -\begin_inset Formula $m^{\textrm{th}}$ -\end_inset - --order derivative of the polynomial represented in poly. - Also available as .deriv(m=1) method of poly1d objects. -\end_layout - -\begin_deeper -\begin_layout Description -Example: -\begin_inset Formula \begin{eqnarray*} -p\left(x\right) & = & x^{3}+2x^{2}+4x+3\\ -\frac{dp}{dx}\left(x\right) & = & 3x^{2}+4x+4\end{eqnarray*} - -\end_inset - - -\end_layout - -\end_deeper -\begin_layout MyCode ->>> polyder([1,2,4,3]) -\newline -array([3, 4, 4]) -\end_layout - -\begin_layout Description -polyadd -\begin_inset LatexCommand index -name "polyadd" - -\end_inset - - (p1, p2) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Add the two polynomials represented by coefficients: -\begin_inset Formula $p_{1}\left(x\right)+p_{2}\left(x\right)$ -\end_inset - - -\end_layout - -\begin_layout Description -polysub -\begin_inset LatexCommand index -name "polysub" - -\end_inset - - (p1, p2) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return coefficients for the polynomial found by subtracting the two polynomials - represented by -\begin_inset Formula $p_{1}$ -\end_inset - - and -\begin_inset Formula $p_{2}$ -\end_inset - -: -\begin_inset Formula $p_{1}\left(x\right)-p_{2}\left(x\right)$ -\end_inset - - -\end_layout - -\begin_layout Description -polymul -\begin_inset LatexCommand index -name "polymul" - -\end_inset - - (p1, p2) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the coefficients for -\begin_inset Formula $p_{1}\left(x\right)p_{2}\left(x\right)$ -\end_inset - - -\end_layout - -\begin_layout Description -polydiv -\begin_inset LatexCommand index -name "polydiv" - -\end_inset - - (p1, p2) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the quotient, -\begin_inset Formula $q\left(x\right)$ -\end_inset - -, and remainder, -\begin_inset Formula $r\left(x\right)$ -\end_inset - -, so that -\begin_inset Formula $p_{1}\left(x\right)=q\left(x\right)p_{2}\left(x\right)+r\left(x\right),$ -\end_inset - - with the order of -\begin_inset Formula $r\left(x\right)$ -\end_inset - - less than the order of -\begin_inset Formula $p_{2}\left(x\right).$ -\end_inset - - -\end_layout - -\begin_layout Description -polyval -\begin_inset LatexCommand index -name "polyval" - -\end_inset - - (p, y) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Evaluate the polynomial -\begin_inset Formula $p$ -\end_inset - - at -\begin_inset Formula $y$ -\end_inset - -. - The argument, -\begin_inset Formula $y$ -\end_inset - -, can be a number or an array or a polynomial object. - If x is a polynomial object, then polyval performs polynomial composition: - -\begin_inset Formula $p\left(y\left(x\right)\right),$ -\end_inset - - otherwise polyval computes the value of the polynomial at each -\begin_inset Formula $y$ -\end_inset - -. - Uses Horner's rule for evaluation, but this can still lead to numerical - instabilities for wildly fluctuating coefficients. -\end_layout - -\begin_layout Description -polyfit -\begin_inset LatexCommand index -name "polyfit" - -\end_inset - - (x,y,N) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Compute a best-fit polynomial in -\begin_inset Formula $x$ -\end_inset - - of order -\begin_inset Formula $N$ -\end_inset - -, to the data, -\begin_inset Formula $y$ -\end_inset - -, in the sense of minimizing averaged-squared error between the measurement - and the model. - Useful for quick line-fitting -\begin_inset LatexCommand index -name "fitting" - -\end_inset - -. - -\end_layout - -\begin_layout Section -Set Operations -\end_layout - -\begin_layout Standard -The set operations -\begin_inset LatexCommand index -name "set operations|(" - -\end_inset - - were kindly contributed by Robert Cimrman. - These set operations are based on sorting functions and all expect 1-d - sequences with unique elements with the exception of unique1d and intersect1d_n -u which will flatten N-d nested-sequences to 1-d arrays and can handle non-uniqu -e elements. - -\end_layout - -\begin_layout Description -unique1d -\begin_inset LatexCommand index -name "unique1d" - -\end_inset - - (arr, retindx=False) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the unique elements of arr as a 1-d array. - If retindx is True, then also return the indices, ind, such that arr.flat[ind] - is the set of unique values. -\end_layout - -\begin_layout Description -intersect1d -\begin_inset LatexCommand index -name "intersect1d" - -\end_inset - - (a1, a2) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the (sorted) intersection of a1 and a2 which is an array containing - the elements of a1 that are also in a2. - -\end_layout - -\begin_layout Description -intersect1d_nu -\begin_inset LatexCommand index -name "intersect1d\\_nu" - -\end_inset - - (a1, a2) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the (sorted) intersection of a1 and a2 but allow a1 and a2 to be - N-d arrays with non-unique elements. - Equivalent to intersect1d(unique1d(a1), unique1d(a2)). - -\end_layout - -\begin_layout Description -union1d -\begin_inset LatexCommand index -name "union1d" - -\end_inset - - (a1, a2) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the (sorted) union of a1 and a2 which is an array containing elements - that are in either a1 or a2. - -\end_layout - -\begin_layout Description -setdiff1d -\begin_inset LatexCommand index -name "setdiff1d" - -\end_inset - - (a1, a2) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the set-difference of a1 and a2 which is an array containing the - elements of a1 that are -\series bold -not -\series default - in a2. -\end_layout - -\begin_layout Description -setxor1d -\begin_inset LatexCommand index -name "setxor1d" - -\end_inset - - (a1, a2) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the (sorted) set containing the exclusive-or of the arrays a1 and - a2. - The exclusive-or contains elements that are in a1 or in a2 as long as the - element is not in both a1 and a2. - -\end_layout - -\begin_layout Description -setmember1d -\begin_inset LatexCommand index -name "setmember1d" - -\end_inset - - (tocheck, set) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a Boolean 1-d array of the length of tocheck which is True whenever - that element is contained in set and false when it is not. - Equivalent -\begin_inset LatexCommand index -name "set operations|)" - -\end_inset - - to array([x in set for x in tocheck]). -\end_layout - -\begin_layout Section -Array construction using index tricks -\end_layout - -\begin_layout Standard -The functions and classes in this category make it simpler to construct - arrays. - -\end_layout - -\begin_layout Description -ix_ -\begin_inset LatexCommand index -name "ix\\_" - -\end_inset - - (*args) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This indexing cross function is useful for forming indexing arrays necessary - to select out the cross-product of -\begin_inset Formula $N$ -\end_inset - - 1-dimensional arrays. - Note that the default indexing does not do a cross-product (which might - be unexpected for someone coming from other programming environments). - The default indexing is more general purpose. - Using the ix_ constructor can produce the indexing arrays necessary to - select a cross-product. -\end_layout - -\begin_layout Description -mgrid [index expression] -\end_layout - -\begin_layout Description -\InsetSpace ~ - This is an instance of a class. - It can be used to construct a filled -\begin_inset Quotes eld -\end_inset - -mesh-grid -\begin_inset Quotes erd -\end_inset - - using slicing syntax. - -\end_layout - -\begin_layout Description -ogrid [index expression] -\end_layout - -\begin_layout Description -\InsetSpace ~ - This is similar to mgrid except it returns an open grid, so as to save - space and time. - The broadcasting rules will ensure that any universal function operating - on the grid will act as if the ogrid had been the result of mgrid. -\end_layout - -\begin_layout Description -r_ -\begin_inset LatexCommand index -name "r\\_" - -\end_inset - - [index expression] -\end_layout - -\begin_layout Description -\InsetSpace ~ - This is a simple way to build up arrays quickly. - There are two use cases. - 1) If the index expression contains comma separated arrays, then stack - them along their first axis. - 2) If the index expression contains slice notation or scalars then create - a 1-d array with a range indicated by the slice notation. - In other-words the slice syntax start:stop:step is equivalent to arange(start, - stop, step) inside of the brackets. - However, if step is an imaginary number (i.e. - 100j) then its integer portion is interpreted as a number-of-points desired - and the start and stop are inclusive. - In other words start:stop:step -\family typewriter -j -\family default - is interpreted as linspace(start, stop, step, endpoint=1) inside of the - brackets. - After expansion of slice notation, all comma separated sequences are concatenat -ed together. -\end_layout - -\begin_layout Description -\InsetSpace ~ - Optional character strings placed as the first element of the index expression - can be used to change the output. - The strings 'r' or 'c' result in matrix output. - If the result is 1-d and 'r' is specified a -\begin_inset Formula $1\times N$ -\end_inset - - (row) matrix is produced. - If the result is 1-d and 'c' is specified, then a -\begin_inset Formula $N\times1$ -\end_inset - - (column) matrix is produced. - If the result is 2-d then both provide the same matrix result. - -\end_layout - -\begin_layout MyCode ->>> print r_[-1:1:9j,[0]*10,5,6] -\newline -[-1. - -0.75 -0.5 -0.25 0. - 0.25 0.5 0.75 1. - 0. - 0. -\newline - 0. - 0. - 0. - 0. - 0. - 0. - 0. - 0. - 5. - 6. - ] -\newline ->>> print r_['r',1,2,5,6] -\newline -[[1 2 5 6]] -\newline ->>> print r_['c',1,2,5,6] -\newline -[[1] -\newline - [2] -\newline - - [5] -\newline - [6]] -\end_layout - -\begin_layout Description -\InsetSpace ~ - A string integer specifies which axis to stack multiple comma separated - arrays along. - -\end_layout - -\begin_layout MyCode ->>> a=arange(6).reshape(2,3) -\newline ->>> r_[a,a] -\newline -array([[0, 1, 2], -\newline - [3, 4, 5], -\newline - - [0, 1, 2], -\newline - [3, 4, 5]]) -\newline ->>> r_['-1',a,a] -\newline -array([[0, 1, 2, 0, 1, - 2], -\newline - [3, 4, 5, 3, 4, 5]]) -\end_layout - -\begin_layout Description -\InsetSpace ~ - A string of two comma-separated integers allows indication of the minimum - number of dimensions to force each entry into as the second integer (the - axis to concatenate along is still the first integer). - -\end_layout - -\begin_layout MyCode ->>> r_['0,2',[1,2,3],[4,5,6]] -\newline -array([[1, 2, 3], -\newline - [4, 5, 6]]) -\newline ->>> r_['1,2',[1, -2,3],[4,5,6]] -\newline -array([[1, 2, 3, 4, 5, 6]]) -\end_layout - -\begin_layout Description -\InsetSpace ~ - A string with three comma-separated integers allows specification of the - axis to concatenate along, the minimum number of dimensions to force the - entries to, and which axis should contain the start of the arrays which - are less than the specified number of dimensions. - In other words the third integer allows you to specify where the the 1's - should be placed in the shape of the arrays that have their shapes upgraded. - By default, they are placed in the front of the shape tuple. - The third argument allows you to specify where the start of the array should - be instead. - Thus, a third argument of '0' would place the 1's at the end of the array - shape. - Negative integers specify where in the new shape tuple the last dimension - of upgraded arrays should be placed, so the default is '-1'. -\end_layout - -\begin_layout MyCode ->>> r_['0,2,0', [1,2,3], [4,5,6]] -\newline -array([[1], -\newline - [2], -\newline - [3], -\newline - - [4], -\newline - [5], -\newline - [6]]) -\newline ->>> r_['1,2,0', [1,2,3], [4,5,6]] -\newline -array([[1, - 4], -\newline - [2, 5], -\newline - [3, 6]]) -\end_layout - -\begin_layout Description -c_ -\begin_inset LatexCommand index -name "c\\_" - -\end_inset - - [index_expression] -\end_layout - -\begin_layout Description -\InsetSpace ~ - This is short-hand for r_['-1,2,0', index_expression] useful because of - its common occurence. - In particular, arrays will be stacked along their last axis after being - upgraded to at least 2-d with 1's post-pended to the shape (column vectors - made out of 1-d arrays). - -\end_layout - -\begin_layout Section -Other indexing devices -\end_layout - -\begin_layout Description -index_exp -\begin_inset LatexCommand index -name "index\\_exp" - -\end_inset - - [index expression] -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a tuple of Python objects that implements the index expression and - can be modified and placed in any other index expression. - -\end_layout - -\begin_layout MyCode ->>> index_exp[2:5,...,4,::-1] -\newline -(slice(2, 5, None), Ellipsis, 4, slice(None, None, - -1)) -\end_layout - -\begin_layout Description -s_ -\begin_inset LatexCommand index -name "s\\_" - -\end_inset - - [index expression] -\end_layout - -\begin_layout Description -\InsetSpace ~ - Translate index expressions into the equivalent Python objects. - This is similar to index_expression except a tuple is not always returned. - For example: -\end_layout - -\begin_layout MyCode ->>> s_[1:10] -\newline -slice(1, 10, None) -\newline ->>> s_[1:10,-3:4:0.5] -\newline -(slice(1, 10, None), slice(-3, - 4, 0.5)) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This provides a standard way to construct index expressions to pass to - functions and methods because Python does not allow slice expressions anywhere - except for inside brackets. - -\end_layout - -\begin_layout Description -ndindex -\begin_inset LatexCommand index -name "ndindex" - -\end_inset - - (*seq) -\end_layout - -\begin_layout Description -\InsetSpace ~ - A sequence of -\begin_inset Formula $N$ -\end_inset - - integers are passed in as separate arguments. - These integers are used as the upper boundaries of an -\begin_inset Formula $N$ -\end_inset - --dimensional counter that starts at 0. - The object returned is an iterator that implements the counter. -\end_layout - -\begin_layout MyCode ->>> for index in ndindex(3,3,2): -\newline -... - print index, -\newline -(0, 0, 0) (0, 0, 1) (0, 1, 0) (0, 1, 1) (0, 2, 0) (0, 2, - 1) (1, 0, 0) (1, 0, 1) (1, 1, 0) (1, 1, 1) (1, 2, 0) (1, 2, 1) (2, 0, 0) - (2, 0, 1) (2, 1, 0) (2, 1, 1) (2, 2, 0) (2, 2, 1) -\end_layout - -\begin_layout Description -unravel_index -\begin_inset LatexCommand index -name "unravel\\_index" - -\end_inset - - (indx, dims) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Convert a flat index, indx, into an index tuple for an array of the given - shape. - Keep in mind that it may be more convenient to use indx with a.flat, then - to unravel the index. -\end_layout - -\begin_layout Section -Two-dimensional functions -\end_layout - -\begin_layout Standard -These functions all deal with or return two dimensional arrays. -\end_layout - -\begin_layout Description -eye -\begin_inset LatexCommand index -name "eye" - -\end_inset - - ( -\begin_inset Formula $N$ -\end_inset - -, -\begin_inset Formula $M$ -\end_inset - -=None, -\begin_inset Formula $k$ -\end_inset - -=0, dtype=float) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an -\begin_inset Formula $N\times M$ -\end_inset - - array of the given type with ones down the -\begin_inset Formula $k^{\textrm{th}}$ -\end_inset - - diagonal. - If -\begin_inset Formula $M$ -\end_inset - - is None, it defaults to -\begin_inset Formula $N$ -\end_inset - -. - Alternatively, if -\begin_inset Formula $M$ -\end_inset - - is a valid data type, then it becomes the data-type used. - -\end_layout - -\begin_layout Description -vander -\begin_inset LatexCommand index -name "vander" - -\end_inset - - ( -\begin_inset Formula $x$ -\end_inset - -, -\begin_inset Formula $N$ -\end_inset - -=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - The Vandermonde matrix of vector, -\begin_inset Formula $x$ -\end_inset - -. - The -\begin_inset Formula $i^{\textrm{th}}$ -\end_inset - - column of the return matrix is the -\begin_inset Formula $m_{i}^{\textrm{th}}$ -\end_inset - - power of -\begin_inset Formula $x$ -\end_inset - - where -\begin_inset Formula $m_{i}=N-i-1$ -\end_inset - -. - If -\begin_inset Formula $N$ -\end_inset - - is None, it defaults to the length of -\begin_inset Formula $x$ -\end_inset - -. - -\end_layout - -\begin_layout MyCode ->>> vander([1,2,3,4,5],3) -\newline -array([[ 1, 1, 1], -\newline - [ 4, 2, 1], -\newline - - [ 9, 3, 1], -\newline - [16, 4, 1], -\newline - [25, 5, 1]]) -\end_layout - -\begin_layout Description -diag -\begin_inset LatexCommand index -name "diag" - -\end_inset - - ( -\begin_inset Formula $v$ -\end_inset - -, -\begin_inset Formula $k$ -\end_inset - -=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the -\begin_inset Formula $k^{\textrm{th}}$ -\end_inset - - diagonal if -\begin_inset Formula $v$ -\end_inset - - is a 2-d array, or returns an array with -\begin_inset Formula $v$ -\end_inset - - as the -\begin_inset Formula $k^{\textrm{th}}$ -\end_inset - - diagonal if -\begin_inset Formula $v$ -\end_inset - - is a 1-d array. - -\end_layout - -\begin_layout MyCode ->>> diag(arange(12).reshape(4,3),k=1) -\newline -array([1, 5]) -\newline ->>> diag([1,4,5,7],k=-1) -\newline -array([ -[0, 0, 0, 0, 0], -\newline - [1, 0, 0, 0, 0], -\newline - [0, 4, 0, 0, 0], -\newline - [0, - 0, 5, 0, 0], -\newline - [0, 0, 0, 7, 0]]) -\end_layout - -\begin_layout Description -diagflat -\begin_inset LatexCommand index -name "diagflat" - -\end_inset - - ( -\begin_inset Formula $v$ -\end_inset - -, -\begin_inset Formula $k$ -\end_inset - -=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a 2-d array (of the same class as -\begin_inset Formula $v$ -\end_inset - -) by placing a flattened version of -\begin_inset Formula $v$ -\end_inset - - along the -\begin_inset Formula $k^{\textrm{th}}$ -\end_inset - - diagonal. - This differs from diag in that it only creates 2-d arrays and will work - with any object that can be converted to an array (returning that object - if it also defines an __array_wrap__ method). - -\end_layout - -\begin_layout Description -fliplr -\begin_inset LatexCommand index -name "fliplr" - -\end_inset - - (m) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the array, m, with rows preserved and columns reversed in the left-right - direction. - For m.ndim > 2, this works on the first two dimensions (equivalent to m[:,::-1]) -\end_layout - -\begin_layout Description -flipud -\begin_inset LatexCommand index -name "flipud" - -\end_inset - - (m) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the array, m, with columns preserved and rows reversed in the up-down - direction. - For m.ndim > 1, this works on the first dimension (equivalent to m[::-1]) -\end_layout - -\begin_layout Description -rot90 -\begin_inset LatexCommand index -name "rot90" - -\end_inset - - (m, k=1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Rotate the first two dimensions of an array, m, by k*90 degrees in the - counterclockwise direction. - Must have m.ndim >=2. -\end_layout - -\begin_layout Description -tri -\begin_inset LatexCommand index -name "tri" - -\end_inset - - ( -\begin_inset Formula $N$ -\end_inset - -, -\begin_inset Formula $M$ -\end_inset - -= -\begin_inset Formula $N$ -\end_inset - -, k=0, dtype=aint) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Construct an -\begin_inset Formula $N\times M$ -\end_inset - - array where all the diagonals starting from the lower left corner up to - the -\begin_inset Formula $\textrm{k}^{\textrm{th}}$ -\end_inset - - diagonal are all ones. - -\end_layout - -\begin_layout Description -triu -\begin_inset LatexCommand index -name "triu" - -\end_inset - - (m, k=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a upper-triangular 2-d array from m with all the elements below - the -\begin_inset Formula $\textrm{k}^{\textrm{th}}$ -\end_inset - - diagonal set to 0. - -\end_layout - -\begin_layout Description -tril -\begin_inset LatexCommand index -name "tril" - -\end_inset - - (m, k=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a lower-triangular 2-d array from m with all the elements above - the -\begin_inset Formula $\textrm{k}^{\textrm{th}}$ -\end_inset - - diagonal set to 0. - -\end_layout - -\begin_layout Description -mat -\begin_inset LatexCommand index -name "mat" - -\end_inset - - (data, dtype=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Construct a matrix from data. - Alias for numpy.asmatrix. - The calling syntax is the same as that function. - Note that data can be a string in which case the routine uses spaces and - semi-colons to construct the matrix: -\end_layout - -\begin_layout MyCode ->>> mat('1 3 4; 5 6 9') -\newline -matrix([[1, 3, 4], -\newline - [5, 6, 9]]) -\end_layout - -\begin_layout Description -bmat -\begin_inset LatexCommand index -name "bmat" - -\end_inset - - (obj, ldict=None, gdict=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Build a matrix from sub-blocks. - This is similar to mat, except the items in the nested-sequence, or string, - should be appropriately shaped 2-d arrays. - If obj is a string, then ldict and gdict can be used to alter where the - names represented in the string are found (default is current local and - global namespace). - -\end_layout - -\begin_layout MyCode ->>> A=mat('1 2; 3 4'); B=mat('5 6; 7 8') -\newline ->>> bmat('A, B; B, A') -\newline -matrix([[1, - 2, 5, 6], -\newline - [3, 4, 7, 8], -\newline - [5, 6, 1, 2], -\newline - [7, 8, 3, 4]]) -\end_layout - -\begin_layout Section -More data type functions -\end_layout - -\begin_layout Description -issubclass_ -\begin_inset LatexCommand index -name "issubclass\\_" - -\end_inset - - (arg1, arg2) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns True if arg1 is a sub-class of arg2, otherwise returns False. - Similar to the built-in issubclass except it does not raise an error if - arg1 or arg2 are not types. - -\end_layout - -\begin_layout Description -issubdtype -\begin_inset LatexCommand index -name "issubdtype" - -\end_inset - - (arg1, arg2) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns True if the type-object of the data-type represented by arg1 is - a sub class of the type-object of the data-type represented by arg2. -\end_layout - -\begin_layout Description -iscomplexobj -\begin_inset LatexCommand index -name "iscomplexobj" - -\end_inset - - (obj) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a single True or False value depending on whether or not obj would - be interpreted as an array with complex-valued data type. -\end_layout - -\begin_layout Description -isrealobj -\begin_inset LatexCommand index -name "isrealobj" - -\end_inset - - (obj) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a single True or False value depending on whether or not obj would - be interpreted as an array with real-valued data type. -\end_layout - -\begin_layout Description -isscalar -\begin_inset LatexCommand index -name "isscalar" - -\end_inset - - (obj) -\end_layout - -\begin_layout Description -\InsetSpace ~ - True if obj is a scalar (an instance of an array data type, or a standard - Python scalar type). - There is also a sequence of called ScalarType defined in NumPy, so that - this can also be tested as type(obj) in numpy.ScalarType. - -\end_layout - -\begin_layout Description -nan_to_num -\begin_inset LatexCommand index -name "nan\\_to\\_num" - -\end_inset - - (arr) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns an array with non-finite numbers changed to finite numbers. - The mapping converts -\family typewriter -nan -\family default - to 0, -\family typewriter -inf -\family default - to the maximum value for the data type and -\family typewriter --inf -\family default - to the minimum value for the data type. -\end_layout - -\begin_layout Description -real_if_close -\begin_inset LatexCommand index -name "real\\_if\\_close" - -\end_inset - - (arr, tol=100) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a real arr if arr is complex with imaginary parts less than some - tolerance. - If tol > 1, then it represents a multiplicative factor on the value of - epsilon for the data type of arr. -\end_layout - -\begin_layout Description -cast -\begin_inset LatexCommand index -name "cast" - -\end_inset - - [dtype_or_alias] (obj) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Cast obj to an array of the given type. - This is equivalent to array(obj, copy=0).astype(dtype_or_alias). - When one type is cast to another in this fashion, a very low-level operation - takes place. - Typically, you get what your C-compiler produces for the cast, but notice - that in the case of casting to a bool type, the value becomes either a - 0 or a 1. - -\end_layout - -\begin_layout MyCode ->>> cast[bool]([1,2,0,4,0]).astype(int) -\newline -array([1, 1, 0, 1, 0]) -\end_layout - -\begin_layout Description -asfarray -\begin_inset LatexCommand index -name "asfarray" - -\end_inset - - (a, dtype=float) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an array of inexact data type (floating or complexfloating). - -\end_layout - -\begin_layout Description -mintypecode -\begin_inset LatexCommand index -name "mintypecode" - -\end_inset - - (typechars, typeset='GDFgdf', default='d') -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a minimum data type character from typeset that handles all given - typechars. - The returned type character must correspond to the data type of the smallest - size such that an array of the returned type can handle the data from an - array of type t for each t in typechars. - If the typechars does not intersect with the typeset, then default is returned. - If an element of typechars is not a string, then t=asarray(t).dtypechar - is applied. -\end_layout - -\begin_layout Description -finfo -\begin_inset LatexCommand index -name "finfo" - -\end_inset - - (dtype) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This class allows exploration of the details of how a floating point number - is represented in the computer. - It can be instantiated by an inexact data type object (or an alias for - one). - Complex-valued data types are acceptable and are equivalent to their real-value -d counterparts. - The attributes of the class are -\end_layout - -\begin_deeper -\begin_layout Description -nmant The number of bits in the floating point mantissa, or fraction. -\end_layout - -\begin_layout Description -nexp The number of bits in the floating point exponent -\end_layout - -\begin_layout Description -machep Exponent of the smallest (most negative) power of 2 that when added - to 1.0 gives something different than 1.0. - -\end_layout - -\begin_layout Description -eps Floating point precision: 2**machep. -\end_layout - -\begin_layout Description -precision Number of decimal digits of precision: int(-log10(eps)) -\end_layout - -\begin_layout Description -resolution 10**(-precision) -\end_layout - -\begin_layout Description -negep Exponent of the smallest power of 2 that, subtracted from 1.0, gives - something different than 1.0. -\end_layout - -\begin_layout Description -epsneg Floating point precision: 2**negep. -\end_layout - -\begin_layout Description -minexp Smallest (most negative) power of 2 producing -\begin_inset Quotes eld -\end_inset - -normal -\begin_inset Quotes erd -\end_inset - - numbers (no leading zeros in the mantissa). - -\end_layout - -\begin_layout Description -tiny The smallest (in magnitude) usable floating point number equal to 2**minexp. -\end_layout - -\begin_layout Description -maxexp Smallest (positive) power of 2 that causes overflow. -\end_layout - -\begin_layout Description -max The largest usable floating value: (1-epsneg)* (2**maxep) -\end_layout - -\begin_layout Description -min The most negative usable floating value: -max -\end_layout - -\end_deeper -\begin_layout Description -\InsetSpace ~ - The most useful attributes are probably eps, max, min, and tiny. -\end_layout - -\begin_layout Section -Functions that behave like ufuncs -\end_layout - -\begin_layout Standard -These functions are Python functions built on top of universal functions - (ufuncs) and also take optional output arguments. - They broadcast like ufuncs but do not have ufunc attributes. -\end_layout - -\begin_layout Description -fix -\begin_inset LatexCommand index -name "fix" - -\end_inset - - (x, y=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Round x to the nearest integer towards zero. -\end_layout - -\begin_layout Description -isneginf -\begin_inset LatexCommand index -name "isneginf" - -\end_inset - - (x, y=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - True if -\begin_inset Formula $x=-\infty$ -\end_inset - -. - Should be the same as -\family typewriter -x==NumPy.NINF -\family default -. -\end_layout - -\begin_layout Description -isposinf -\begin_inset LatexCommand index -name "isposinf" - -\end_inset - - (x, y=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - True if -\begin_inset Formula $x=+\infty.$ -\end_inset - - Should be the same as -\family typewriter -x==NumPy.PINF -\family default -. -\end_layout - -\begin_layout Description -log2 -\begin_inset LatexCommand index -name "log2" - -\end_inset - - (x, y=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Compute the logarithm to the base 2 of -\begin_inset Formula $x.$ -\end_inset - - An optional output array may be provided. -\end_layout - -\begin_layout Section -Miscellaneous Functions -\end_layout - -\begin_layout Standard -Some miscellaneous functions are available in NumPy which are included largely - for compatibility with MLab of the old Numeric package. - One notable difference, however, is that due to a separate implementation - of the modified Bessel function, the kaiser window is available without - needing a separate library. - -\end_layout - -\begin_layout Description -sinc -\begin_inset LatexCommand index -name "sinc" - -\end_inset - - ( -\begin_inset Formula $x$ -\end_inset - -) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Compute the sinc function for -\begin_inset Formula $x$ -\end_inset - - which can be a scalar or array. - The sinc is defined as -\begin_inset Formula $y=\textrm{sinc}\left(x\right)=\frac{\sin\left(\pi x\right)}{\pi x}$ -\end_inset - - with the caveat that the limiting value (1.0) of the ratio is taken for - -\begin_inset Formula $x=0.$ -\end_inset - - -\end_layout - -\begin_layout Description -i0 -\begin_inset LatexCommand index -name "i0" - -\end_inset - - ( -\begin_inset Formula $x$ -\end_inset - -) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Modified Bessel function of the first kind of order 0. - Needed to compute the kaiser window. - The modified Bessel function is defined as -\begin_inset Formula \[ -I_{0}\left(x\right)=\frac{1}{\pi}\int_{0}^{\pi}e^{x\cos\theta}d\theta=\sum_{k=0}^{\infty}\frac{x^{2k}}{4^{k}\left(k!\right)^{2}}.\] - -\end_inset - - -\end_layout - -\begin_layout Description -blackman -\begin_inset LatexCommand index -name "blackman" - -\end_inset - - ( -\begin_inset Formula $M$ -\end_inset - -) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Construct an -\begin_inset Formula $M$ -\end_inset - --point Blackman smoothing window which is sequence of length -\begin_inset Formula $M$ -\end_inset - - with values given for -\begin_inset Formula $n=0\ldots M-1$ -\end_inset - - by -\begin_inset Formula \[ -w\left[n\right]=0.42-0.5\cos\left(2\pi\frac{n}{M-1}\right)+0.08\cos\left(4\pi\frac{n}{M-1}\right).\] - -\end_inset - - -\end_layout - -\begin_layout Description -bartlett -\begin_inset LatexCommand index -name "bartlett" - -\end_inset - - ( -\begin_inset Formula $M$ -\end_inset - -) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Construct an -\begin_inset Formula $M$ -\end_inset - --point Bartlett (triangular) smoothing window as -\begin_inset Formula \[ -w\left[n\right]=\left\{ \begin{array}{cc} -2\frac{n}{M-1} & 0\leq n\leq\frac{M-1}{2},\\ -2-2\frac{n}{M-1} & \frac{M-1}{2}<n\leq M-1.\end{array}\right.\] - -\end_inset - - -\end_layout - -\begin_layout Description -hanning -\begin_inset LatexCommand index -name "hanning" - -\end_inset - - ( -\begin_inset Formula $M$ -\end_inset - -) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Construct an -\begin_inset Formula $M$ -\end_inset - --point Hanning smoothing window defined as -\begin_inset Formula \[ -w\left[n\right]=\frac{1}{2}-\frac{1}{2}\cos\left(2\pi\frac{n}{M-1}\right).\] - -\end_inset - - -\end_layout - -\begin_layout Description -hamming -\begin_inset LatexCommand index -name "hamming" - -\end_inset - - ( -\begin_inset Formula $M$ -\end_inset - -) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Construct an -\begin_inset Formula $M$ -\end_inset - --point Hamming smoothing window defined for -\begin_inset Formula $n=0\ldots M-1$ -\end_inset - - as -\begin_inset Formula \[ -w\left[n\right]=0.54-0.46\cos\left(2\pi\frac{n}{M-1}\right).\] - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - All of the windowing functions are smoothing windows that attempt to balance - the inherent trade off between side-lobe height (ringing) and main-lobe - width (resolution) in the frequency domain. - A rectangular window has the smallest main-lobe width but the largest side-lobe - height. - A windowing (tapering) function tries to can help trade off main-lobe width - By sacrificing a little in resolution using a windowing function These - windows can be used to smooth data using the convolve function. - Figure -\begin_inset LatexCommand ref -reference "cap:window functions" - -\end_inset - - shows the windowing functions described so far and their time- and frequency-do -main behavior. - -\end_layout - -\begin_layout Standard -\begin_inset Float figure -wide false -sideways false -status open - -\begin_layout Standard -\begin_inset Graphics - filename Figures/fig1.eps - lyxscale 48 - width 49line% - keepAspectRatio - -\end_inset - - -\hfill - -\begin_inset Graphics - filename Figures/fig2.eps - lyxscale 48 - width 49line% - keepAspectRatio - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset Caption - -\begin_layout Standard -\begin_inset LatexCommand label -name "cap:window functions" - -\end_inset - -Blackman, Bartlett, Hanning, and Hamming windows in the time and frequency - domain showing the trade-off between main-lobe width and side-lobe height - (Figures made with matplotlib). -\end_layout - -\end_inset - - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The trade-off between main-lobe and side-lobe has been studied extensively. - Solutions that maximize energy in the main-lobe compared to energy in the - side-lobes can be found by finding an eigenvector which can be expensive - to compute for large window sizes. - A good approximation to these prolate-spheroidal windows is the Kaiser - window. - -\end_layout - -\begin_layout Description -kaiser -\begin_inset LatexCommand index -name "kaiser" - -\end_inset - - ( -\begin_inset Formula $M$ -\end_inset - -, -\begin_inset Formula $\beta$ -\end_inset - -) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Construct an -\begin_inset Formula $M$ -\end_inset - --point Kaiser smoothing window. - The -\begin_inset Formula $\beta$ -\end_inset - - parameter controls the width of the window (and the frequency-domain side-lobe - height and main-lobe width). - The window is defined as -\begin_inset Formula \[ -w\left[n\right]=\frac{1}{I_{0}\left(\beta\right)}I_{0}\left(\beta\sqrt{1-\frac{\left(2n-M-1\right)^{2}}{\left(M-1\right)^{2}}}\right).\] - -\end_inset - - There is an empirical relationship between -\begin_inset Formula $\beta$ -\end_inset - - and the side-lobe height which can be used in FIR filter design. - To achieve a side-lobe height of -\begin_inset Formula $-\alpha$ -\end_inset - -dB, the -\begin_inset Formula $\beta$ -\end_inset - - parameter is -\begin_inset Formula \[ -\beta=\left\{ \begin{array}{cc} -0.1002\left(\alpha-8.7\right) & \alpha>50,\\ -0.5842\left(\alpha-21\right)^{0.4}+0.07886\left(\alpha-21\right) & 21\leq\alpha\leq50,\\ -0 & \alpha<21.\end{array}\right.\] - -\end_inset - - The length -\begin_inset Formula $M$ -\end_inset - - of the window determines the transition width. - To obtain a transition width of -\begin_inset Formula $\Delta\omega$ -\end_inset - -rad/s the window-length must be at least: -\begin_inset Formula \[ -M=\frac{\alpha-8}{2.285\Delta\omega}+1.\] - -\end_inset - - -\end_layout - -\begin_layout Section -Utility functions -\end_layout - -\begin_layout Description -set_numeric_ops -\begin_inset LatexCommand index -name "set\\_numeric\\_ops" - -\end_inset - - (<op1>=func1, <op2>=func2, ...) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This function can be used to alter the operations used for internal array - calculations and array special methods. - Replaceable operations (and possible entries for <opN>) are add, subtract, - multiply, divide, remainder, power, sqrt, negative, absolute, invert, left_shif -t, right_shift, bitwise_and, bitwise_or, less, less_equal, equal, not_equal, - greater, greater_equal, floor_divide, true_divide, logical_or, logical_and, - floor, ceil, maximum, and minimum. - The example code below changes, then restores, the old Numeric behavior - of remainder (which was changed because it was not consistent with Python). - -\end_layout - -\begin_layout MyCode ->>> a = array([-3.,-2,-1,0,1,2,3]) -\newline ->>> print a % -2.1 -\newline -[-0.9 -2. - -1. - 0. - -1.1 -0.1 -1.2] -\newline ->>> oldops = set_numeric_ops(remainder=fmod) -\newline ->>> print a % - -2.1 -\newline -[-0.9 -2. - -1. - 0. - 1. - 2. - 0.9] -\newline ->>> newops = set_numeric_ops(**oldops) -\newline ->>> print a % -2.1 -\newline -[-0.9 -2. - -1. - 0. - -1.1 -0.1 -1.2] -\newline ->>> print 3 % -2.1 # comparison -\newline --1.2 -\end_layout - -\begin_layout Description -get_include -\begin_inset LatexCommand index -name "get\\_include" - -\end_inset - - () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the directory that contains the numpy include files. - The numpy.distutils automatically includes this directory in building extensions. - -\end_layout - -\begin_layout Description -get_numarray_include -\begin_inset LatexCommand index -name "get\\_numarray\\_include" - -\end_inset - - (type=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the directory that contains the numarray compatible C-API include - files. - If type is not None, then return a list containing both the numarray compatible - C-API include files and the numpy include files. - The latter form is only needed when building an extension without the use - of numpy.distutils. - -\end_layout - -\begin_layout Description -deprecate -\begin_inset LatexCommand index -name "deprecate" - -\end_inset - - (func, oldname, newname) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a deprecated function named 'oldname' that has been replaced by - 'newname'. - This new deprecated function issues a warning before calling the old function. - The name and docs of the function are also updated to be oldname instead - of the name that func has. - Example usage. - If you want to deprecate the function named 'old' in favor of a new function - named 'new' which has the same calling conention then this could be done - with the assignment -\end_layout - -\begin_deeper -\begin_layout LyX-Code -old = deprecate(new, 'old', 'new') -\end_layout - -\end_deeper -\begin_layout Chapter -Scalar objects -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand label -name "cha:Scalar-objects" - -\end_inset - - -\end_layout - -\begin_layout Quotation -Never worry about numbers. - Help one person at a time, and always start with the person nearest you. -\end_layout - -\begin_layout Right Address ---- -\emph on -Mother Teresa -\end_layout - -\begin_layout Quotation -A great many people think they are thinking when they are merely rearranging - their prejudices. -\end_layout - -\begin_layout Right Address ---- -\emph on -William James -\end_layout - -\begin_layout Standard -One -\begin_inset LatexCommand index -name "array scalars|(" - -\end_inset - - important new feature of NumPy is the addition of a new scalar object for - each of the 21 different data types that an array can have. - Do not confuse these scalar objects with the data-type objects. - There is one data-type object. - It contains a -\family typewriter -.type -\family default - attribute which points to the Python type that each element of the array - will be returned as -\begin_inset Foot -status open - -\begin_layout Standard -with the exception of object data-types which return the underlying object - and not a -\begin_inset Quotes eld -\end_inset - -scalar -\begin_inset Quotes erd -\end_inset - - type. - -\end_layout - -\end_inset - -. - The built-in data-types point have . -\family typewriter -type -\family default - attributes that point to these scalar objects. - Five (or six) of these new scalar objects are essentially equivalent to - fundamental Python types and therefore inherit from them as well as from - the generic array scalar type. - The bool_ data type is very similar to the Python BooleanType but does - not inherit from it because Python's BooleanType does not allow itself - to be inherited from, and on the C-level the size of the actual bool_ data - is not the same as a Python Boolean scalar. - Table -\begin_inset LatexCommand ref -reference "cap:Array-scalar-types" - -\end_inset - - shows which array scalars inherit from basic Python types. - -\end_layout - -\begin_layout Standard -\begin_inset Float table -wide false -sideways false -status open - -\begin_layout Standard -\begin_inset Caption - -\begin_layout Standard -\begin_inset LatexCommand label -name "cap:Array-scalar-types" - -\end_inset - -Array scalar types that inherit from basic Python types. - The intc array data type might also inherit from the IntType if it has - the same number of bits as the int_ array data type on your platform. -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\align center -\begin_inset Tabular -<lyxtabular version="3" rows="6" columns="2"> -<features> -<column alignment="center" valignment="top" leftline="true" width="0"> -<column alignment="center" valignment="top" leftline="true" rightline="true" width="0"> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -array data type -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Python type -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -int_ -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -IntType -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -float_ -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -FloatType -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -complex_ -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -ComplexType -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -str_ -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -StringType -\end_layout - -\end_inset -</cell> -</row> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -unicode_ -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -UnicodeType -\end_layout - -\end_inset -</cell> -</row> -</lyxtabular> - -\end_inset - - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -The array scalars have the same attributes and methods as arrays and live - in a hierarchy of scalar types so they can be easily classified based on - their type objects. - However, because array scalars are immutable, and attributes change intrinsic - properties of the object, the -\series bold -array scalar attributes are not settable -\series default -. -\end_layout - -\begin_layout Standard -Array scalars can be detected using the hierarchy of data types. - For example, -\family typewriter -isinstance(val, generic) -\family default - will return True if val is an array scalar object. - Alternatively, what kind of array scalar is present can be determined using - other members of the data type hierarchy. - Thus, for example -\family typewriter -isinstance(val, complexfloating) -\family default - will return True if val is a complex valued type, while -\family typewriter -isinstance(val, flexible) -\family default - will return true if val is one of the flexible itemsize array types (string, - unicode, void). - -\end_layout - -\begin_layout Warning -The bool_ type is not a subclass of the int_ type (the bool_ type is not - even a number type). - This is different than Python's default implementation of bool as a sub-class - of int. -\end_layout - -\begin_layout Section -Attributes of array scalars -\end_layout - -\begin_layout Standard -The array scalar objects have an -\family typewriter -__array_priority__ -\family default - of NPY_SCALAR_PRIORITY (-1,000,000.0). - They also do not (yet) have a ctypes attribute. - Otherwise, they share the same attributes as arrays: -\end_layout - -\begin_layout Description -flags -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns True for CONTIGUOUS, OWNDATA, FORTRAN, and ALIGNED. - Always returns False for WRITEABLE, and UPDATEIFCOPY. - -\end_layout - -\begin_layout Description -shape -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns (). -\end_layout - -\begin_layout Description -strides -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns (). -\end_layout - -\begin_layout Description -ndim -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns 0. -\end_layout - -\begin_layout Description -data -\end_layout - -\begin_layout Description -\InsetSpace ~ - A read-only buffer object of size self.itemsize, -\end_layout - -\begin_layout Description -size -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return 1. -\end_layout - -\begin_layout Description -itemsize -\end_layout - -\begin_layout Description -\InsetSpace ~ - The number of bytes this scalar requires. -\end_layout - -\begin_layout Description -base -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns None. -\end_layout - -\begin_layout Description -dtype -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns data type descriptor corresponding to this array scalar. - -\end_layout - -\begin_layout Description -real -\end_layout - -\begin_layout Description -\InsetSpace ~ - The real part of the scalar. -\end_layout - -\begin_layout Description -imag -\end_layout - -\begin_layout Description -\InsetSpace ~ - The imaginary part of the scalar (or 0 if this is real). -\end_layout - -\begin_layout Description -flat -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a 1-d iterator object (of size 1). -\end_layout - -\begin_layout Description -T -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a reference to self. -\end_layout - -\begin_layout Description -__array_interface__ -\end_layout - -\begin_layout Description -\InsetSpace ~ - The Python-side to the array interface. - -\end_layout - -\begin_layout Description -__array_struct__ -\end_layout - -\begin_layout Description -\InsetSpace ~ - The C-side to the array interface -\end_layout - -\begin_layout Description -__array_priority__ -\end_layout - -\begin_layout Description -\InsetSpace ~ - -100.0 (very low-priority). - -\end_layout - -\begin_layout Description -__array_wrap__ (obj) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns an array scalar from an array -\end_layout - -\begin_layout Section -Methods of array scalars -\end_layout - -\begin_layout Standard -Array scalars have exactly the same methods as arrays. - The default behavior of these methods is to internally convert the scalar - to an equivalent 0-dimensional array and to call the corresponding array - method. - The exceptions to these rules are given below. - In addition, math operations on array scalars are defined so that the same - hardware flags are set and used to interpret the results as for ufunc. - Therefore the error state used for ufuncs also carries over to the math - on array scalars. -\end_layout - -\begin_layout Description -__new__ (obj) -\end_layout - -\begin_layout Description -\InsetSpace ~ - The default behavior is to return a new array or array scalar by calling - array(obj) with the corresponding data type. - There are two situations when this default behavior is delayed until another - approach is tried. - First, when the array scalar type inherits from a Python type, then the - Python types new method is called first and the default method is called - only if that approach fails. - The second situation is for the -\family typewriter -void -\family default - data type where a single integer-like argument will cause a void scalar - of that size to be created and initialized to 0. - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Notice that because array(obj) is called for new, if obj is a nested sequence, - then the return object could actually be an -\family typewriter -ndarray -\family default -. - Thus, arrays of the correct type can also be created by calling the array - data type name directly: -\end_layout - -\begin_layout MyCode ->>> uint32([[5,6,7,8],[1,2,3,4]]) -\newline -array([[5, 6, 7, 8], -\newline - [1, 2, 3, 4]], - dtype=uint32) -\end_layout - -\begin_layout Description -__array__ (<None>) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns a 0-dimensional array of the given data type, or of type(self) - if argument is None. -\end_layout - -\begin_layout Description -__array_wrap__ (array) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns a scalar array object from the first-element of the array. -\end_layout - -\begin_layout Description -__squeeze__ () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns self. -\end_layout - -\begin_layout Description -byteswap (<False>) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Trying to set the first (inplace) argument to True raises a ValueError. - Otherwise, this returns a new array scalar with the data byteswapped. - -\end_layout - -\begin_layout Description -__reduce__ () -\end_layout - -\begin_layout Description -\InsetSpace ~ - This is called to pickle an array scalar. - It returns a tuple of (numpy.core.multiarray.scalar, self.dtypestr, obj or - self.tostring()) which can be used to reconstruct the scalar on unpickling. - Notice that no state is written, because the entire scalar can be constructed - from just the string. - Also, if this is an object array scalar, then the Python object being reference -d is written. -\end_layout - -\begin_layout Description -__setstate__ () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Does nothing but return None. -\end_layout - -\begin_layout Description -setflags () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Does nothing, as flags cannot be set for scalars -\begin_inset LatexCommand index -name "array scalars|)" - -\end_inset - -. -\end_layout - -\begin_layout Section -Defining New Types -\end_layout - -\begin_layout Standard -There are two ways to effectively define a new type of array. - One way is to simply subclass the ndarray and overwrite the methods of - interest. - This will work to a degree, but internally certain behaviors are fixed - by the data type of the array. - To fully customize the data type of an array you need to define a new data-type - for the array, and register it with NumPy. - This new type can only be defined in C. - How to define a new data type in C will be discussed in the next part of - the book. -\end_layout - -\begin_layout Chapter -Data-type ( -\family typewriter -dtype -\family default -) Objects -\end_layout - -\begin_layout Quotation -We cannot expect that all nations will adopt like systems, for conformity - is the jailer of freedom and the enemy of growth. -\end_layout - -\begin_layout Right Address ---- -\emph on -John F. - Kennedy -\end_layout - -\begin_layout Quotation -What information consumes is rather obvious: it consumes the attention of - its recipients. - Hence, a wealth of information creates a poverty of attention and a need - to allocate that attention efficiently among the overabundance of information - sources that might consume it. -\end_layout - -\begin_layout Right Address ---- -\emph on -Herbert Simon -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand label -name "cha:Data-descriptor-objects" - -\end_inset - -It -\begin_inset LatexCommand index -name "dtype|(" - -\end_inset - - is important not to confuse the -\begin_inset Quotes eld -\end_inset - -array-scalars -\begin_inset Quotes erd -\end_inset - - with the -\begin_inset Quotes eld -\end_inset - -data-type objects. -\begin_inset Quotes erd -\end_inset - - It is true that an array-scalar can be interpreted as a data-type object - and so can be used to refer to the data-type of an array. - However, the data-type object is a separate Python object. - Every ndarray has an associated data-type object that completely defines - the data in the array (including any named fields). - For every built-in data-type object there is an associated type object - whose instances are the array-scalars. - Because of the association between each data-type object and a type-object - of the corresponding array scalar, the array-scalar type-objects can also - be thought of as data-types. - However, for the type objects of flexible array-scalars (string, unicode_, - and void), the type-objects alone are not enough to specify the full data-type - because the length is not given. - The data-type constructor, -\series bold -numpy.dtype -\series default -, converts any object that can be considered as a data-type into a data-type - object which is the actual object an ndarray looks to in order to interpret - each element of its data region. - Whenever a data-type is required in a NumPy function or method, supplying - a dtype object is always fastest. - If the object supplied is not a dtype object, then it will be converted - to one using dtype(obj). - Therefore, understanding data-type objects is the key to understanding - how data types are really represented and understood in NumPy. -\end_layout - -\begin_layout Section -Attributes -\begin_inset LatexCommand index -name "dtype!attributes|(" - -\end_inset - - -\end_layout - -\begin_layout Description -type -\begin_inset LatexCommand index -name "dtype!attributes!type" - -\end_inset - - The -\begin_inset LatexCommand index -name "The" - -\end_inset - - type object used to instantiate a scalar of this data-type. -\end_layout - -\begin_layout Description -kind -\begin_inset LatexCommand index -name "dtype!attributes!kind" - -\end_inset - - A character code (one of 'biufcSUV') identifying the general kind of data. - -\end_layout - -\begin_layout Description -char -\begin_inset LatexCommand index -name "dtype!attributes!char" - -\end_inset - - A unique character code for each of the 21 different built-in types. - -\end_layout - -\begin_layout Description -num -\begin_inset LatexCommand index -name "dtype!attributes!num" - -\end_inset - - A unique number for each of the 21 different built-in types roughly ordered - from least-to-most precision. - -\end_layout - -\begin_layout Description -str -\begin_inset LatexCommand index -name "dtype!attributes!str" - -\end_inset - - The array-protocol typestring of this data-type object. -\end_layout - -\begin_layout Description -name -\begin_inset LatexCommand index -name "dtype!attributes!name" - -\end_inset - - A bit-width name for this data-type (un-sized flexible data-type objects - are missing the width). - -\end_layout - -\begin_layout Description -byteorder -\begin_inset LatexCommand index -name "dtype!attributes!byteorder" - -\end_inset - - A character indicating the byte-order of this data-type object ('=' : native, - '<' : little-endian, '>' : big-endian, '|' : not applicable). - All built-in data-type objects have byteorder either '=' or '|'. - -\end_layout - -\begin_layout Description -itemsize -\begin_inset LatexCommand index -name "dtype!attributes!itemsize" - -\end_inset - - The element size of this data-type object. - For 18 of the 21 types this number is fixed by the data-type. - For the flexible data-types, this number can be anything. - -\end_layout - -\begin_layout Description -alignment -\begin_inset LatexCommand index -name "dtype!attributes!alignment" - -\end_inset - - The required alignment (in bytes) of this data-type according to the compiler. - More information is available in the C-API section. - -\end_layout - -\begin_layout Description -fields -\begin_inset LatexCommand index -name "dtype!attributes!fields" - -\end_inset - - A dictionary showing any named fields that have been defined for this data-type - (or None if there are no named fields). - Fields can be assigned to any built-in data-type ( -\emph on -e.g. - -\emph default - using the tuple input to the dtype constructor). - However, fields are most useful for (subtypes of) void data-types which - can be any size. - Fields are a convenient way to keep track of fixed-size sub-parts of the - total fixed-size array-element, or record. - A field is defined in terms of another dtype object and an offset (in bytes) - into the current record. - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The fields dictionary is indexed by keys that are the names of the fields. - Each entry in the dictionary is a tuple fully describing the field: (dtype, - offset[, title]). - If present, the optional title can actually be any object (if it is string - or unicode then it will also be a key in the fields dictionary, otherwise - it's meta-data). - Notice also, that the first two elements of the tuple can be passed directly - as arguments to the getfield and setfield attributes of an ndarray. - If field names are not specified in a constructor, they default to 'f0', - 'f2', ..., 'f<n-1>'. - -\end_layout - -\begin_layout Description -names -\begin_inset LatexCommand index -name "dtype!attributes!char" - -\end_inset - - An ordered list of field names. - This can be used to walk through all of the named fields in offset order. - Notice that the defined fields do not have to -\begin_inset Quotes eld -\end_inset - -cover -\begin_inset Quotes erd -\end_inset - - the record, but the itemsize of the container data-type object must always - be at least as large as the itemsizes of the data-type objects in the defined - fields. - This attribute is None if there are no fields. -\end_layout - -\begin_layout Description -subdtype -\begin_inset LatexCommand index -name "dtype!attributes!subdtype" - -\end_inset - - Numarray introduced the concept of a fixed-length record having fields - that were themselves arrays of another data-type. - This is supported at a fundamental level in NumPy using this attribute - which maintains the simplicity of defining a field by another data-type - object. - It either returns None or a tuple (base dtype, shape) where shape is a - tuple showing the size of the C-contiguous array and the base dtype object - indicates the data-type in each element of the subarray. - If a field whose dtype object has this attribute is retrieved, then the - extra dimensions implied by the shape are tacked on to the end of the retrieved - array. - -\end_layout - -\begin_layout Description -descr -\begin_inset LatexCommand index -name "dtype!attributes!descr" - -\end_inset - - An array-interface-compliant full description of the data-type. - The format is that required by the 'descr' key in the __array_interface__. -\end_layout - -\begin_layout Description -isbuiltin -\begin_inset LatexCommand index -name "dtype!attributes!isbuiltin" - -\end_inset - - A 1 if self is one of the built-in dtype objects; a 2 if self is a user-defined - dtype object; a 0, otherwise. -\end_layout - -\begin_layout Description -isnative -\begin_inset LatexCommand index -name "dtype!attributes!isnative" - -\end_inset - - True if this data-type object has a byteorder that is native to the platform; - otherwise False. -\end_layout - -\begin_layout Description -hasobject -\begin_inset LatexCommand index -name "dtype!attributes!hasobject" - -\end_inset - - True if self contains reference-counted objects in any of it's fields or - sub data-types. - Recall that what is actually in the ndarray memory representing the Python - object is the memory address of that object (a pointer). - Special handling may be required and this attribute is useful for distinguishin -g data-types that may contain arbitrary Python objects and data-types that - won't. - -\end_layout - -\begin_layout Description -flags -\begin_inset LatexCommand index -name "dtype!attributes!flags" - -\end_inset - - Bit-flags for the data-type describing how the data-type will be interpreted. - Bit-masks are in numpy.core.multiarray as the constants ITEM_HASOBJECT, LIST_PICK -LE, ITEM_IS_POINTER, NEEDS_INIT, NEEDS_PYAPI, USE_GETITEM, USE_SETITEM. - A full explanation of these flags is in the second part of this book. - These flags are largely useful for user-defined data-types. - -\begin_inset LatexCommand index -name "dtype!attributes|)" - -\end_inset - - -\end_layout - -\begin_layout Section -Construction -\end_layout - -\begin_layout Description -dtype (obj, align=0, copy=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset LatexCommand index -name "dtype!construction|(" - -\end_inset - -Return a new data-type object from obj. - The keyword argument, align, can only be nonzero if obj is a dictionary, - or a comma-separated string. - If it is non-zero in those cases it is used to add padding as needed to - the fields to match what the compiler that compiled NumPy would do to a - similar C-struct. - The copy argument guarantees a new copy of the data-type object, otherwise, - the result may just be a reference to a built-in data-type object. -\end_layout - -\begin_layout Description -\InsetSpace ~ - Objects that can be converted to a data-type object are described in the - following list. - Because every object in this list can be converted to a data-type object - it can also be used whenever a -\family typewriter -dtype -\family default - is requested by a function or method in NumPy. - -\end_layout - -\begin_deeper -\begin_layout Description -dtype -\begin_inset LatexCommand index -name "dtype!construction!from float" - -\end_inset - -Returns itself. -\end_layout - -\begin_layout Description -None -\begin_inset LatexCommand index -name "dtype!construction!from None" - -\end_inset - -Returns the default data-type descriptor object: float. -\end_layout - -\begin_layout Description -type-object -\begin_inset LatexCommand index -name "dtype!construction!from type" - -\end_inset - -Many Python type objects can be converted to data-type objects. -\end_layout - -\begin_deeper -\begin_layout Enumerate -Array-scalar types: The type-objects of the 21 built-in array scalars all - convert to an associated data-type object. - This is true for sub-classes as well. - Not all data-type information can be supplied with a type-object. - Flexible data-types with default itemsizes of 0, for example, require an - itemsize to be useful. -\end_layout - -\begin_deeper -\begin_layout Description -Examples: int32, float64, uint16, complex128 -\end_layout - -\end_deeper -\begin_layout Enumerate -Generic types: The generic hierarchical type objects convert to corresponding - dtype objects according to the associations: (numeric, inexact, floating) - --> float; complexfloating --> cfloat; (integer, signedinteger) --> int_; - unsignedinteger --> uint; character --> string; (generic, flexible) --> - void. - -\end_layout - -\begin_layout Enumerate -Builtin types: Several python types are equivalent to a corresponding array - scalar when used to generate a dtype object: int --> int_; bool --> bool_; - float --> float_; complex --> cfloat; str --> string; unicode --> unicode_; - buffer --> void; (all others) --> object_. -\end_layout - -\begin_deeper -\begin_layout Description -Examples: object, str, float, int -\end_layout - -\end_deeper -\begin_layout Enumerate -Any type object with the dtype attribute: The attribute will be accessed - and used directly. - The attribute must return something that is convertible into a dtype object. - -\end_layout - -\end_deeper -\begin_layout Description -string -\begin_inset LatexCommand index -name "dtype!construction!from string" - -\end_inset - -Several kinds of strings can be converted. - Recognized strings can be pre-pended with '>', or '<', to specify the byteorder. -\end_layout - -\begin_deeper -\begin_layout Enumerate -One-character strings: Each built-in data-type has a character code (the - updated Numeric typecodes), that uniquely identifies it. - -\end_layout - -\begin_deeper -\begin_layout Description -Examples: 'b', 'H', 'f', 'd', 'F', 'D', Float64, Int32, UInt16 -\end_layout - -\end_deeper -\begin_layout Enumerate -Array-protocol type strings: The first character specifies the kind of data - and the remaining characters specify how many bytes of data. - The supported kinds are 'b' --> Boolean, 'i' --> (signed) integer, 'u' - --> unsigned integer, 'f' --> floating-point, 'c' --> complex-floating - point, 'S', 'a' --> string, 'U' --> unicode, 'V' --> anything (void). - -\end_layout - -\begin_deeper -\begin_layout Description -Examples: 'i4', 'f8', 'c16', 'b1', 'S10', 'a25' -\end_layout - -\end_deeper -\begin_layout Enumerate -Comma-separated field formats: numarray introduced a short-hand notation - for specifying the format of a record as a comma-separated string of basic - formats. - A basic format in this context is an optional shape specifier followed - by an array-protocol type string. - Parenthesis are required on the shape if it is greater than 1-d. - NumPy allows a modification on the format in that any string that can uniquely - identify the type can be used to specify the data-type in a field. - This data-type defines fields named 'f0', 'f2', ..., 'f<N-1>' where N (>1) - is the number of comma-separated basic formats in the string. - If the optional shape specifier is provided, then the data-type for the - corresponding field contains a subdtype attribute providing the shape. - -\end_layout - -\begin_deeper -\begin_layout Description -Examples: -\begin_inset Quotes eld -\end_inset - -i4, (2,3)f8, f4 -\begin_inset Quotes erd -\end_inset - -; -\begin_inset Quotes eld -\end_inset - -a3, 3u8, (3,4)a10 -\begin_inset Quotes erd -\end_inset - - -\end_layout - -\end_deeper -\begin_layout Enumerate -Any string in NumPy.sctypeDict.keys(): -\end_layout - -\begin_deeper -\begin_layout Description -Examples: 'uint32', 'Int16', 'Uint64', 'Float64', 'Complex64' -\end_layout - -\end_deeper -\end_deeper -\begin_layout Description -tuple -\begin_inset LatexCommand index -name "dtype!construction!from tuple" - -\end_inset - -Three kinds of tuples each of length 2 can be converted into a data-type - object: -\end_layout - -\begin_deeper -\begin_layout Enumerate -(flexible dtype, itemsize): The first argument must be an object that is - converted to a flexible data-type object (one whose element size is 0), - the second argument is an integer providing the desired itemsize. -\end_layout - -\begin_deeper -\begin_layout Description -Examples: (void, 10); (str, 35), ('U', 10) -\end_layout - -\end_deeper -\begin_layout Enumerate -(fixed dtype, shape): The first argument is any object that can be converted - into a fixed-size data-type object. - The second argument is the desired shape of this type. - If the shape parameter is 1, then the data-type object is equivalent to - fixed dtype. -\end_layout - -\begin_deeper -\begin_layout Description -Examples: (int32, (2,5)); ('S10', 1)=='S10'; ('i4, (2,3)f8, f4', (2,3)) -\end_layout - -\end_deeper -\begin_layout Enumerate -(base dtype, new dtype): Both arguments must be convertible to data-type - objects in this case. - The base dtype is the data-type object that the new data-type builds on. - This is how you could assign named fields to any built-in data-type object. - -\end_layout - -\begin_deeper -\begin_layout Description -Examples: (int32, {'real':(int16,0), 'imag':(int16,2)}); (int32, (int8, - 4)); -\newline -('i4', [('r','u1'),('g','u1'),('b','u1'),('a','u1')]) -\end_layout - -\end_deeper -\end_deeper -\begin_layout Description -list -\begin_inset LatexCommand index -name "dtype!construction!from list" - -\end_inset - -(array description interface): This style is more fully described at -\begin_inset LatexCommand url -name "this site" -target "http://numpy.scipy.org/array_interface.html" - -\end_inset - -. - It consists of a list of fields where each field is described by a tuple - of length 2 or 3. - The first element of the tuple is the field name (if this is '' then a - standard field name, 'f#', is assigned). - The field name may also be a 2-tuple of strings where the first string - is either a -\begin_inset Quotes eld -\end_inset - -title -\begin_inset Quotes erd -\end_inset - - (which may be any string or unicode string) or meta-data for the field - which can be any object, and the second string is the -\begin_inset Quotes eld -\end_inset - -name -\begin_inset Quotes erd -\end_inset - - which must be a valid Python identifier. - The second element of the tuple can be anything that can be interpreted - as a data-type. - The optional third element of the tuple contains the shape if this field - represents an array of the data-type in the second element. - This style does not accept align=1 as it is assumed that all of the memory - is accounted for by the array interface description. - See the web-page for more examples. - Note that a 3-tuple with a third argument equal to 1 is equivalent to a - 2-tuple. -\end_layout - -\begin_layout Description -Examples: [('big','>i4'), ('little','<i4')]; [('R','u1'), ('G','u1'), ('B','u1') -, ('A','u1')] -\end_layout - -\begin_layout Description -dictionary -\begin_inset LatexCommand index -name "dtype!construction!from dict" - -\end_inset - -There are two dictionary styles. - The first is a standard dictionary format while the second accepted format - allows the fields attribute of dtype objects to be interpreted as a data-type. - -\end_layout - -\begin_deeper -\begin_layout Enumerate -names and formats: This style has two required and two optional keys. - The 'names' and 'formats' keys are required. - Their respective values are equal-length lists with the field names and - the field formats. - The field names must be strings and the field formats can be any object - accepted by dtypedescr constructor. - The optional keys in the dictionary are 'offsets' and 'titles' and their - values must each be lists of the same length as the 'names' and 'formats' - lists. - The 'offsets' value is a list of integer offsets for each field, while - the 'titles' value is a list of titles for each field (None can be used - if no title is desired for that field). - The titles can be any string or unicode object and will add another entry - to the fields dictionary keyed by the title and referencing the same field - tuple which will contain the title as an additional tuple member. - -\end_layout - -\begin_deeper -\begin_layout Description -Examples: {'names': ['r','g','b','a'], 'formats': [uint8, uint8, uint8, - uint8]}; {'names':['r','b'], 'formats': ['u1', 'u1'], 'offsets': [0, 2], - 'titles': ['Red pixel', 'Blue pixel']} -\end_layout - -\end_deeper -\begin_layout Enumerate -data-type object fields: This style is patterned after the format of the - fields dictionary in a data-type object. - It contains string or unicode keys that refer to (data-type, offset) or - (data-type, offset, title) tuples. - -\end_layout - -\begin_deeper -\begin_layout Description -Examples: {'col1': ('S10', 0), 'col2': (float32, 10), 'col3': (int, 14)} -\begin_inset LatexCommand index -name "dtype!construction|)" - -\end_inset - - -\end_layout - -\end_deeper -\end_deeper -\end_deeper -\begin_layout Section -Methods -\begin_inset LatexCommand index -name "dtype!methods|(" - -\end_inset - - -\end_layout - -\begin_layout Description -newbyteorder -\begin_inset LatexCommand index -name "dtype!methods!newbyteorder" - -\end_inset - -(<'swap'>) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Construct a new copy of self with its byteorder changed according to the - optional argument. - All changes are also propagated to the data-type objects of all fields - and sub-arrays. - If a byteorder of '|' (meaning ignore) is encountered it is left unchanged. - The default behavior is to swap the byteorder. - Other possible arguments are 'big' ('>'), 'little' ('<'), and 'native' - ('=') which recursively forces the byteorder of self (and it's field data-type - objects and any sub-arrays) to the corresponding byteorder. - -\end_layout - -\begin_layout Description -__reduce__ -\begin_inset LatexCommand index -name "dtype!methods!\\_\\_reduce\\_\\_" - -\end_inset - - () -\end_layout - -\begin_layout Description -__setstate__ -\begin_inset LatexCommand index -name "dtype!methods!\\_\\_setstate\\_\\_" - -\end_inset - - (state) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Data-type objects can be pickled because of these two methods. - The __reduce__() method returns a 3-tuple consisting of (callable object, - args, state), where the callable object is numpy.core.multiarray.dtype and - args is (typestring, 0, 1) unless the data-type inherits from void (or - is user-defined) in which case args is (typeobj, 0, 1). - The state is an 8-tuple with (version, endian, self.subdtype, self.names, - self.fields, self.itemsize, self.alignment, self.flags). - The self.itemsize and self.alignment entries are both -1 if the data-type - object is built-in and not flexible (because they are fixed on creation). - The setstate method takes the saved state and updates the date-type -\begin_inset LatexCommand index -name "dtype!methods|)" - -\end_inset - -object. -\begin_inset LatexCommand index -name "dtype|)" - -\end_inset - - -\end_layout - -\begin_layout Chapter -Standard Classes -\end_layout - -\begin_layout Quotation -To generalize is to be an idiot. - -\end_layout - -\begin_layout Right Address ---- -\emph on -William Blake -\end_layout - -\begin_layout Quotation -Not everything that can be counted counts, and not everything that counts - can be counted. -\end_layout - -\begin_layout Right Address ---- -\emph on -Albert Einstein -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "ndarray!subtyping|(" - -\end_inset - -The ndarray in NumPy is a -\begin_inset Quotes eld -\end_inset - -new-style -\begin_inset Quotes erd -\end_inset - - Python built-in-type. - Therefore, it can be inherited from (in Python or in C) if desired. - Therefore, it can form a foundation for many useful classes. - Often whether to sub-class the array object or to simply use the core array - component as an internal part of a new class is a difficult decision, and - can be simply a matter of choice. - NumPy has several tools for simplifying how your new object interacts with - other array objects, and so the choice may not be significant in the end. - One way to simplify the question is by asking yourself if the object you - are interested can be replaced as a single array or does it really require - two or more arrays at it's core. - For example, in the standard NumPy distribution, the matrix and records - classes inherit from the ndarray, while masked arrays use two ndarrays - as objects of its internal structure. -\end_layout - -\begin_layout Standard -Note that asarray(a) always returns the base-class ndarray. - If you are confident that your use of the array object can handle any subclass - of an ndarray, then asanyarray(a) can be used to allow subclasses to propagate - more cleanly through your subroutine. - In principal a subclass could redefine any aspect of the array and therefore, - under strict guidelines, asanyarray(a) would rarely be useful. - However, most subclasses of the arrayobject will not redefine certain aspects - of the array object such as the buffer interface, or the attributes of - the array. - One of important example, however, of why your subroutine may not be able - to handle an arbitrary subclass of an array is that matrices redefine the - '*' operator to be matrix-multiplication, rather than element-by-element - multiplication. -\end_layout - -\begin_layout Section -Special attributes and methods recognized by NumPy -\begin_inset LatexCommand index -name "ndarray!attributes!recognized by|(" - -\end_inset - - -\end_layout - -\begin_layout Description -__array_finalize__ (obj) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This method is called whenever the system internally allocates a new array - from obj, where obj is a subclass (subtype) of the (big)ndarray. - It can be used to change attributes of self after construction (so as to - ensure a 2-d matrix for example), or to update meta-information from the - -\begin_inset Quotes eld -\end_inset - -parent. -\begin_inset Quotes erd -\end_inset - - Subclasses inherit a default implementation of this method that does nothing. -\end_layout - -\begin_layout Description -__array_wrap__ (array) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This method should return an instance of the class from the ndarray object - passed in. - For example, this is called after every ufunc for the object with the highest - __array_priority__. - The ufunc-computed array object is passed in and whatever is returned is - passed to the user. - Subclasses inherit a default implementation of this method. -\end_layout - -\begin_layout Description -__array__ (dtype <None>) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This method is called to obtain an ndarray object when needed. - You should always guarantee this returns an actual ndarray object. - Subclasses inherit a default implementation of this method. - -\end_layout - -\begin_layout Description -__array_priority__ -\end_layout - -\begin_layout Description -\InsetSpace ~ - The value of this attribute is used to determine what type of object to - return in situations where there is more than one possibility for the Python - type of the returned object. - Subclasses inherit a default value of 1.0 for this attribute. -\begin_inset LatexCommand index -name "ndarray!attributes!recognized by|)" - -\end_inset - - -\begin_inset LatexCommand index -name "ndarray!subtyping|)" - -\end_inset - - -\end_layout - -\begin_layout Section -Matrix Objects -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "matrix|(" - -\end_inset - -Matrix objects inherit from the ndarray and therefore, they have the same - attributes and methods of ndarrays. - There are six important differences of matrix objects, however that may - lead to unexpected results when you use matrices but expect them to act - like arrays: -\end_layout - -\begin_layout Enumerate -Matrix objects can be created using a string notation to allow Matlab-style - syntax where spaces separate columns and semicolons (';') separate rows. - -\end_layout - -\begin_layout Enumerate -Matrix objects are always two-dimensional. - This has far-reaching implications, in that m.ravel() is still two-dimensional - (with a 1 in the first dimension) and item selection returns two-dimensional - objects so that sequence behavior is fundamentally different than arrays. -\end_layout - -\begin_layout Enumerate -Matrix objects over-ride multiplication to be matrix-multiplication. - -\series bold -Make sure you understand this for functions that you may want to receive - matrices. - Especially in light of the fact that asanyarray(m) returns a matrix when - m is a matrix. -\end_layout - -\begin_layout Enumerate -Matrix objects over-ride power to be matrix raised to a power. - The same warning about using power inside a function that uses asanyarray(...) - to get an array object holds for this fact. - -\end_layout - -\begin_layout Enumerate -The default __array_priority__ of matrix objects is 10.0, and therefore mixed - operations with ndarrays always produce matrices. - -\end_layout - -\begin_layout Enumerate -Matrices have special attributes which make calculations easier. - These are -\end_layout - -\begin_deeper -\begin_layout Enumerate -.T --- return the transpose of self -\end_layout - -\begin_layout Enumerate -.H --- return the conjugate transpose of self -\end_layout - -\begin_layout Enumerate -.I --- return the inverse of self -\end_layout - -\begin_layout Enumerate -.A --- return a view of the data of self as a 2d array (no copy is done). -\end_layout - -\end_deeper -\begin_layout Warning -Matrix objects over-ride multiplication, '*', and power, '**', to be matrix-mult -iplication and matrix power, respectively. - If your subroutine can accept sub-classes and you do not convert to base-class - arrays, then you must use the ufuncs multiply and power to be sure that - you are performing the correct operation for all inputs. - -\end_layout - -\begin_layout Standard -The matrix class is a Python subclass of the ndarray and can be used as - a reference for how to construct your own subclass of the ndarray. - Matrices can be created from other matrices, strings, and anything else - that can be converted to an -\family typewriter -ndarray -\family default -. - The name -\begin_inset Quotes eld -\end_inset - -mat -\begin_inset Quotes erd -\end_inset - - is an alias for -\begin_inset Quotes eld -\end_inset - -matrix -\begin_inset Quotes erd -\end_inset - - in NumPy. -\end_layout - -\begin_layout Description -Example\InsetSpace ~ -1: Matrix creation from a string -\end_layout - -\begin_layout MyCode ->>> a=mat('1 2 3; 4 5 3') -\newline ->>> print (a*a.T).I -\newline -[[ 0.2924 -0.1345] -\newline - [-0.1345 0.0819]] -\end_layout - -\begin_layout Description -Example\InsetSpace ~ -2: Matrix creation from nested sequence -\end_layout - -\begin_layout MyCode ->>> mat([[1,5,10],[1.0,3,4j]]) -\newline -matrix([[ 1.+0.j, 5.+0.j, 10.+0.j], -\newline - [ - 1.+0.j, 3.+0.j, 0.+4.j]]) -\end_layout - -\begin_layout Description -Example\InsetSpace ~ -3: Matrix creation from an array -\end_layout - -\begin_layout MyCode ->>> mat(random.rand(3,3)).T -\newline -matrix([[ 0.7699, 0.7922, 0.3294], -\newline - [ 0.2792, - 0.0101, 0.9219], -\newline - [ 0.3398, 0.7571, 0.8197]]) -\end_layout - -\begin_layout Description -matrix (data, dtype=None, copy=True) -\end_layout - -\begin_layout Description -\InsetSpace ~ - The sequence to convert to a matrix is passed in as data. - If dtype is None, then the data-type is determined from the data. - If copy is True, then a copy of the data is made, otherwise, the same data - buffer is used. - If no buffer can be found for data, then a copy is also made. - Note: The matrix object is actually a class and so using this syntax calls - matrix.__new__(matrix, data, dtype, copy) which is what happens whenever - you -\begin_inset Quotes eld -\end_inset - -call -\begin_inset Quotes erd -\end_inset - - any class object as a function. -\end_layout - -\begin_layout Description -mat -\end_layout - -\begin_layout Description -\InsetSpace ~ - Just another name for matrix. -\end_layout - -\begin_layout Description -asmatrix (data, dtype=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns the data without copying. - Equivalent to matrix(data, dtype, copy=False). -\end_layout - -\begin_layout Description -bmat (obj, ldict=None, gdict=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Build a matrix object from a string, nested sequence or an array. - This command lets you build up matrices from other other objects. - The ldict and gdict parameters are local and module (global) dictionaries - that are only used when obj is a string. - If they are not provided, then the local and module dictionaries present - when bmat is called are used. -\begin_inset LatexCommand index -name "matrix|)" - -\end_inset - - -\end_layout - -\begin_layout MyCode ->>> A = mat('2 2; 2 2'); B=mat('1 1; 1 1'); -\newline ->>> print bmat('A B; B A') -\newline -[[2 - 2 1 1] -\newline - [2 2 1 1] -\newline - [1 1 2 2] -\newline - [1 1 2 2]] -\end_layout - -\begin_layout Section -Memory-mapped-file arrays -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "memory maps|(" - -\end_inset - -Memory-mapped files are useful for reading and/or modifying small segments - of a large file with regular layout, without reading the entire file into - memory. - A simple subclass of the ndarray uses a memory-mapped file for the data - buffer of the array. - For small files, the over-head of reading the entire file into memory is - typically not significant, however for large files using memory mapping - can save considerable resources. - -\end_layout - -\begin_layout Note -Memory-mapped arrays use the the Python memory-map object which (prior to - Python 2.5) does not allow files to be larger than a certain size depending - on the platform. - This size is always < 2GB even on 64-bit systems. - -\end_layout - -\begin_layout Standard -The class is called memmap and is available in the NumPy namespace. - The __new__ method of the class has been re-written to have the following - syntax: -\end_layout - -\begin_layout Description -__new__ (cls, filename, dtype=uint8, mode='r+', offset=0, shape=None, order=0) - -\end_layout - -\begin_deeper -\begin_layout Description -filename The file name to be used as the array data buffer -\end_layout - -\begin_layout Description -dtype A data-type object used to interpret the file contents (including - byteorder). -\end_layout - -\begin_layout Description -mode The mode to open the file in. - Valid modes are 'readonly' or 'r', 'copyonwrite' or 'c', 'readwrite' or - 'r+', and 'write' or 'w+'. - This mode determines the WRITEABLE flag of the returned array. -\end_layout - -\begin_layout Description -offset An offset into the file to start the array data. -\end_layout - -\begin_layout Description -shape The desired shape of the array. - If this is None, then the returned array will be 1-d with the number of - elements determined by the file size and data type. -\end_layout - -\begin_layout Description -order Either 'C' or 'Fortran' to indicate the order that an N-D array should - be interpreted. - This only has an effect if the shape is greater than 2-D. -\end_layout - -\end_deeper -\begin_layout Standard -Memory-mapped-file arrays have one additional method (besides those they - inherit from the ndarray): self. -\series bold -sync -\series default -() which must be called manually by the user to ensure that any changes - to the array actually get written to disk. - -\end_layout - -\begin_layout Description -Example: -\end_layout - -\begin_layout MyCode ->>> a = memmap('newfile.dat', dtype=float, mode='w+', shape=1000) -\newline ->>> a[10] - = 10.0 -\newline ->>> a[30] = 30.0 -\newline ->>> del a -\newline ->>> b = fromfile('newfile.dat', dtype=float) -\newline ->>> - print b[10], b[30] -\newline -10.0 30.0 -\newline ->>> a = memmap('newfile.dat', dtype=float) -\newline ->>> print - a[10], a[30] -\newline -10.0 30.0 -\end_layout - -\begin_layout Section -Character arrays (numpy.char) -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "character arrays|(" - -\end_inset - -These are enhanced arrays of either string type or unicode_ type. - These arrays inherit from the ndarray, but specially-define the operations - +, *, and % on a (broadcasting) element-by-element basis. - These operations are not available on the standard ndarray of character - type. - In addition, the chararray has all of the standard string (and unicode) - methods, executing them on an element-by-element basis. - Perhaps the easiest way to create a chararray is to use self.view(chararray) - where self is an ndarray of string or unicode data-type. - However, a chararray can also be created using the numpy.chararray.__new__ - method. -\end_layout - -\begin_layout Description -__new__ (shape, itemsize, unicode=False, buffer=None, offset=0, strides=None, - order=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Create a new character array of string or unicode type and itemsize characters. - Create the array using buffer (with offset and strides) if it is not None. - If buffer is None, then construct a new array with strides in Fortran order - if len(shape) >=2 and order is 'Fortran' (otherwise the strides will be - in 'C' order). - -\end_layout - -\begin_layout Description -char.array (obj, itemsize=None, copy=True, unicode=False, order=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Create a chararray from the nested sequence obj. - If obj is an ndarray of data-type unicode_ or string, then its data is - wrapped by the chararray object and converted to the desired type (string - or unicode). - -\end_layout - -\begin_layout Standard -Another difference with the standard ndarray of string data-type is that - the chararray inherits the feature introduced by Numarray that white-space - at the end of any element in the array will be ignored on item retrieval - and comparison operations. - -\begin_inset LatexCommand index -name "character arrays|)" - -\end_inset - - -\end_layout - -\begin_layout Section -Record Arrays (numpy.rec) -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "record arrays|(" - -\end_inset - -NumPy provides a powerful data-type object that allows any ndarray to hold - (arbitrarily nested) record-like items with named-field access to the sub-types. - This is possible without any special record-array sub-class. - Consider the example where each item in the array is a simple record of - name, age, and weight. - You could specify a data-type for an array of such records using the following - data-type object: -\end_layout - -\begin_layout MyCode ->>> desc = dtype({'names': ['name', 'age', 'weight'], 'formats': ['S30', - 'i2', 'f4']}) -\newline ->>> a = array([('Bill',31,260.0),('Fred', 15, 145.0)],dtype=desc) -\newline ->>> - print a[0] -\newline -('Bill', 31, 260.0) -\newline ->>> print a['name'] -\newline -['Bill' 'Fred'] -\newline ->>> print - a['age'] -\newline -[31 15] -\newline ->>> print a['weight'] -\newline -[ 260. - 145.] -\newline ->>> print a[0]['name'], a[0]['age'], a[0]['weight'] -\newline -Bill 31 260.0 -\newline ->>> - print len(a[0]) -\newline -3 -\end_layout - -\begin_layout Standard -This example shows how a general array can be assigned named fields and - how these fields can be accessed. - In this case the a[0] object is an array-scalar of type void. - The void array-scalars are unique in that they contain references to (rather - than copies of) the underlying data whenever fields are defined. - Therefore, the record data can be modified in place: -\end_layout - -\begin_layout MyCode ->>> a[0]['name'] = 'George'; print a -\newline -[('George', 31, 260.0) ('Fred', 15, 145.0)] -\end_layout - -\begin_layout Standard -The recarray subclass and its accompanying record item add the ability to - access named fields through attribute lookup. - A quick way to get a record array is to use the view method of the ndarray. - -\end_layout - -\begin_layout MyCode ->>> r = a.view(recarray) -\newline ->>> print r.name -\newline -['George' 'Fred'] -\end_layout - -\begin_layout Standard -The numpy.core.records module (aliased to nump.rec when numpy is imported) - contains additional convenience functions for constructing record arrays. - All of the following constructors have two different mechanisms for specifying - the data-type. - Either the dtype= argument can be specified or the argument formats= can - be specified along with an optional set of four additional keyword arguments - (names=, titles=, aligned= and byteorder=). - In some cases neither dtype= nor formats= is required as the data-type - can be inferred from the object passed in as the first argument. -\end_layout - -\begin_layout Standard -The five argument method for specifying a data-type constructs a data-type - object internally. - The comma-separated formats string is used to specify the fields. - The names (and optional titles) of the fields can be specified by a comma-separ -ated string of names (or titles). - The aligned flag determines whether the fields are packed (False) or padded - (True) according to the platform compiler rules. - The byteorder argument allows specification of the byte-order for all of - the fields at once (they can also be specified individually in the formats - string). - The default byte-order is native to the platform. - -\end_layout - -\begin_layout Description -array (obj, dtype=None, shape=None, offset=0, strides=None, formats=None, - names=None, titles=None, aligned=False, byteorder=None, copy=True) -\end_layout - -\begin_layout Description -\InsetSpace ~ - A general-purpose record array constructor that is a front-end to the other - constructors If obj is None, then call the -\series bold -recarray -\series default - constructor. - If obj is a string, then call the -\series bold -fromstring -\series default - constructor. - If obj is a list or a tuple then if the first object is an ndarray, then - call -\series bold -fromarrays -\series default -, otherwise call -\series bold -fromrecords -\series default -. - If obj is a recarray, then make a copy of the data in recarray (if copy - is True) and use the new formats, names, and titles. - If obj is a file then call -\series bold -fromfile -\series default -. - Finally, if obj is an ndarray, then return obj.view(recarray) and make a - copy of the data if copy is True. - Otherwise, call the __array_interface__ attribute and try to convert using - the information returned from that object. - Either dtype or the formats argument must be given if obj is None, a string, - or a file, and if obj is None so the recarray constructor will be called, - then shape must be given as well. - -\end_layout - -\begin_layout Description -fromarrays (array_list, dtype=None, shape=None, formats=None, names=None, - titles=None, aligned=False, byteorder=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Create a record array from a (flat) list of ndarrays. - The data from the arrays will be copied into the fields. - If formats is None and dtype is None, then the formats will be determined - from the arrays. - The names and titles arguments can be a list, tuple or a (comma-separated) - string specifying the names and/or titles to use for the fields. - If aligned is True, then the structure will be padded according to the - rules of the compiler that NumPy was compiled with. -\end_layout - -\begin_layout MyCode ->>> x1 = array([21,32,14]) -\newline ->>> x2 = array(['my','first','name']) -\newline ->>> x3 = - array([3.1, 4.5, 6.2]) -\newline ->>> r = rec.fromarrays([x1,x2,x3], names='id, word, number') -\newline -> ->> print r[1] -\newline -(32, 'first', 4.5) -\newline ->>> r.number -\newline -array([ 3.1, 4.5, 6.2]) -\newline ->>> r.word -\newline -chararra -y(['my', 'first', 'name'], -\newline - dtype='|S5') -\end_layout - -\begin_layout Description -fromrecords (rec_list, dtype=None, shape=None, formats=None, names=None, - titles=None, aligned=False, byteorder=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Construct a record array from a (nested) sequence of tuples that define - the records. - If formats are not given, they are deduced from the records, but this is - slower. - The field names and field titles can be specified. - If aligned is non-zero, then the record array is padded so that fields - are aligned as the platform compiler would do if the fields represented - a C-struct. -\end_layout - -\begin_layout MyCode ->>> recs = [('Bill', 31, 260.0), ('Fred', 15, 145.0)] -\newline ->>> r = rec.fromrecords(recs, - formats='S30,i2,f4', names='name, age, weight') -\newline ->>> print r.name -\newline -['Bill' 'Fred'] -\newline ->> -> print r.age -\newline -[31 15] -\newline ->>> print r.weight -\newline -[ 260. - 145.] -\end_layout - -\begin_layout Description -fromstring (datastring, dtype=None, shape=None, offset=0, formats=None, - names=None, titles=None, aligned=0, byteorder=None): -\end_layout - -\begin_layout Description -\InsetSpace ~ - Construct a record array using the provided datastring (at the given offset) - as the memory. - The record array will be read-only. - The byteorder argument may be used to specify the byteorder of all of the - fields at the same time. - A True aligned argument causes padding fields to be added as needed so - that the fields are aligned on boundaries determined by the compiler. - The shape of the returned array can also be specified. - -\end_layout - -\begin_layout Description -fromfile (fd, dtype=None, shape=None, offset=0, formats=None, names=None, - titles=None, aligned=False, byteorder=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Construct a record array from the (binary) data in the given file object, - fd. - This object may be an open file or a string to indicate a file to read - from. - If offset is non-zero, then data is read from the file at offset bytes - from the current position. - -\end_layout - -\begin_layout Standard -The following classes are also available in the numpy.core (and therefore - the numpy) namespace -\end_layout - -\begin_layout Description -record A subclass of the void array scalar type that allows field access - using attributes. - -\end_layout - -\begin_layout Description -recarray A subclass of the ndarray that allows field access using attributes -\end_layout - -\begin_deeper -\begin_layout Description -__new__ (subtype, shape, formats, names=None, titles=None, buf=None, offset=0, - strides=None, byteorder=None, aligned=0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Construct an array of the given subtype and shape with data-type (record, - dtype) where dtype is constructed from formats, names, and titles. - If buf is None, then create new memory. - Otherwise, use the memory of buf exposed through the buffer protocol. -\end_layout - -\end_deeper -\begin_layout Description -format_parser A class useful for creating a data-type descriptor from formats, - names, titles, and aligned arguments. - This is used by several of the record array constructors for consistency - in behavior. - -\end_layout - -\begin_deeper -\begin_layout Description -__init__ (self, formats, names, titles, aligned=False, byteorder=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Construct a data-type object from formats, names, titles, aligned, and - byteorder arguments. - Upon completion the constructed data-type object is in self._descr. - -\begin_inset LatexCommand index -name "record arrays|)" - -\end_inset - - -\end_layout - -\end_deeper -\begin_layout Section -Masked Arrays (numpy.ma) -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "masked arrays|(" - -\end_inset - -These are adapted from the masked arrays provided with Numeric. - Masked Arrays do not inherit from the ndarray, they simply use two ndarray - objects in their internal representation. - Fortunately, as I have not used masked arrays in my work, Paul Dubois (the - original author of MA for Numeric) adapted and modified the code for use - by NumPy. - Alexander Belopolsky (Sasha) added additional functions and improvements - -\end_layout - -\begin_layout Standard -Masked arrays are created using the masked array creation function. - -\end_layout - -\begin_layout Description -ma.array (data, dtype=None, copy=True, order='C', mask=ma.nomask, fill_value=None) -\end_layout - -\begin_deeper -\begin_layout Description -data Something that can be converted to an array. - If data is already a masked array, then if mask is ma.nomask, the mask used - be data.mask and the data used data.data. - -\end_layout - -\begin_layout Description -dtype The data-type of the underlying array -\end_layout - -\begin_layout Description -copy If copy is False, then every effort will be made to not copy the data. - -\end_layout - -\begin_layout Description -order Specify whether the array is in 'C', 'Fortran', or 'Any' order -\end_layout - -\begin_layout Description -mask Masked values are excluded from calculations. - If this is ma.nomask, then there are no masked values. - Otherwise, this should be an object that is convertible to an array of - Booleans with the same shape as data. -\end_layout - -\begin_layout Description -fill_value This value is used to fill in masked values when necessary. - The fill_value is not used for computation for functions within the ma - module. -\end_layout - -\end_deeper -\begin_layout Standard -Masked arrays have the same methods and attributes as arrays with the addition - of the mask attribute as well as the -\begin_inset Quotes eld -\end_inset - -hidden -\begin_inset Quotes erd -\end_inset - - attributes ._data and ._mask. - -\begin_inset LatexCommand index -name "masked arrays|)" - -\end_inset - - -\end_layout - -\begin_layout Section -Standard container class -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "user\\_array" - -\end_inset - - -\begin_inset LatexCommand index -name "container class" - -\end_inset - -For backward compatibility and as a standard -\begin_inset Quotes eld -\end_inset - -container -\begin_inset Quotes erd -\end_inset - - class, the UserArray from Numeric has been brought over to NumPy and named - -\series bold -numpy.lib.user_array.container -\series default - The container class is a Python class whose self.array attribute is an ndarray. - Multiple inheritance is probably easier with numpy.lib.user_array.container - than with the ndarray itself and so it is included by default. - It is not documented here beyond mentioning its existence because you are - encouraged to use the ndarray class directly if you can. - -\end_layout - -\begin_layout Section -Array Iterators -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "array iterator" - -\end_inset - -Iterators are a powerful concept for array processing. - Essentially, iterators implement a generalized for-loop. - If myiter is an iterator object, then the Python code -\end_layout - -\begin_layout LyX-Code -for val in myiter: -\end_layout - -\begin_layout LyX-Code - ... -\end_layout - -\begin_layout LyX-Code - some code involving val -\end_layout - -\begin_layout LyX-Code - ... -\end_layout - -\begin_layout Standard -calls val=myiter.next() repeatedly until StopIteration is raised by the iterator. - There are several ways to iterate over an array that may be useful: default - iteration, flat iteration, and -\begin_inset Formula $N$ -\end_inset - --dimensional enumeration. -\end_layout - -\begin_layout Subsection -Default iteration -\end_layout - -\begin_layout Standard -The default iterator of an ndarray object is the default Python iterator - of a sequence type. - Thus, when the array object itself is used as an iterator. - The default behavior is equivalent to: -\end_layout - -\begin_layout LyX-Code -for i in arr.shape[0]: -\end_layout - -\begin_layout LyX-Code - val = arr[i] -\end_layout - -\begin_layout Standard -This default iterator selects a sub-array of dimension -\begin_inset Formula $N-1$ -\end_inset - - from the array. - This can be a useful construct for defining recursive algorithms. - To loop over the entire array requires -\begin_inset Formula $N$ -\end_inset - - for-loops. - -\end_layout - -\begin_layout MyCode ->>> a = arange(24).reshape(3,2,4)+10 -\newline ->>> for val in a: -\newline -... - print 'item:', val -\newline -item: [[10 11 12 13] -\newline - [14 15 16 17]] -\newline -item: [[18 19 - 20 21] -\newline - [22 23 24 25]] -\newline -item: [[26 27 28 29] -\newline - [30 31 32 33]] -\end_layout - -\begin_layout Subsection -Flat iteration -\end_layout - -\begin_layout Standard -As mentioned previously, the flat attribute of ndarray objects returns an - iterator that will cycle over the entire array in C-style contiguous order. - -\end_layout - -\begin_layout MyCode ->>> for i, val in enumerate(a.flat): -\newline -... - if i%5 == 0: print i, val -\newline -0 10 -\newline -5 15 -\newline -10 20 -\newline -15 25 -\newline -20 30 -\end_layout - -\begin_layout Standard -Here, I've used the built-in enumerate iterator to return the iterator index - as well as the value. -\end_layout - -\begin_layout Subsection -N-dimensional enumeration -\end_layout - -\begin_layout Standard -Sometimes it may be useful to get the N-dimensional index while iterating. - The ndenumerate iterator can achieve this. -\end_layout - -\begin_layout MyCode ->>> for i, val in ndenumerate(a): -\newline -... - if sum(i)%5 == 0: print i, val -\newline -(0, 0, 0) 10 -\newline -(1, 1, 3) 25 -\newline -(2, 0, 3) 29 -\newline -(2, - 1, 2) 32 -\end_layout - -\begin_layout Subsection -Iterator for broadcasting -\end_layout - -\begin_layout Standard -The general concept of broadcasting is also available from Python using - the -\series bold -broadcast -\series default - iterator. - This object takes -\begin_inset Formula $N$ -\end_inset - - objects as inputs and returns an iterator that returns tuples providing - each of the input sequence elements in the broadcasted result. -\end_layout - -\begin_layout MyCode ->>> for val in broadcast([[1,0],[2,3]],[0,1]): -\newline -... - print val -\newline -(1, 0) -\newline -(0, 1) -\newline -(2, 0) -\newline -(3, 1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - The methods and attributes of the broadcast object are: -\end_layout - -\begin_deeper -\begin_layout Description -nd the number of dimensions in the broadcasted result. -\end_layout - -\begin_layout Description -shape the shape of the broadcasted result. -\end_layout - -\begin_layout Description -size the total size of the broadcasted result. -\end_layout - -\begin_layout Description -index the current (flat) index into the broadcasted array -\end_layout - -\begin_layout Description -iters a tuple of (broadcasted) NumPy.flatiter objects, one for each array. -\end_layout - -\begin_layout Description -reset () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Reset the multiter object to the beginning. -\end_layout - -\begin_layout Description -next () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Get the next tuple of objects from the (broadcasted) arrays -\end_layout - -\end_deeper -\begin_layout Chapter -Universal Functions -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand label -name "par:The-Ufunc-Object" - -\end_inset - - -\end_layout - -\begin_layout Quotation -Computers make it easier to do a lot of things, but most of the things they - make it easier to do don't need to be done. -\end_layout - -\begin_layout Right Address ---- -\emph on -Andy Rooney -\end_layout - -\begin_layout Quotation -People think computers will keep them from making mistakes. - They're wrong. - With computers you make mistakes faster. -\end_layout - -\begin_layout Right Address ---- -\emph on -Adam Osborne -\end_layout - -\begin_layout Section -Description -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "ufunc|(" - -\end_inset - -Universal functions are wrappers that provide a common interface to mathematical - functions that operate on scalars, and can be made to operate on arrays - in an element-by-element fashion. - All -\family typewriter -u -\family default -niversal -\family typewriter -func -\family default -tion -\family typewriter -s -\family default - ( -\family typewriter -ufuncs -\family default -) wrap some core function that takes -\begin_inset Formula $n_{i}$ -\end_inset - - (scalar) inputs and produces -\begin_inset Formula $n_{o}$ -\end_inset - - (scalar) outputs. - Typically, this core function is implemented in compiled code but a Python - function can also be wrapped into a universal function using the basic - method -\family typewriter -frompyfunc -\family default - in the umath module. - -\end_layout - -\begin_layout Description -frompyfunc (func, nin, nout) -\begin_inset LatexCommand index -name "frompyfunc" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - This function returns a new universal function wrapping a Python function - func with nin inputs and nout outputs. - The resulting universal function works using Object arrays for both input - and output. - The vectorize class makes use of frompyfunc internally. - You can view the source code using numpy.source(numpy.vectorize). -\end_layout - -\begin_layout Subsection -Broadcasting -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "broadcasting" - -\end_inset - -Each universal function takes array inputs and produces array outputs by - performing the core function element-wise on the inputs. - The standard broadcasting rules are applied so that inputs without exactly - the same shapes can still be usefully operated on. - Broadcasting can be understood by four rules: -\end_layout - -\begin_layout Enumerate -All input arrays with ndim smaller than the input array of largest ndim - have 1's pre-pended to their shapes. -\end_layout - -\begin_layout Enumerate -The size in each dimension of the output shape is the maximum of all the - input shapes in that dimension. -\end_layout - -\begin_layout Enumerate -An input can be used in the calculation if it's shape in a particular dimension - either matches the output shape or has value exactly 1. -\end_layout - -\begin_layout Enumerate -If an input has a dimension size of 1 in its shape, the first data entry - in that dimension will be used for all calculations along that dimension. - In other words, the stepping machinery of the ufunc will simply not step - along that dimension when otherwise needed (the stride will be 0 for that - dimension). - -\end_layout - -\begin_layout Standard -While perhaps a bit difficult to explain, broadcasting can be quite useful - and becomes second nature rather quickly. - Broadcasting is used throughout NumPy to decide how to handle non equally-shape -d arrays. - -\end_layout - -\begin_layout Subsection -Output type determination -\end_layout - -\begin_layout Standard -The output of the ufunc (and its methods) does not have to be an ndarray. - All output arrays will be passed to the __array_wrap__ method of any input - (besides ndarrays, and scalars) that defines it -\series bold -and -\series default - has the highest __array_priority__ of any other input to the universal - function. - The default __array_priority__ of the ndarray is 0.0, and the default __array_pr -iority__ of a subtype is 1.0. - Matrices have __array_priority__ equal to 10.0. - -\end_layout - -\begin_layout Standard -The ufuncs can also all take output arguments. - The output will be cast if necessary to the provided output array. - If a class with an __array__ method is used for the output, results will - be written to the object returned by __array__. - Then, if the class also has an __array_wrap__ method, the returned -\family typewriter -ndarray -\family default - result will be passed to that method just before passing control back to - the caller. - -\end_layout - -\begin_layout Subsection -Use of internal buffers -\end_layout - -\begin_layout Standard -Internally, buffers are used for misaligned data, swapped data, and data - that has to be converted from one data type to another. - The size of the internal buffers is settable on a per-thread basis. - There can be up to -\begin_inset Formula $2\left(n_{i}+n_{o}\right)$ -\end_inset - - buffers of the specified size created to handle the data from all the inputs - and outputs of a ufunc. - The default size of the buffer is 10,000 elements. - Whenever buffer-based calculation would be needed, but all input arrays - are smaller than the buffer size, those misbehaved or incorrect typed arrays - will be copied before the calculation proceeds. - Adjusting the size of the buffer may therefore alter the speed at which - ufunc calculations of various sorts are completed. - A simple interface for setting this variable is accessible using the function - -\end_layout - -\begin_layout Description -setbufsize (size) -\begin_inset LatexCommand index -name "setbufsize" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Set the buffer size to the given number of elements in the current thread. - Return the old buffer size (so that it can be reset later if desired). - -\end_layout - -\begin_layout Subsection -Error handling -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "error handling" - -\end_inset - -Universal functions can trip special floating point status registers in - your hardware (such as divide-by-zero). - If available on your platform, these registers will be regularly checked - during calculation. - The user can determine what should be done if errors are encountered. - Error handling is controlled on a per-thread basis. - Four errors can be individually configured: divide-by-zero, overflow, underflow -, and invalid. - The errors can each be set to ignore, warn, raise, or call. - The easiest way to configure the error mask is using the function -\end_layout - -\begin_layout Description -seterr (all=None, divide=None, over=None, under=None, invalid=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset LatexCommand index -name "seterr" - -\end_inset - -This will set the current thread so that errors can be handled if desired. - If one of the errors is set to 'call', then a function must be provided - using the seterrcall() routine. - If any of the arguments are None, then that error mask will be unchanged. - The return value of this function is a dictionary with the old error conditions. - Thus, you can restore the old condition after you are finished with your - function by calling seterr(**old). - If all is set, then all errors will be set to the specified value. - -\end_layout - -\begin_layout Description -seterrcall (callable) -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset LatexCommand index -name "seterrcall" - -\end_inset - -This sets the function to call when an error is triggered for an error condition - configured with the -\begin_inset Quotes eld -\end_inset - -call -\begin_inset Quotes erd -\end_inset - - handler. - This function should take two arguments: a string showing the type of error - that triggered the call, and an integer showing the state of the floating - point status registers. - Any return value of the call function will be ignored, but errors can be - raised by the function. - Only one error function handler can be specified for all the errors. - The status argument shows which errors were raised. - The return value of this routine is the old callable. - The argument passed in to this function must be any callable object with - the right signature or None. - -\end_layout - -\begin_layout Note -FPE_DIVIDEBYZERO, FPE_OVERFLOW, FPE_UNDERFLOW, and FPE_INVALID, are all - defined constants in NumPy. - The status flag returned for a 'call' error handling type shows which errors - were raised by adding these constants together. -\end_layout - -\begin_layout Subsection -Optional keyword arguments -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "ufunc!keyword arguments" - -\end_inset - -All ufuncs take optional keyword arguments. - These represent rather advanced usage and will likely not be used by most - users. - -\end_layout - -\begin_layout Description -sig= either a data-type, a tuple of data-types, or a special signature string - indicating the input and output types of a ufunc. - This argument allows you to specify a specific signature for a the 1-d - loop to use in the underlying calculation. - If the loop specified does not exist for the ufunc, then a TypeError is - raised. - Normally a suitable loop is found automatically by comparing the input - types with what is available and searching for a loop with data-types to - which all inputs can be cast safely. - This key-word argument lets you by-pass that search and choose a loop you - want. - A list of available signatures is available in the -\series bold -types -\series default - attribute of the ufunc object. - -\end_layout - -\begin_layout Description -extobj= a list of length 1, 2, or 3 specifying the ufunc buffer-size, the - error mode integer, and the error call-back function. - Normally, these values are looked-up in a thread-specific dictionary. - Passing them here bypasses that look-up and uses the low-level specification - provided for the error-mode. - This may be useful as an optimization for calculations requiring lots of - ufuncs on small arrays in a loop. - -\end_layout - -\begin_layout Section -Attributes -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "ufunc!attributes" - -\end_inset - -There are some informational attributes that universal functions possess. - None of the attributes can be set. - -\end_layout - -\begin_layout Description -__doc__ -\end_layout - -\begin_layout Description -\InsetSpace ~ - A docstring for each ufunc. - The first part of the docstring is dynamically generated from the number - of outputs, the name, and the number of inputs. - The second part of the doc string is provided at creation time and stored - with the ufunc. - -\end_layout - -\begin_layout Description -__name__ -\end_layout - -\begin_layout Description -\InsetSpace ~ - The name of this ufunc. -\end_layout - -\begin_layout Description -nin -\end_layout - -\begin_layout Description -\InsetSpace ~ - The number of inputs -\end_layout - -\begin_layout Description -nout -\end_layout - -\begin_layout Description -\InsetSpace ~ - The number of outputs -\end_layout - -\begin_layout Description -nargs -\end_layout - -\begin_layout Description -\InsetSpace ~ - The total number of inputs + outputs -\end_layout - -\begin_layout Description -ntypes -\end_layout - -\begin_layout Description -\InsetSpace ~ - The total number of different types for which this ufunc is defined. -\end_layout - -\begin_layout Description -types -\end_layout - -\begin_layout Description -\InsetSpace ~ - A list of length ntypes containing strings showing the types for which - this ufunc is defined. - Other types may still be used as inputs (and as output arrays), they will - just need casting. - For inputs, standard casting rules will be used to determine which of the - supplied internal functions that will be used (and therefore the default - type of the output). - Results will always be force-cast to any array provided to hold the output. - -\end_layout - -\begin_layout Description -identity -\end_layout - -\begin_layout Description -\InsetSpace ~ - A 1, 0, or None to show the identity for this universal function. - This identity is used for reduction on zero-sized arrays (arrays with a - shape that includes a 0). -\end_layout - -\begin_layout Standard -\begin_inset Float table -wide false -sideways false -status open - -\begin_layout Standard -\begin_inset Caption - -\begin_layout Standard -Universal function (ufunc) attributes. -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\align center -\begin_inset Tabular -<lyxtabular version="3" rows="9" columns="2"> -<features> -<column alignment="center" valignment="top" leftline="true" width="0"> -<column alignment="center" valignment="top" leftline="true" rightline="true" width="0"> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Name -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Description -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -__doc__ -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Dynamic docstring. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -__name__ -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Name of ufunc -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -nin -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Number of input arguments -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -nout -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Number of output arguments -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -nargs -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Total number of arguments -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -ntypes -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Number of defined inner loops. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -types -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -List showing types for which inner loop is defined. -\end_layout - -\end_inset -</cell> -</row> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -identity -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Identity for this ufunc. -\end_layout - -\end_inset -</cell> -</row> -</lyxtabular> - -\end_inset - - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Section -Casting Rules -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "ufunc!casting rules" - -\end_inset - -At the core of every ufunc is a one-dimensional strided loop that implements - the actual function for a specific type combination. - When a ufunc is created, it is given a static list of inner loops and a - corresponding list of type signatures over which the ufunc operates. - The ufunc machinery uses this list to determine which inner loop to use - for a particular case. - You can inspect the -\family typewriter -.types -\family default - attribute for a particular ufunc to see which type combinations have a - defined inner loop and which output type they produce (the character codes - are used in that output for brevity). - -\end_layout - -\begin_layout Standard -Casting must be done on one or more of the inputs whenever the ufunc does - not have a core loop implementation for the input types provided. - If an implementation for the input types cannot be found, then the algorithm - searches for an implementation with a type signature to which all of the - inputs can be cast -\begin_inset Quotes eld -\end_inset - -safely. -\begin_inset Quotes erd -\end_inset - - The first one it finds in its internal list of loops is selected and performed - with types cast. - Recall that internal copies during ufuncs (even for casting) are limited - to the size of an internal buffer which is user settable. - -\end_layout - -\begin_layout Note -Universal functions in NumPy are flexible enough to have mixed type signatures. - Thus, for example, a universal function could be defined that works with - floating point and integer values. - See ldexp for an example. -\end_layout - -\begin_layout Standard -By the above description, the casting rules are essentially implemented - by the question of when a data type can be cast -\begin_inset Quotes eld -\end_inset - -safely -\begin_inset Quotes erd -\end_inset - - to another data type. - The answer to this question can be determined in Python with a function - call: can_cast (fromtype, totype). - Figure shows the results of this call for my 32-bit system on the 21 internally - supported types. - You can generate this table for your system with code shown in that Figure. -\end_layout - -\begin_layout Standard -\begin_inset Float figure -wide false -sideways false -status open - -\begin_layout MyCode ->>> def print_table(ntypes): -\newline -... - print 'X', -\newline -... - for char in ntypes: print char, -\newline -... - print -\newline -... - for row in ntypes: -\newline -... - print row, -\newline -... - for col in ntypes: -\newline -... - print int(can_cast(row, col)), -\newline -... - print -\newline ->>> print_table(typecodes['All']) -\newline -X ? b h i l q p B H I L Q - P f d g F D G S U V O -\newline -? 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 -\newline -b 0 - 1 1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 -\newline -h 0 0 1 1 1 1 1 0 0 0 0 0 0 - 1 1 1 1 1 1 1 1 1 1 -\newline -i 0 0 0 1 1 1 1 0 0 0 0 0 0 0 1 1 0 1 1 1 1 1 1 -\newline -l 0 0 - 0 1 1 1 1 0 0 0 0 0 0 0 1 1 0 1 1 1 1 1 1 -\newline -q 0 0 0 0 0 1 0 0 0 0 0 0 0 0 - 1 1 0 1 1 1 1 1 1 -\newline -p 0 0 0 1 1 1 1 0 0 0 0 0 0 0 1 1 0 1 1 1 1 1 1 -\newline -B 0 0 1 - 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 -\newline -H 0 0 0 1 1 1 1 0 1 1 1 1 1 1 1 - 1 1 1 1 1 1 1 1 -\newline -I 0 0 0 0 0 1 0 0 0 1 1 1 1 0 1 1 0 1 1 1 1 1 1 -\newline -L 0 0 0 0 - 0 1 0 0 0 1 1 1 1 0 1 1 0 1 1 1 1 1 1 -\newline -Q 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 1 - 0 1 1 1 1 1 1 -\newline -P 0 0 0 0 0 1 0 0 0 1 1 1 1 0 1 1 0 1 1 1 1 1 1 -\newline -f 0 0 0 0 0 - 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 -\newline -d 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 - 1 1 1 1 1 1 -\newline -g 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 1 1 1 1 -\newline -F 0 0 0 0 0 0 - 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 -\newline -D 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 - 1 1 1 1 1 -\newline -G 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 -\newline -S 0 0 0 0 0 0 0 - 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 -\newline -U 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 - 0 1 1 1 -\newline -V 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 -\newline -O 0 0 0 0 0 0 0 0 - 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 -\end_layout - -\begin_layout Standard -\begin_inset Caption - -\begin_layout Standard -Code segment showing the can cast safely table for a 32-bit system. -\end_layout - -\end_inset - - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -You should note that, while included in the table for completeness, the - 'S', 'U', and 'V' types cannot be operated on by ufuncs. - Also, note that on a 64-bit system the integer types may have different - sizes resulting in a slightly altered table. - -\end_layout - -\begin_layout Standard -Mixed scalar-array operations use a different set of casting rules that - ensure that a scalar cannot upcast an array unless the scalar is of a fundament -ally different kind of data ( -\emph on -i.e. - -\emph default - under a different hierachy in the data type hierarchy) then the array. - This rule enables you to use scalar constants in your code (which as Python - types are interpreted accordingly in ufuncs) without worrying about whether - the precision of the scalar constant will cause upcasting on your large - (small precision) array. - -\end_layout - -\begin_layout Section -Methods -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "ufunc!methods|(" - -\end_inset - -All ufuncs have 4 methods. - However, these methods only make sense on ufuncs that take two input arguments - and return one output argument. - Attempting to call these methods on other ufuncs will cause a -\family typewriter -ValueError -\family default -. - The reduce-like methods all take an axis keyword and a dtype keyword, and - the arrays must all have dimension >= 1. - The -\emph on -axis -\emph default - keyword specifies which axis of the array the reduction will take place - over and may be negative, but must be an integer. - The -\emph on -dtype -\emph default - keyword allows you to manage a very common problem that arises when naively - using <op>.reduce. - Sometimes you may have an array of a certain data type and wish to add - up all of its elements, but the result does not fit into the data type - of the array. - This commonly happens if you have an array of single-byte integers. - The dtype keyword allows you to alter the data type that the reduction - takes place over (and therefore the type of the output). - Thus, you can ensure that the output is a data type with large-enough precision - to handle your output. - The responsibility of altering the reduce type is mostly up to you. - There is one exception: if no dtype is given for a reduction on the -\begin_inset Quotes eld -\end_inset - -add -\begin_inset Quotes erd -\end_inset - - or -\begin_inset Quotes eld -\end_inset - -multiply -\begin_inset Quotes erd -\end_inset - - operations, then if the input type is an integer (or boolean) data-type - and smaller than the size of the int_ data type, it will be internally - upcast to the int_ (or uint) data type. - -\end_layout - -\begin_layout Warning -A reduce-like operation on an array with a data type that has range -\begin_inset Quotes eld -\end_inset - -too small -\begin_inset Quotes erd -\end_inset - - to handle the result will silently wrap. - You should use dtype to increase the data type over which reduction takes - place. -\end_layout - -\begin_layout Subsection -Reduce -\end_layout - -\begin_layout Description -<op>.reduce (array=, axis=0, dtype=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset LatexCommand index -name "ufunc!methods!reduce" - -\end_inset - -For each one-dimensional sequence along the -\emph on -axis -\emph default - dimension of the array, return a single number resulting from recursively - applying the operation to succesive elements along that dimension. - If the input array has -\begin_inset Formula $N$ -\end_inset - - dimensions, then the returned array has -\begin_inset Formula $N-1$ -\end_inset - - dimensions. - This produces the equivalent of the following Python code : -\end_layout - -\begin_layout LyX-Code ->>> indx = [index_exp[:]]*array.ndim -\newline ->>> indx[axis] = 0; N=array.shape[axis] -\newline ->>> - result = array[indx].astype(dtype) -\newline ->>> for i in range(1,N): -\newline -... - indx[axis] = i -\newline -... - <op>(result, array[indx], result) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Studying the above code can also help you gain an appreciation for how - to do generic indexing in Python using -\family typewriter -index_exp -\family default -. - For example, if <op> is add, then <op>.reduce produces a summation along - the given axis. - If <op> is prod, then a repeated multiply is performed. -\end_layout - -\begin_layout Subsection -Accumulate -\end_layout - -\begin_layout Description -<op>.accumulate (array=, axis=0, dtype=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset LatexCommand index -name "ufunc!methods!accumulate" - -\end_inset - -This method is similar to reduce, except it returns an array of the same - shape as the input, and keeps intermediate calculations. - The operation is still performed along the access. - This method underlies the operations of the cumsum and cumprod methods - of arrays. - The following Python code implements an equivalent of the accumulate method. -\end_layout - -\begin_layout LyX-Code ->>> i1 = [index_exp[:]]*array.ndim -\newline ->>> i2 = [index_exp[:]]*array.ndim -\newline ->>> i1[axis] - = 0; N=array.shape[axis] -\newline ->>> result = array.astype(dtype) -\newline ->>> for i in range(1,N): -\newline -... - i1[axis] = i -\newline -... - i2[axis] = i-1 -\newline -... - <op>(result[i1], array[i1], result[i2]) -\end_layout - -\begin_layout Subsection -Reduceat -\end_layout - -\begin_layout Description -<op>.reduceat (array=, indices=, axis=0, dtype=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset LatexCommand index -name "ufunc!methods!reduceat" - -\end_inset - -This method is a generalization of both reduce and accumulate. - It offers the ability to reduce along an axis but only between certain - indices. - The indices input must be a one dimensional (index) sequence. - Then, if -\begin_inset Formula $I_{k}$ -\end_inset - - is the -\begin_inset Formula $k^{\textrm{th}}$ -\end_inset - - element of indices, the reduceat method computes <op>.reduce(array[ -\begin_inset Formula $I_{k}$ -\end_inset - -: -\begin_inset Formula $I_{k+1}$ -\end_inset - -]). - This formula assumes -\begin_inset Formula $I_{k+1}>I_{k}$ -\end_inset - -, and also that -\begin_inset Formula $I_{k+1}$ -\end_inset - - is the length of the input array when -\begin_inset Formula $I_{k}$ -\end_inset - - is the last element. - There is no requirement that the indices be monotonic. - If -\begin_inset Formula $I_{k+1}\leq I_{k},$ -\end_inset - - then reduceat simply returns array[ -\begin_inset Formula $I_{k}$ -\end_inset - -] for that particular element of indices. - In these formulas, we have assumed that array is one dimensional (or axis - is 0). - If the array is -\begin_inset Formula $N$ -\end_inset - --dimensional and axis>0, then the index expression needs axis ':' (full - slice objects) inserted (i.e. - array[ -\begin_inset Formula $\underbrace{:,\ldots,:}_{\textrm{axis}},I_{k}:I_{k+1}$ -\end_inset - -]). - The effect is to slice along the axis dimension. - Equivalent Python code is -\end_layout - -\begin_layout LyX-Code ->>> i1 = [index_exp[:]]*array.ndim -\newline ->>> i2 = [index_exp[:]]*array.ndim -\newline ->>> outshape - = list(array.shape) -\newline ->>> N = array.shape[axis] -\newline ->>> outshape[axis] = len(indices) -\newline ->>> - result = zeros(outshape, dtype or array.dtype) -\newline ->>> for k,Ik in enumerate(indices -): -\newline -... - i1[axis] = k -\newline -... - try: -\newline -... - Ikp1 = indices[k+1] -\newline -... - except IndexError: -\newline -... - Ikp1 = N -\newline -... - if (Ikp1 > Ik): -\end_layout - -\begin_layout LyX-Code -... - i2[axis] = index_exp[Ik:Ikp1] -\newline -... - result[i1] = <op>.reduce(array[i2],axis=axis,dtype=dtype) -\newline -... - else: -\newline -... - result[i1] = array[Ik].astype(dtype) -\end_layout - -\begin_layout Description -\InsetSpace ~ - The returned array has as many dimensions as the input array, and is the - same shape except for the -\emph on -axis -\emph default - dimension which has shape equal to the length of indices (the number of - reduce operations that were performed). - If you ever have a need to compute multiple reductions over portions of - an array, then (if you can get your mind around what it is doing) reduceat - may be just what you were looking for. - -\end_layout - -\begin_deeper -\begin_layout Description -Example: Suppose a is a two-dimensional array of shape -\begin_inset Formula $10\times20$ -\end_inset - -. - Then, res=add.reduce (a, [0,3,1]) returns a -\begin_inset Formula $3\times20$ -\end_inset - - array with res[0,:] = add.reduce(a[:,0:3]), res[1,:] = a[:,3], and res[2,:] - = add.reduce(a[:,1:]). - -\end_layout - -\end_deeper -\begin_layout Subsection -Outer -\end_layout - -\begin_layout Description -<op>.outer (a, b) -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset LatexCommand index -name "ufunc!methods!outer" - -\end_inset - -This method computes an outer operation on <op>. - It computes <op>(a2, b2) where a2 is 'a' with b.ndim 1's post-pended to - it's shape and b2 is 'b' with a.ndim 1's pre-pended to its shape (broadcasting - takes care of this automatically in the code below). - The return shape has a.ndim + b.ndim dimensions. - Equivalent Python code is -\end_layout - -\begin_layout LyX-Code ->>> a.shape += (1,)*b.ndim -\newline ->>> <op>(a,b) -\newline ->>> a = a.squeeze() -\end_layout - -\begin_layout Standard -\InsetSpace ~ - Among many other uses, arithmetic tables can be conveniently built using - outer: -\begin_inset LatexCommand index -name "ufunc!methods|)" - -\end_inset - - -\end_layout - -\begin_layout MyCode ->>> multiply.outer([1,7,9,12],arange(5,12)) -\newline -array([[ 5, 6, 7, 8, - 9, 10, 11], -\newline - [ 35, 42, 49, 56, 63, 70, 77], -\newline - [ 45, 54, - 63, 72, 81, 90, 99], -\newline - [ 60, 72, 84, 96, 108, 120, 132]]) -\end_layout - -\begin_layout Section -Available ufuncs -\end_layout - -\begin_layout Standard -There are currently more than 60 universal functions defined on one or more - types, covering a wide variety of operations. - Some of these ufuncs are called automatically on arrays when the relevant - infix notation is used (i.e. - add(a,b) is called internally when a + b is written and a or b is an ndarray). - Nonetheless, you may still want to use the ufunc call in order to use the - optional output argument(s) to place the output(s) in an object (or in - objects) of your choice. - -\end_layout - -\begin_layout Standard -Recall that each ufunc operates element-by-element. - Therefore, each ufunc will be described as if acting on a set of scalar - inputs to return a set of scalar outputs. -\end_layout - -\begin_layout Note -The ufunc still returns its output(s) even if you use the optional output - argument(s). - -\end_layout - -\begin_layout Subsection -Math operations -\end_layout - -\begin_layout Description -add ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "add" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset Formula $y=x_{1}+x_{2}$ -\end_inset - -. - Called to implement -\family typewriter -x1+x2 -\family default - for arrays -\end_layout - -\begin_layout Description -subtract ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "subtract" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset Formula $y=x_{1}-x_{2}$ -\end_inset - -. - Called to implement -\family typewriter -x1-x2 -\family default - for arrays -\end_layout - -\begin_layout Description -multiply ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "multiply" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset Formula $y=x_{1}\cdot x_{2}$ -\end_inset - -. - Called to implement -\family typewriter -x1*x2 -\family default - for arrays. -\end_layout - -\begin_layout Description -divide ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "divide" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset Formula $y=x_{1}/x_{2}$ -\end_inset - - Integer division results in truncation. - Floating-point does not. - Called to implement -\family typewriter -x1/x2 -\family default - for arrays (when __future__.division is not active). - -\end_layout - -\begin_layout Description -true_divide ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "true\\_divide" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - This version of division always returns an inexact number so that integer - division returns floating point. - Called with __future__.division is active to implement -\family typewriter -x1/x2 -\family default - for arrays. -\end_layout - -\begin_layout Description -floor_divide ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "floor\\_divide" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - This version of division always results in truncation of an fractional - part remaining. - Called to implement -\family typewriter -x1//x2 -\family default - for arrays. -\end_layout - -\begin_layout Description -negative ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "negative" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset Formula $y=-x$ -\end_inset - -. - Called to implement -\family typewriter --x -\family default - for arrays. -\end_layout - -\begin_layout Description -power ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "power" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset Formula $y=x_{1}^{x_{2}}$ -\end_inset - -. - There is no three-term power ufunc defined. - This two-term power function is called to implement -\family typewriter -pow(x1,x2,<any>) -\family default - or -\family typewriter -x1**x2 -\family default - for arrays. - Note that the third term in -\family typewriter -pow -\family default - is ignored for array arguments. -\end_layout - -\begin_layout Description -remainder ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "remainder" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns -\begin_inset Formula $x-y$ -\end_inset - -*floor( -\begin_inset Formula $x/y$ -\end_inset - -). - Result has the sign of -\begin_inset Formula $y$ -\end_inset - -. - Called to implement -\family typewriter -x1%x2 -\family default -. -\end_layout - -\begin_layout Description -mod ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Same as remainder ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]). - -\end_layout - -\begin_layout Description -fmod ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset Formula $x_{1}=kx_{2}+y$ -\end_inset - - where -\begin_inset Formula $k$ -\end_inset - - is the largest integer satisfying this equation. - Computes C-like -\begin_inset Formula $x_{1}\%x_{2}$ -\end_inset - - element-wise. - This was the behavior of -\family typewriter -x1%x2 -\family default - in old Numeric. -\end_layout - -\begin_layout Description -absolute ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "absolute" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset Formula $y=\left|x\right|.$ -\end_inset - - Called to implement -\family typewriter -abs(x) -\family default - for arrays. - -\end_layout - -\begin_layout Description -rint (x, [, y]) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Round -\begin_inset Formula $x$ -\end_inset - - to the nearest integer. - Rounds half-way cases to the nearest even integer. -\end_layout - -\begin_layout Description -sign ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Sets -\begin_inset Formula $y$ -\end_inset - - according to -\begin_inset Formula \[ -\textrm{sign}\left(x\right)=\left\{ \begin{array}{cc} -1 & x:>0,\\ -0 & x=0,\\ --1 & x<0.\end{array}\right.\] - -\end_inset - - -\end_layout - -\begin_layout Description -conj ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "conj" - -\end_inset - - -\end_layout - -\begin_layout Description -conjugate ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "conjugate" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset Formula $y=\overline{x}$ -\end_inset - -; in other words, the complex conjugate of -\begin_inset Formula $x$ -\end_inset - -. -\end_layout - -\begin_layout Description -exp ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "exp" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset Formula $y=e^{x}.$ -\end_inset - - -\end_layout - -\begin_layout Description -log ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "log" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset Formula $y=\log\left(x\right)$ -\end_inset - -. - In other words, -\begin_inset Formula $y$ -\end_inset - - is the number so that -\begin_inset Formula $e^{y}=x$ -\end_inset - -. - -\end_layout - -\begin_layout Description -expm1 ( -\begin_inset Formula $x$ -\end_inset - -, [, -\begin_inset Formula $y$ -\end_inset - -]) -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset Formula $y=e^{x}-1.$ -\end_inset - - Calculated so that it is accurate for small -\begin_inset Formula $\left|x\right|.$ -\end_inset - - -\end_layout - -\begin_layout Description -log1p ( -\begin_inset Formula $x$ -\end_inset - -, [, -\begin_inset Formula $y$ -\end_inset - -]) -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset Formula $y=\log\left(1+x\right)$ -\end_inset - - but accurate for small -\begin_inset Formula $\left|x\right|.$ -\end_inset - - Returns the number -\begin_inset Formula $y$ -\end_inset - - such that -\begin_inset Formula $e^{y}-1=x$ -\end_inset - - -\end_layout - -\begin_layout Description -log10 ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "log10" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset Formula $y=\log10\left(x\right)$ -\end_inset - -. - In other words, -\begin_inset Formula $y$ -\end_inset - - is the number so that -\begin_inset Formula $10^{y}=x.$ -\end_inset - - -\end_layout - -\begin_layout Description -sqrt ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "sqrt" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset Formula $y=\sqrt{x}.$ -\end_inset - - -\end_layout - -\begin_layout Description -square ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset Formula $y=x*x$ -\end_inset - - -\end_layout - -\begin_layout Description -reciprocal ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset Formula $y=1/x$ -\end_inset - - -\end_layout - -\begin_layout Description -ones_like ( -\begin_inset Formula $x$ -\end_inset - -, [, -\begin_inset Formula $y$ -\end_inset - -]) -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset Formula $y=1$ -\end_inset - - If an output argument is not given the returned data-type is the same as - the input data type. -\end_layout - -\begin_layout Tip -The optional output arguments can be used to help you save memory for large - calculations. - If your arrays are large, complicated expressions can take longer than - absolutely necessary due to the creation and (later) destruction of temporary - calculation spaces. - For example, the expression 'G=a*b+c' is equivalent to t1=A*B; G=T1+C; - del t1; It will be more quickly executed as G=A*B; add(G,C,G) which is - the same as G=A*B; G+=C. -\end_layout - -\begin_layout Subsection -Trigonometric functions -\end_layout - -\begin_layout Standard -All trigonometric functions use radians when an angle is called for. - The ratio of degrees to radians is -\begin_inset Formula $180^{\circ}/\pi.$ -\end_inset - - -\end_layout - -\begin_layout Description -sin ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "sin" - -\end_inset - - -\end_layout - -\begin_layout Description -cos ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "cos" - -\end_inset - - -\end_layout - -\begin_layout Description -tan ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "tan" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The standard trignometric functions. - -\begin_inset Formula $y=\sin\left(x\right),$ -\end_inset - - -\begin_inset Formula $y=\cos\left(x\right),$ -\end_inset - - and -\begin_inset Formula $y=\tan\left(x\right).$ -\end_inset - - -\end_layout - -\begin_layout Description -arcsin ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "arcsin" - -\end_inset - - -\end_layout - -\begin_layout Description -arccos ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "arccos" - -\end_inset - - -\end_layout - -\begin_layout Description -arctan ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "arctan" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The inverse trigonometric functions: -\begin_inset Formula $y=\sin^{-1}\left(x\right),$ -\end_inset - - -\begin_inset Formula $y=\cos^{-1}\left(x\right)$ -\end_inset - -, -\begin_inset Formula $y=\tan^{-1}\left(x\right).$ -\end_inset - - These return the value of -\begin_inset Formula $y$ -\end_inset - - (in radians) such that -\begin_inset Formula $\sin\left(y\right)=x$ -\end_inset - - with -\begin_inset Formula $y\in\left[-\frac{\pi}{2},\frac{\pi}{2}\right]$ -\end_inset - -; -\begin_inset Formula $\cos\left(y\right)=x$ -\end_inset - - with -\begin_inset Formula $y\in\left[0,\pi\right]$ -\end_inset - -; and -\begin_inset Formula $\tan\left(y\right)=x$ -\end_inset - - with -\begin_inset Formula $y\in\left[-\frac{\pi}{2},\frac{\pi}{2}\right]$ -\end_inset - -, respectively. - -\end_layout - -\begin_layout Description -arctan2 ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "arctan2" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns -\begin_inset Formula $\tan^{-1}\left(\frac{x_{1}}{x_{2}}\right)$ -\end_inset - - but takes into account the sign on -\begin_inset Formula $x_{1}$ -\end_inset - - and -\begin_inset Formula $x_{2}$ -\end_inset - - to place the angle in the correct quadrant. - The angle -\begin_inset Formula $y$ -\end_inset - - is returned in the full range -\begin_inset Formula $-\pi<y\leq\pi$ -\end_inset - -. - The angle is chosen so that -\begin_inset Formula $\sin\left(y\right)=\frac{x_{1}}{\sqrt{x_{1}^{2}+x_{2}^{2}}},$ -\end_inset - - and -\begin_inset Formula $\cos\left(y\right)=\frac{x_{2}}{\sqrt{x_{1}^{2}+x_{2}^{2}}}.$ -\end_inset - - Particular values are showin in the following table: -\end_layout - -\begin_layout Standard -\align center -\begin_inset Tabular -<lyxtabular version="3" rows="5" columns="3"> -<features> -<column alignment="center" valignment="top" leftline="true" width="0"> -<column alignment="center" valignment="top" leftline="true" width="0"> -<column alignment="center" valignment="top" leftline="true" rightline="true" width="0"> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -\begin_inset Formula $x_{1}$ -\end_inset - - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -\begin_inset Formula $x_{2}$ -\end_inset - - -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -\begin_inset Formula $y=\textrm{arctan2}\left(x_{1},x_{2}\right)$ -\end_inset - - -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -0 -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -1 -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -0 -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -1 -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -0 -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -\begin_inset Formula $\frac{\pi}{2}$ -\end_inset - - -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -0 -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard --1 -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -\begin_inset Formula $\pi$ -\end_inset - - -\end_layout - -\end_inset -</cell> -</row> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard --1 -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -0 -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -\begin_inset Formula $-\frac{\pi}{2}$ -\end_inset - - -\end_layout - -\end_inset -</cell> -</row> -</lyxtabular> - -\end_inset - - -\end_layout - -\begin_layout Description -hypot ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "hypot" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns -\begin_inset Formula $y=\sqrt{x_{1}^{2}+x_{2}^{2}}.$ -\end_inset - - Given a complex number in cartesian form, arctan2 and hypot can be used - to compute phase and magnitude, quickly. -\end_layout - -\begin_layout Description -sinh ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "sinh" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Computes -\begin_inset Formula $y=\sinh\left(x\right)$ -\end_inset - - which is defined as -\begin_inset Formula $\frac{1}{2}\left(e^{x}-e^{-x}\right).$ -\end_inset - - -\end_layout - -\begin_layout Description -cosh ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "cosh" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Computes -\begin_inset Formula $y=\cosh\left(x\right)$ -\end_inset - - which is defined as -\begin_inset Formula $\frac{1}{2}\left(e^{x}+e^{-x}\right).$ -\end_inset - - -\end_layout - -\begin_layout Description -tanh ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "tanh" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Computes -\begin_inset Formula $y=\tanh\left(x\right)$ -\end_inset - - which is defined as -\begin_inset Formula $\left(e^{x}-e^{-x}\right)/\left(e^{x}+e^{-x}\right).$ -\end_inset - - -\end_layout - -\begin_layout Description -arcsinh ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "arcsinh" - -\end_inset - - -\end_layout - -\begin_layout Description -arccosh ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "arccosh" - -\end_inset - - -\end_layout - -\begin_layout Description -arctanh ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "arctanh" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - These compute the inverse hyperpolic functions. - -\begin_inset Formula $y=\textrm{arc}func\left(x\right)$ -\end_inset - - is the (principal) value of -\begin_inset Formula $y$ -\end_inset - - such that -\begin_inset Formula $func\left(y\right)=x.$ -\end_inset - - -\end_layout - -\begin_layout Subsection -Bit-twiddling functions -\end_layout - -\begin_layout Standard -These function all need integer arguments and they maniuplate the bit-pattern - of those arguments. -\end_layout - -\begin_layout Description -bitwise_and ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "bitwise\\_and" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Each bit in -\begin_inset Formula $y$ -\end_inset - - is the result of a bit-wise 'and' operation on the corresponding bits in - -\begin_inset Formula $x_{1}$ -\end_inset - - and -\begin_inset Formula $x_{2}$ -\end_inset - -. - Called to implement -\family typewriter -x1&x2 -\family default - for arrays. - -\end_layout - -\begin_layout Description -bitwise_or ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "bitwise\\_or" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Each bit in -\begin_inset Formula $y$ -\end_inset - - is the result of a bit-wise 'or' operation on the corresponding bits in - -\begin_inset Formula $x_{1}$ -\end_inset - - and -\begin_inset Formula $x_{2}$ -\end_inset - -. - Called to implement -\family typewriter -x1|x2 -\family default - for arrays. -\end_layout - -\begin_layout Description -bitwise_xor ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "bitwise\\_xor" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Each bit in -\begin_inset Formula $y$ -\end_inset - - is the result of a bit-wise 'xor' operation on the corresponding bits in - -\begin_inset Formula $x_{1}$ -\end_inset - - and -\begin_inset Formula $x_{2}$ -\end_inset - -. - An xor operation sets the output to 1 if one and only one of the input - bits is 1. - Called to implement -\family typewriter -x1^x2 -\family default - for arrays. - Using the bitwise_xor operation and the optional output argument you can - swap the values of two integer arrays of equivalent types without using - temporary arrays. -\end_layout - -\begin_layout MyCode ->>> a=arange(10) -\newline ->>> b=arange(10,20) -\newline ->>> bitwise_xor(a,b,a); bitwise_xor(a,b,b); -\newline ->> -> bitwise_xor(a,b,a) -\newline -array([10, 11, 12, 13, 14, 15, 16, 17, 18, 19]) -\newline ->>> print - a; print b -\newline -[10 11 12 13 14 15 16 17 18 19] -\newline -[0 1 2 3 4 5 6 7 8 9] -\end_layout - -\begin_layout Description -invert ( -\begin_inset Formula $x$ -\end_inset - -, [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "invert" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Each bit in -\begin_inset Formula $y$ -\end_inset - - is the opposite of the corresponding bit in -\begin_inset Formula $x$ -\end_inset - -. - Called to implement -\family typewriter -~x -\family default - for arrays. -\end_layout - -\begin_layout Description -left_shift ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "left\\_shift" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Shifts the bits of -\begin_inset Formula $x_{1}$ -\end_inset - - to the left by -\begin_inset Formula $x_{2}$ -\end_inset - -. - Called to implement -\family typewriter -x1<<x2 -\family default - for arrays. - Provided there is no overflow, the result is equal to -\begin_inset Formula $y=x_{1}2^{x_{2}}.$ -\end_inset - - -\end_layout - -\begin_layout Description -right_shift ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "right\\_shift" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Shifts the bits of -\begin_inset Formula $x_{1}$ -\end_inset - - to the right by -\begin_inset Formula $x_{2}$ -\end_inset - -. - Called to implement -\family typewriter -x1>>x2 -\family default - for arrays. - Absent overflow, the result is equal to -\begin_inset Formula $y=x_{1}2^{-x_{2}}$ -\end_inset - -. -\end_layout - -\begin_layout Subsection -Comparison functions -\end_layout - -\begin_layout Standard -All of these functions (except maximum, minimum, and sign) return Boolean - arrays. - -\end_layout - -\begin_layout Description -greater ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "greater" - -\end_inset - - -\end_layout - -\begin_layout Description -greater_equal ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "greater\\_equal" - -\end_inset - - -\end_layout - -\begin_layout Description -less ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "less" - -\end_inset - - -\end_layout - -\begin_layout Description -less_equal ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "less\\_equal" - -\end_inset - - -\end_layout - -\begin_layout Description -not_equal ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "not\\_equal" - -\end_inset - - -\end_layout - -\begin_layout Description -equal ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "equal" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - These functions are called to implement -\family typewriter -x1>x2 -\family default -, -\family typewriter -x1>=x2 -\family default -, -\family typewriter -x1<x2 -\family default -, -\family typewriter -x1<=x2 -\family default -, -\family typewriter -x1!=x2 -\family default - (or -\family typewriter -x1<>x2 -\family default -), and -\family typewriter -x1==x2 -\family default -, respectively, for arrays. -\end_layout - -\begin_layout Description -\InsetSpace ~ - The fact that these functions return Boolean arrays make them very useful - in combination with advanced array indexing. - Thus, for example, arr[arr>10] = 10 clips large values to 10. - Used in conjunction with bitwise operators quite complicated expressions - are possible. - For example, arr[~((arr<10)&(arr>5))] = 0 clips all values outside of the - range -\begin_inset Formula $\left(5,10\right)$ -\end_inset - - to 0. - -\end_layout - -\begin_layout Warning -Do not use the Python keywords -\family typewriter -and -\family default - and -\family typewriter -or -\family default - to combine logical array expressions. - These keywords will test the truth value of the entire array (not element-by-el -ement as you might expect). - Use the bitwise operators: & and | instead. -\end_layout - -\begin_layout Description -logical_and ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "logical\\_and" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The output is the truth value of -\begin_inset Formula $x_{1}$ -\end_inset - - -\series bold -and -\series default - -\begin_inset Formula $x_{2}$ -\end_inset - -. - Numbers equal to 0 are considered False. - Nonzero numbers are True. -\end_layout - -\begin_layout Description -logical_or ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "logical\\_or" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The output, -\begin_inset Formula $y$ -\end_inset - -, is the truth value of -\begin_inset Formula $x_{1}$ -\end_inset - - -\series bold -or -\begin_inset Formula $x_{2}$ -\end_inset - - -\series default - . -\end_layout - -\begin_layout Description -logical_xor ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "logical\\_xor" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The output, -\begin_inset Formula $y$ -\end_inset - -, is the truth value of -\begin_inset Formula $x_{1}$ -\end_inset - - -\series bold -xor -\begin_inset Formula $x_{2}$ -\end_inset - - -\series default -, which is the same as ( -\begin_inset Formula $x_{1}$ -\end_inset - - and not -\begin_inset Formula $x_{2}$ -\end_inset - -) or (not -\begin_inset Formula $x_{1}$ -\end_inset - - and -\begin_inset Formula $x_{2}$ -\end_inset - -). -\end_layout - -\begin_layout Description -logical_not ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "logical\\_not" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The output, -\begin_inset Formula $y$ -\end_inset - - is the truth value of -\series bold -not -\series default - -\begin_inset Formula $x$ -\end_inset - -. - -\end_layout - -\begin_layout Warning -The Bitwise operators (& and |) are the proper way to combine element-by-element - array comparisons. - Be sure to understand the operator precedence: (a>2) & (a<5) is the proper - syntax because a>2 & a<5 will result in an error due to the fact that 2 - & a is evaluated first. -\end_layout - -\begin_layout Description -maximum ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "maximum" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The output, -\begin_inset Formula $y$ -\end_inset - -, is the larger of -\begin_inset Formula $x_{1}$ -\end_inset - - and -\begin_inset Formula $x_{2}$ -\end_inset - -. - -\end_layout - -\begin_layout MyCode ->>> maximum([1,0,5,10],[3,2,4,5]) -\newline -array([ 3, 2, 5, 10]) -\newline ->>> max([1,0,5,10],[3,2, -4,5]) -\newline -[3, 2, 4, 5] -\end_layout - -\begin_layout Tip -The Python function max() will find the maximum over a one-dimensional array, - but it will do so using a slower sequence interface. - The reduce method of the maximum ufunc is much faster. - Also, the max() method will not give answers you might expect for arrays - with greater than one dimension. - The reduce method of minimum also allows you to compute a total minimum - over an array. -\end_layout - -\begin_layout Description -minimum ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "minimum" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The output, -\begin_inset Formula $y$ -\end_inset - -, is the smaller of -\begin_inset Formula $x_{1}$ -\end_inset - - and -\begin_inset Formula $x_{2}$ -\end_inset - -. -\end_layout - -\begin_layout MyCode ->>> minimum([1,0,5,10],[3,2,4,5]) -\newline -array([1, 0, 4, 5]) -\newline ->>> min([1,0,5,10],[3,2,4,5] -) -\newline -[1, 0, 5, 10] -\end_layout - -\begin_layout Warning -the behavior of maximum(a,b) is than that of max(a,b). - As a ufunc, maximum(a,b) performs an element-by-element comparison of a - and b and chooses each element of the result according to which element - in the two arrays is larger. - In contrast, max(a,b) treats the objects a and b as a whole, looks at the - (total) truth value of a>b and uses it to return either a or b (as a whole). - A similar difference exists between minimum(a,b) and min(a,b). - -\end_layout - -\begin_layout Subsection -Floating functions -\end_layout - -\begin_layout Standard -Recall that all of these functions work element-by-element over an array, - returning an array output. - The description details only a single operation. -\end_layout - -\begin_layout Description -isreal ( -\begin_inset Formula $x$ -\end_inset - -) -\begin_inset LatexCommand index -name "isreal" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - True if -\begin_inset Formula $x$ -\end_inset - - has an imaginary part that is 0. -\end_layout - -\begin_layout Description -iscomplex ( -\begin_inset Formula $x$ -\end_inset - -) -\begin_inset LatexCommand index -name "iscomplex" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - True if -\begin_inset Formula $x$ -\end_inset - - has an imaginary part that is non-zero. - -\end_layout - -\begin_layout Description -isfinite ( -\begin_inset Formula $x$ -\end_inset - -) -\begin_inset LatexCommand index -name "isfinite" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - True if -\begin_inset Formula $x$ -\end_inset - - is a finite floating point number (not a NaN or an Inf). - -\end_layout - -\begin_layout Description -isinf ( -\begin_inset Formula $x$ -\end_inset - -) -\begin_inset LatexCommand index -name "isinf" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - True if -\begin_inset Formula $x$ -\end_inset - - is -\begin_inset Formula $\pm\infty$ -\end_inset - -. - -\end_layout - -\begin_layout Description -isnan ( -\begin_inset Formula $x$ -\end_inset - -) -\begin_inset LatexCommand index -name "isnan" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - True if -\begin_inset Formula $x$ -\end_inset - - is Not-a-Number. - This represents invalid results. - When a NaN is created, the invalid flag is set. - If you set the error mode of invalid to 'warn', 'raise', or 'call', then - the appropriate action will be performed on NaN creation. - -\end_layout - -\begin_layout Description -signbit ( -\begin_inset Formula $x$ -\end_inset - -) -\begin_inset LatexCommand index -name "signbit" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - True where the sign bit of the floating point number is set. - This should correspond to -\begin_inset Formula $x>0$ -\end_inset - - when -\begin_inset Formula $x$ -\end_inset - - is a finite number. - When, -\begin_inset Formula $x$ -\end_inset - - is NaN or infinite, then this tests the actual signbit. - -\end_layout - -\begin_layout Description -modf ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y_{1}$ -\end_inset - -, -\begin_inset Formula $y_{2}$ -\end_inset - -]) -\begin_inset LatexCommand index -name "modf" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Breaks up the floating point value -\begin_inset Formula $x$ -\end_inset - - into its fractional, -\begin_inset Formula $y_{1}$ -\end_inset - -, and integral, -\begin_inset Formula $y_{2}$ -\end_inset - -, parts. - Thus, -\begin_inset Formula $x=y_{1}+y_{2}$ -\end_inset - - with -\family typewriter -floor(y2)==y2 -\family default -. - -\end_layout - -\begin_layout Description -ldexp ( -\begin_inset Formula $x$ -\end_inset - -, -\begin_inset Formula $n$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "ldexp" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Fast multiply of a floating point number by an integral power of 2: -\begin_inset Formula $y=2^{n}x.$ -\end_inset - - -\end_layout - -\begin_layout Description -frexp ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -, -\begin_inset Formula $n$ -\end_inset - -]) -\begin_inset LatexCommand index -name "frexp" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Breaks up the floating point value -\begin_inset Formula $x$ -\end_inset - - into a normalized fraction, -\begin_inset Formula $y$ -\end_inset - - and an exponent, -\begin_inset Formula $n$ -\end_inset - - which corresponds to how the value is represented in the computer. - The results are such that -\begin_inset Formula $x=y2^{n}.$ -\end_inset - - Effectively, the inverse of ldexp. - -\end_layout - -\begin_layout Description -fmod ( -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - -]) -\begin_inset LatexCommand index -name "fmod" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Computes the remainder of dividing -\begin_inset Formula $x_{1}$ -\end_inset - - by -\begin_inset Formula $x_{2}$ -\end_inset - -. - The result, -\begin_inset Formula $y$ -\end_inset - -, is -\begin_inset Formula $x_{1}-nx_{2}$ -\end_inset - - where -\begin_inset Formula $n$ -\end_inset - - is the quotient (rounded towards zero to an integer) of -\begin_inset Formula $x_{1}/x_{2}.$ -\end_inset - - -\end_layout - -\begin_layout Description -floor ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - - ]) -\begin_inset LatexCommand index -name "floor" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return -\begin_inset Formula $y=\left\lfloor x\right\rfloor $ -\end_inset - - where -\begin_inset Formula $y$ -\end_inset - - is the nearest integer smaller-than or equal to -\begin_inset Formula $x.$ -\end_inset - - Thus, -\begin_inset Formula $ $ -\end_inset - - -\begin_inset Formula $\left\lfloor x\right\rfloor \leq x<\left\lfloor x\right\rfloor +1$ -\end_inset - -. - -\end_layout - -\begin_layout Description -ceil ( -\begin_inset Formula $x$ -\end_inset - - [, -\begin_inset Formula $y$ -\end_inset - - ]) -\begin_inset LatexCommand index -name "ceil" - -\end_inset - - -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return -\begin_inset Formula $y=\left\lceil x\right\rceil $ -\end_inset - - where -\begin_inset Formula $y$ -\end_inset - - is the nearest integer greater-than or equal to -\begin_inset Formula $x$ -\end_inset - -. - Thus, -\begin_inset Formula $x\leq\left\lceil x\right\rceil <x+1.$ -\end_inset - - -\begin_inset LatexCommand index -name "ufunc|)" - -\end_inset - - -\end_layout - -\begin_layout Chapter -Basic Modules -\end_layout - -\begin_layout Quotation -It is the mark of an educated mind to rest satisfied with the degree of - precision which the nature of the subject admits and not to seek exactness - where only an approximation is possible. -\end_layout - -\begin_layout Right Address ---- -\emph on -Aristotle -\end_layout - -\begin_layout Quotation -"Oh no. - We're in the hands of engineers!" -\end_layout - -\begin_layout Right Address ---- -\emph on -Malcolm, Ian in 'Jurassic Park' -\end_layout - -\begin_layout Standard -The NumPy distribution contains some basic functionality equivalent to what - was available in the Numeric packages previously. - This section documents the new interfaces. - These are sub-packages of the NumPy namespace. - The linalg and fft capabilities are useful but limited. - You should install the full SciPy package to access more functionality. - The numpy.dual module contains functions that are defined in both SciPy - and NumPy. - If SciPy defines func, then numpy.dual.func will point to the SciPy version, - otherwise it will point to the NumPy version. - It must be imported specifically to be used. - Table -\begin_inset LatexCommand ref -reference "cap:Functions-in-numpy.dual" - -\end_inset - - shows the functions defined in numpy.dual that are in both NumPy and SciPy. -\end_layout - -\begin_layout Standard -\begin_inset Float table -wide false -sideways false -status open - -\begin_layout Standard -\begin_inset Caption - -\begin_layout Standard -\begin_inset LatexCommand label -name "cap:Functions-in-numpy.dual" - -\end_inset - -Functions in numpy.dual (both in NumPy and SciPy) -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -\align center -\begin_inset Tabular -<lyxtabular version="3" rows="4" columns="2"> -<features> -<column alignment="center" valignment="top" leftline="true" width="0"> -<column alignment="center" valignment="middle" leftline="true" rightline="true" width="55text%"> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Family -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Functions -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Fourier Transforms -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -fft, ifft, fft2, ifft2, fftn, ifftn -\end_layout - -\end_inset -</cell> -</row> -<row topline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Linear Algebra -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -norm, det, inv, pinv, solve, eig, eigh, eigvals, eigvalsh, lstsq, cholesky, - svd -\end_layout - -\end_inset -</cell> -</row> -<row topline="true" bottomline="true"> -<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -Special Functions -\end_layout - -\end_inset -</cell> -<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> -\begin_inset Text - -\begin_layout Standard -i0 -\end_layout - -\end_inset -</cell> -</row> -</lyxtabular> - -\end_inset - - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Section -Linear Algebra ( -\family typewriter -linalg -\family default -) -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "linalg|(" - -\end_inset - -These functions are in the numpy.linalg sub-package. -\end_layout - -\begin_layout Description -inv (A) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the (matrix) inverse of the 2-d array A. - The result, X, is such that dot(A,X) is equal to eye(*A.shape) (to within - machine precision). - -\end_layout - -\begin_layout Description -solve (A,b) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Find the solution to the linear equation -\begin_inset Formula $\mathbf{Ax}=\mathbf{b}$ -\end_inset - -, where -\begin_inset Formula $A$ -\end_inset - - is a 2-d array and -\begin_inset Formula $b$ -\end_inset - - is a 1-d or 2-d array. - -\end_layout - -\begin_layout Description -tensorsolve (A, b, axes=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Find the solution, -\begin_inset Formula $x_{kl}$ -\end_inset - -, to the multi-index linear equation -\begin_inset Formula \[ -\sum_{kl}A_{ijkl}x_{kl}=b_{ij}.\] - -\end_inset - - The axes argument specifies which dimensions of -\begin_inset Formula $A$ -\end_inset - - are summed over. - If it is None, then the last A.ndim - b.ndim dimensions are summed over. - The result, therefore, has dimension x.ndim = A.ndim-b.ndim. - -\end_layout - -\begin_layout Description -tensorinv (A, ind=2) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Find the tensor inverse of -\begin_inset Formula $A$ -\end_inset - -, defined to be the tensor such that tensordot (Ainv, A) is an identity - operator. - -\end_layout - -\begin_layout Description -cholesky (A) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return, -\begin_inset Formula $\mathbf{L}$ -\end_inset - -, the Cholesky decomposition of -\begin_inset Formula $\mathbf{A}$ -\end_inset - -. - Cholesky decomposition is applicable to a Hermitian, positive definite - matrices. - When -\begin_inset Formula $\mathbf{A}=\mathbf{A}^{H}$ -\end_inset - - and -\begin_inset Formula $\mathbf{x}^{H}\mathbf{Ax}\geq0$ -\end_inset - - for all -\begin_inset Formula $\mathbf{x}$ -\end_inset - -, then decompositions of -\begin_inset Formula $\mathbf{A}$ -\end_inset - - can be found so that -\begin_inset Formula $\mathbf{A}=\mathbf{LL}^{H}$ -\end_inset - -, where -\begin_inset Formula $\mathbf{L}$ -\end_inset - - is lower-triangular. - -\end_layout - -\begin_layout Description -eigvals (A) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return all solutions ( -\begin_inset Formula $\lambda$ -\end_inset - -) to the equation -\begin_inset Formula $\mathbf{Ax}=\lambda\mathbf{x}$ -\end_inset - -. -\end_layout - -\begin_layout Description -eig (A) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return all solutions -\begin_inset Formula $\left(\lambda,\mathbf{x}\right)$ -\end_inset - - to the equation -\begin_inset Formula $\mathbf{Ax}=\lambda\mathbf{x}$ -\end_inset - -. - The first element of the return tuple contains all the eigenvalues. - The second element of the return tuple contains the eigenvectors in the - columns (x[:,i] is the ith eigenvector). -\end_layout - -\begin_layout Description -eigvalsh (U) -\end_layout - -\begin_layout Description -eigh (U) -\end_layout - -\begin_layout Description -\InsetSpace ~ - These functions are identical to eigvals and eig except they only work - with Hermitian matrices where -\begin_inset Formula $\mathbf{U}^{H}=\mathbf{U}$ -\end_inset - - (only the lower-triangular part of the array is used). -\end_layout - -\begin_layout Description -svd (A) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Compute the singular value decomposition of the 2-d array -\begin_inset Formula $\mathbf{A}$ -\end_inset - -. - Every -\begin_inset Formula $m\times n$ -\end_inset - - matrix can be decomposed into a pair of unitary matrices, -\begin_inset Formula $\mathbf{U}=\mathbf{U}^{H}$ -\end_inset - - ( -\begin_inset Formula $m\times m$ -\end_inset - -) and -\begin_inset Formula $\mathbf{V}=\mathbf{V}^{H}$ -\end_inset - - ( -\begin_inset Formula $n\times n$ -\end_inset - -) and an -\begin_inset Formula $m\times n$ -\end_inset - - -\begin_inset Quotes eld -\end_inset - -diagonal -\begin_inset Quotes erd -\end_inset - - matrix -\begin_inset Formula $\boldsymbol{\Sigma}$ -\end_inset - -, such that -\begin_inset Formula $\mathbf{A}=\mathbf{U\boldsymbol{\Sigma}}\mathbf{V}^{H}$ -\end_inset - -. - The only non-zero portion of -\begin_inset Formula $\boldsymbol{\Sigma}$ -\end_inset - - is the upper -\begin_inset Formula $r\times r$ -\end_inset - - block where -\begin_inset Formula $r=\min\left(m,n\right)$ -\end_inset - -. - The svd function returns three arrays as a tuple: ( -\begin_inset Formula $\mathbf{U}$ -\end_inset - -, -\begin_inset Formula $\boldsymbol{\sigma}$ -\end_inset - -, -\begin_inset Formula $\mathbf{V}^{H}$ -\end_inset - -). - The singular values are returned in the 1-d array -\begin_inset Formula $\boldsymbol{\sigma}$ -\end_inset - -. - If needed, the array -\begin_inset Formula $\boldsymbol{\Sigma}$ -\end_inset - - can be found (if really needed) using the command diag( -\begin_inset Formula $\boldsymbol{\sigma}$ -\end_inset - -) which creates the -\begin_inset Formula $r\times r$ -\end_inset - - diagonal block and then inserting this into a zeros matrix: -\end_layout - -\begin_layout MyCode ->>> A = random.rand(3,5) -\newline ->>> from numpy.dual import svd; U,s,Vh = svd(A) -\newline ->>> - r=min(*A.shape); Sig = zeros_like(A); -\newline ->>> Sig[:r,:r] = diag(s); print Sig -\newline -[[ - 2.1634 0. - 0. - 0. - 0. - ] -\newline - [ 0. - 0.7076 0. - 0. - 0. - ] -\newline - [ 0. - 0. - 0.2098 0. - 0. - ]] -\end_layout - -\begin_layout Description -pinv (A, rcond= -\begin_inset Formula $10^{-10}$ -\end_inset - -) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the generalized, pseudo inverse, of -\begin_inset Formula $A$ -\end_inset - -. - For invertible matrices, this is the same as the inverse. - -\end_layout - -\begin_layout Description -det (A) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the determinant of the array. - The determinant of an array is the product of its singular values. - -\end_layout - -\begin_layout Description -lstsq (A, b, rcond= -\begin_inset Formula $10^{-10}$ -\end_inset - -) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return (x, resids, rank, s) where x minimizes resids= -\begin_inset Formula $\left\Vert \mathbf{Ax}-\mathbf{b}\right\Vert _{2}$ -\end_inset - -. - The output rank is the rank of A and s is the singular values of a in descendin -g order. - Singular values less than s[0]*rcond are treated as 0. - If the rank of A is less than the number of columns of A or greater than - the number of rows, resids will be returned as an empty array. -\begin_inset LatexCommand index -name "linalg|)" - -\end_inset - - -\end_layout - -\begin_layout Section -Discrete Fourier Transforms ( -\family typewriter -fft -\family default -) -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "fft|(" - -\end_inset - -All of the algorithms here are most efficient if the length of the data - is a power of 2 (or decomposable into low prime factors). - -\end_layout - -\begin_layout Description -fft (x, n=None, axis=-1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return, X, the N-point Discrete Fourier Transform (DFT) of x along the - given axis using a fast algorithm. - If N is larger than x.shape[axis], then x will be zero-padded. - If N is smaller than x.shape[axis], then the first N items will be used. - The result is computed for -\begin_inset Formula $k=0\ldots n-1$ -\end_inset - - from the formula: -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -X\left[k\right]=\sum_{m=0}^{n-1}x[m]\exp\left(-j\frac{2\pi km}{n}\right).\] - -\end_inset - - -\end_layout - -\begin_layout Tip -The fft returns values for -\begin_inset Formula $k=0\ldots N-1$ -\end_inset - -. - Because -\begin_inset Formula $X\left[N-k\right]=X[-k]$ -\end_inset - - in the FFT formula, larger values of k correspond also to negative frequencies. -\end_layout - -\begin_layout Description -ifft (X, n=None, axis=-1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the inverse of the fft so that (ifft(fft(a)) == a within numerical - precision. - The order of frequencies must be the same as returned by fft. - The result is computed (using a fast algorithm) for -\begin_inset Formula $m=0\ldots n-1$ -\end_inset - - from the formula: -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -x\left[m\right]=\frac{1}{n}\sum_{k=0}^{n-1}X\left[k\right]\exp\left(j\frac{2\pi km}{n}\right).\] - -\end_inset - - -\end_layout - -\begin_layout Standard -Sometimes having the -\begin_inset Quotes eld -\end_inset - -negative -\begin_inset Quotes erd -\end_inset - - frequencies at the end of the output returned by fft can be a little confusing. - There are two ways to deal with this confusion. - In my opinion, the most useful way is to get a collection of DFT sample - frequencies and use them to keep track of where each frequency is. - The function -\family typewriter -fftfreq -\family default - provides these sample frequencies. - Making an x-y plot, where the sample frequencies are along the -\begin_inset Quotes eld -\end_inset - -x -\begin_inset Quotes erd -\end_inset - --axis and the result of the DFT is along the -\begin_inset Quotes eld -\end_inset - -y -\begin_inset Quotes erd -\end_inset - --axis provides a useful visualization with the zero-frequency at the center - of the plot. - The advantage of this approach is that your data is still in proper order - for using the -\family typewriter -ifft -\family default - function. - Some people, however, prefer to simply swap one-half of the output with - the other. - This is exactly what the function -\family typewriter -fftshift -\family default - does. - Of course, now the data is not in the proper order for the ifft function, - but to each his own. - -\end_layout - -\begin_layout Standard -The reason that the -\begin_inset Quotes eld -\end_inset - -negative -\begin_inset Quotes erd -\end_inset - - frequencies are in the upper part of the return signal was given in the - description of the DFT. - The reason is that the output of the DFT is just one period of a periodic - function (with period -\begin_inset Formula $n$ -\end_inset - -). - The traditional output of the FFT algorithm is to provide the portion of - the function from from -\begin_inset Formula $k=0$ -\end_inset - - to -\begin_inset Formula $k=n-1$ -\end_inset - -. - -\end_layout - -\begin_layout Description -fftshift (x, axes=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Shift zero-frequency component to the center of the spectrum. - This function swaps half-spaces for all axes listed (defaults to all of - them). - -\end_layout - -\begin_layout Description -ifftshift (x, axes=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Reverse the effect of the fftshift operation. - Thus, it takes zero-centered data and shifts it into the correct order - for the ifft operation. -\end_layout - -\begin_layout Description -fftfreq (n, d=1.0) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Provide the DFT sample frequencies. - The returned float array contains the frequency bins in the order returned - from the fft function. - If given, -\begin_inset Formula $d$ -\end_inset - - represents the sample-spacing. - The units on the frequency bins are cycles / unit. - For example, the following example computes the output frequencies (in - Hz) of the fft of -\begin_inset Formula $256$ -\end_inset - - samples of a voice signal sampled at 20000Hz. -\end_layout - -\begin_layout MyCode ->>> from numpy.fft import fftfreq; f=fftfreq(256,d=1./20e3) -\newline ->>> print f[0], - f[1], f[2], f[128] -\newline -0.0 78.125 156.25 -10000.0 -\end_layout - -\begin_layout Description -fft2 (x, s=None, axes=(-2,-1)) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the two-dimensional fft of the array x for each 2-d array formed - by axes. - The 2-d fft is computed as -\begin_inset Formula \[ -X\left[k_{0},k_{1}\right]=\sum_{m_{0}=0}^{s[0]-1}\sum_{m_{1}=0}^{s[1]-1}x\left[m_{0},m_{1}\right]\exp\left(-j\frac{2\pi k_{0}m_{0}}{s[0]}\right)\exp\left[-j\frac{2\pi k_{1}m_{1}}{s\left[1\right]}\right]\] - -\end_inset - - and can be realized by repeated application of the 1-d fft (first over - the axes[0] and then over axes[1]). - In other-words fft2(x,s,axes) is equivalent to fft(fft(x, s[0], axes[0]), - s[1], axes[1]). - The 2-d fft is returned for -\begin_inset Formula $k_{0}=0\ldots s[0]-1$ -\end_inset - - and -\begin_inset Formula $k_{1}=0\ldots s[1]-1.$ -\end_inset - - Symmetry ( -\begin_inset Formula $X\left[s[0]-k_{0},s[1]-k_{1}\right]=X[-k_{0},-k_{1}]$ -\end_inset - -) ensures that higher values of -\begin_inset Formula $k_{i}$ -\end_inset - - correspond to negative frequencies. - -\end_layout - -\begin_layout Description -ifft2 (X, s=None, axes=(-2,-1)) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the inverse of the two-dimension fft. - Thus, ifft2(fft2(x)) == x to within numerical precision. - Note that the -\begin_inset Quotes eld -\end_inset - -negative frequencies -\begin_inset Quotes erd -\end_inset - - must be -\end_layout - -\begin_layout Description -fftn (x, s=None, axes=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the -\begin_inset Formula $N$ -\end_inset - --dimensional fft of x. - If s is not given, then if axes is given, then -\begin_inset Formula $N$ -\end_inset - -=len(axes), otherwise -\begin_inset Formula $N$ -\end_inset - -=x.ndim. - If s is given, then -\begin_inset Formula $N$ -\end_inset - -=len(s). - Results are computed using a similar formula as for the 1- and 2-d FFT - with -\begin_inset Formula $N$ -\end_inset - - summations. - -\end_layout - -\begin_layout Description -ifftn (X, s=None, axes=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the -\begin_inset Formula $N$ -\end_inset - --dimensional inverse fft of -\begin_inset Formula $X$ -\end_inset - -. - Note that ifftn(fftn(x)) == x to within machine precision. - -\end_layout - -\begin_layout Standard -The Discrete Fourier transform returns complex-valued data (even for real-valued - input). - If the data was originally real-valued, then much of the output of the - full DFT is redundant. - Notice that if -\begin_inset Formula $x\left[m\right]$ -\end_inset - - is real, then -\begin_inset Formula \begin{eqnarray*} -X\left[n-k\right] & = & \sum_{m=0}^{n-1}x[m]\exp\left(-j\frac{2\pi\left(n-k\right)m}{n}\right)\\ - & = & \left[\sum_{m=0}^{n-1}x\left[m\right]\exp\left(-j\frac{2\pi km}{n}\right)\right]^{*}\\ - & = & X^{*}\left[k\right],\end{eqnarray*} - -\end_inset - -where -\begin_inset Formula $a^{*}$ -\end_inset - - denotes the complex-conjugate of -\begin_inset Formula $a$ -\end_inset - -. - So, the upper half of the fft output (the negative frequencies) is determined - exactly by the lower half of the output when the input is purely real. - This kind of symmetry is called Hermitian symmetry. - The real-valued Fourier transforms described next take advantage of Hermitian - symmetry to compute only the unique outputs more quickly. - -\end_layout - -\begin_layout Standard -The symmetry in higher dimensions is always about the origin. - If -\begin_inset Formula $N$ -\end_inset - - is the number of dimensions, then: -\begin_inset Formula \[ -X[n_{1}-k_{1},n_{2}-k_{2},\ldots n_{N}-k_{N}]=X^{*}\left[k_{1},k_{2},\ldots,k_{N}\right].\] - -\end_inset - -Thus, the data-savings remains constant at about 1/2 for higher dimensions - as well. - -\end_layout - -\begin_layout Description -rfft (x, n=None, axis=-1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Compute the first n//2+1 points of the -\begin_inset Formula $n$ -\end_inset - --point discrete Fourier transform of the real valued data along the given - axis. - The returned array will be just the first half of the -\family typewriter -fft -\family default -, corresponding to positive frequencies: rfft(x) == fft(x)[:n//2+1] -\end_layout - -\begin_layout Description -irfft (X, n=None, axis=-1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Compute the inverse -\begin_inset Formula $n$ -\end_inset - --point discrete Fourier transform along the given axis using the first n//2+1 - points. - To within numerical precision, irfft(rfft(x))==x. - -\end_layout - -\begin_layout Description -rfft2 (x, s=None, axes=(-2, -1)) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Compute only the first half-plane of the two-dimensional discrete Fourier - transform corresponding to unique values. - s[0] and -\begin_inset Formula $s[1]$ -\end_inset - --point DFTs will be computed along axes[0] and axes[1] dimensions, respectively. - Requires a real array. - If -\begin_inset Formula $s$ -\end_inset - - is None it defaults to the shape of -\begin_inset Formula $x.$ -\end_inset - - The real fft will be computed along the last axis specified in axes while - a full fft will be computed in the other dimension. -\end_layout - -\begin_layout Description -irfft2 (X, s=None, axes=(-2, -1)) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Compute the inverse of the 2-d DFT using only the first quadrant. - Returns a real array such that to within numerical precision irfft2(rfft2(x))== -x. -\end_layout - -\begin_layout Description -rfftn (x, s=None, axes=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Compute only the unique part of the -\begin_inset Formula $N$ -\end_inset - --dimensional DFT from a real-valued array. - If -\begin_inset Formula $s$ -\end_inset - - is None it defaults to the shape of x. - If axes is not given it defaults to all the axes (-n, -\begin_inset Formula $\ldots$ -\end_inset - -, -1). - The length of axes provides the dimensionality of the DFT. - The unique part of the real -\begin_inset Formula $N$ -\end_inset - --dimensional DFT is obtained by slicing the full fft along the last axis - specified and taking n//2+1 slices. - rfftn(x) == fft(x)[sliceobj] where sliceobj[axes[-1]] = slice(None,s[-1]//2+1,N -one). -\end_layout - -\begin_layout Description -irfftn (X, s=None, axes=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Compute the inverse DFT from the unique portions of the N-dimensional DFT - provided by -\family typewriter -rfftn -\family default -. -\end_layout - -\begin_layout Standard -Occasionally, the situation may arise where you have complex-valued data - with Hermitian symmetry (or real-valued symmetric data). - This ensures that the Fourier transform will be real. - The two functions below can calculate it without wasting extra space for - the zero-valued imaginary entries of the Discrete Fourier transform, or - the entire signal. -\end_layout - -\begin_layout Description -hfft (x, n=None, axis=-1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Calculate the -\begin_inset Formula $n$ -\end_inset - --point real-valued Fourier transform from (the first half of Hermitian-symmetric - data, x. - -\end_layout - -\begin_layout Description -ihfft (X, n=None, axis=-1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return (the first half-of) Hermitian-symmetric data from the real-valued - Fourier transform, X. -\begin_inset LatexCommand index -name "fft|)" - -\end_inset - - -\end_layout - -\begin_layout Section -Random Numbers ( -\family typewriter -random -\family default -) -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "random|(" - -\end_inset - -The random number capabilities surpass those that were available in Numeric. - The random number facilities were generously contributed by Robert Kern, - who has been a dedicated and patient help to many mailing list questioners. - Robert built the random package using Pyrex to build on top of his own - code as well as that of randomkit by Jean-Sebastien Roy as well as code - by Ivan Frohne. - The fundamental random number generator is the Mersenne Twister based on - code written by Makoto Matsumoto and Takuji Nishimura (and modified for - Python by Raymond Hettinger). - Random numbers from discrete and continuous distributions are available, - as well as some useful random-number-related utilities. - Many of the random number generators are based on algorithms published - by Luc Devroye in -\begin_inset Quotes eld -\end_inset - -Non-Uniform Random Variate Generation -\begin_inset Quotes erd -\end_inset - - available electronically at -\begin_inset LatexCommand htmlurl -target "http://cgm.cs.mcgill.ca/~luc/rnbookindex.html" - -\end_inset - - -\end_layout - -\begin_layout Standard -Each of the discrete and continuous random number generators take a size - keyword. - If this is None (default), then the size is determined from the additional - inputs (using ufunc-like broadcasting). - If no additional inputs are needed, or if these additional inputs are scalars, - then a single number is generated from the selected distribution. - If size is an integer, then a 1-d array of that size is generated filled - with random numbers from the selected distribution. - Finally, if size is a tuple, then an array of that shape is returned filled - with random numbers. - -\end_layout - -\begin_layout Standard -Many distributions take additional inputs as parameters. - These additional inputs must be broadcastable to each other (and to the - size parameter if it is not None). - The broadcasting behavior of the additional inputs is ufunc-like. - -\end_layout - -\begin_layout Subsection -Discrete Distributions -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "random!discrete|(" - -\end_inset - -Discrete random numbers take on only a countable number of values (typically - integers). - Each distribution has associated with it a probability mass function (pmf), - -\begin_inset Formula $p_{m}\left(k;\cdot\right),$ -\end_inset - - that is defined as the probability that the returned random number is -\begin_inset Formula $k$ -\end_inset - -. - The arguments after -\begin_inset Formula $k$ -\end_inset - - represent possible parameters to the distribution. - Thus, let -\begin_inset Formula $X\left(\cdot\right)$ -\end_inset - - represent the random number generator for a particular distribution. - Then, -\begin_inset Formula \[ -p_{m}\left(k;\cdot\right)=\textrm{Probability}\left\{ X\left(\cdot\right)=k\right\} .\] - -\end_inset - - -\end_layout - -\begin_layout Standard -It will be useful to define the discrete indicator function, -\begin_inset Formula $I_{S}\left(k\right),$ -\end_inset - - where -\begin_inset Formula $S$ -\end_inset - - is a set of integers (often represented by an interval). - -\begin_inset Formula $I_{S}\left(k\right)=1$ -\end_inset - - if -\begin_inset Formula $k\in S$ -\end_inset - -, otherwise -\begin_inset Formula $I_{S}\left(k\right)=0.$ -\end_inset - - This convenient notation isolates the relevance of a particular functional - form to a certain range. - Also, the formulas below make use of the following definition: -\begin_inset Formula \[ -\left(\begin{array}{c} -n\\ -k\end{array}\right)=\frac{n!}{k!\left(n-k\right)!}\] - -\end_inset - - where -\begin_inset Formula $k!=k\cdot\left(k-1\right)\cdot\cdots\cdot2\cdot1.$ -\end_inset - - -\end_layout - -\begin_layout Description -binomial (n, p, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This random number models the number of successes in -\begin_inset Formula $n$ -\end_inset - - independent trials of a random experiment where the probability of success - in each experiment is -\begin_inset Formula $p$ -\end_inset - -. - -\begin_inset Formula \[ -p_{m}\left(k\right)=\left(\begin{array}{c} -n\\ -k\end{array}\right)p^{k}\left(1-p\right)^{n-k}I_{\left[0,n\right]}\left(k\right).\] - -\end_inset - - -\end_layout - -\begin_layout Description -geometric (p, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This random number models the number of (independent) attempts required - to obtain a success where the probability of success on each attempt is - -\begin_inset Formula $p$ -\end_inset - -. - -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -p_{m}\left(k;p\right)=\left(1-p\right)^{k-1}p\, I_{\left[1,\infty\right)}\left(k\right).\] - -\end_inset - - -\end_layout - -\begin_layout Description -hypergeometric (ngood, nbad, nsample, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Imagine a probability theorists favorite urn filled with -\begin_inset Formula $n_{g}$ -\end_inset - - -\begin_inset Quotes eld -\end_inset - -good -\begin_inset Quotes erd -\end_inset - - objects and -\begin_inset Formula $n_{b}$ -\end_inset - - -\begin_inset Quotes eld -\end_inset - -bad -\begin_inset Quotes erd -\end_inset - - objects. - In other words there are two types of objects in a jar. - The hypergeometric random number models how many -\begin_inset Quotes eld -\end_inset - -good -\begin_inset Quotes erd -\end_inset - - objects will be present when -\begin_inset Formula $N$ -\end_inset - - items are taken out of the urn without replacement. -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -p\left(k;n_{g},n_{b},N\right)=\frac{\left(\begin{array}{c} -n_{g}\\ -k\end{array}\right)\left(\begin{array}{c} -n_{b}\\ -N-k\end{array}\right)}{\left(\begin{array}{c} -n_{g}+n_{b}\\ -N\end{array}\right)}I_{\left[N-n_{b},\textrm{min}\left(n,N\right)\right]}\left(k\right).\] - -\end_inset - - -\end_layout - -\begin_layout Description -logseries (p, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - A random number whose pmf with terms proportional to the Taylor series - expansion of -\begin_inset Formula $\log\left(1-p\right)$ -\end_inset - -. - It has been used in biological studies to model the species abundance distribut -ion. - -\begin_inset Formula \[ -p_{m}\left(k;p\right)=-\frac{p^{k}}{k\log\left(1-p\right)}\, I_{\left[1,\infty\right)}\left(k\right).\] - -\end_inset - - -\end_layout - -\begin_layout Description -multinomial (n, pvals, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This generator produces random vectors of length -\begin_inset Formula $N$ -\end_inset - - where -\begin_inset Formula $N=\textrm{len}\left(pvals\right)$ -\end_inset - -. - The shape of the returned array is always the shape indicated by size + - ( -\begin_inset Formula $N,$ -\end_inset - -). - The multinomial distribution is a generalization of the binomial distribution. - This time, -\begin_inset Formula $n$ -\end_inset - - trials of an experiment are independently repeated but each trial results - in -\begin_inset Formula $N$ -\end_inset - - possible integers -\begin_inset Formula $k_{1},k_{2},\ldots,k_{N}$ -\end_inset - - with -\begin_inset Formula $\sum_{i=1}^{N}k_{i}=n.$ -\end_inset - - -\begin_inset Formula \begin{eqnarray*} -p_{m}\left(k_{1},k_{2},\ldots,k_{N};\cdot\right) & = & \textrm{Probability}\left\{ X\left(\cdot\right)=\left[k_{1},k_{2},\cdots,k_{N}\right]\right\} \\ - & = & \frac{n!}{k_{1}!k_{2}!\cdots k_{N}!}p_{1}^{k_{1}}p_{2}^{k_{2}}\cdots p_{N}^{k_{N}}\end{eqnarray*} - -\end_inset - -where -\begin_inset Formula $pvals=[p_{1},p_{2},\ldots,p_{N}].$ -\end_inset - - It must be true that -\begin_inset Formula $\sum_{i=1}^{N}p_{i}=1.$ -\end_inset - - Therefore, as long as -\begin_inset Formula $\sum_{i=1}^{N-1}p_{i}\leq1,$ -\end_inset - - the last entry in -\begin_inset Formula $pvals$ -\end_inset - - is computed as -\begin_inset Formula $1-\sum_{i=1}^{N-1}p_{i}$ -\end_inset - -. -\end_layout - -\begin_layout Description -negative_binomial (n, p, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Models the number of extra independent trials (beyond -\begin_inset Formula $n$ -\end_inset - -) required to accumulate a total of -\begin_inset Formula $n$ -\end_inset - - successes where the probability of success on each trial is -\begin_inset Formula $p.$ -\end_inset - - Equivalently, this random number models the number of failures encountered - while accumulating -\begin_inset Formula $n$ -\end_inset - - successes during independent trials of the experiment that succeeds with - probability, -\begin_inset Formula $p$ -\end_inset - -. - -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -p_{m}\left(k;n,p\right)=\left(\begin{array}{c} -k+n-1\\ -n-1\end{array}\right)p^{n}\left(1-p\right)^{k}\, I_{\left[0,\infty\right)}\left(k\right).\] - -\end_inset - - -\end_layout - -\begin_layout Description -poisson (lam=1.0, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This random number counts the number of successes in -\begin_inset Formula $n$ -\end_inset - - independent experiments (where the probability of success in each experiment - is -\begin_inset Formula $p$ -\end_inset - -) in the limit as -\begin_inset Formula $n\rightarrow\infty$ -\end_inset - - and -\begin_inset Formula $p\rightarrow0$ -\end_inset - - gets very small such that -\begin_inset Formula $\lambda=np\geq0$ -\end_inset - - is a constant. - It can be used, for example, to model how many typographical errors are - on each page of a book. -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -p\left(k;\lambda\right)=e^{-\lambda}\frac{\lambda^{k}}{k!}\, I_{\left[0,\infty\right)}\left(k\right).\] - -\end_inset - - -\end_layout - -\begin_layout Description -zipf (a, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - The probability mass function of this random number (also called the zeta - distribution) is -\begin_inset Formula \[ -p_{m}\left(k;a\right)=\frac{1}{\zeta\left(a\right)k^{a}}\, I_{\left[1,\infty\right)}\left(k\right),\] - -\end_inset - -where -\begin_inset Formula \[ -\zeta\left(a\right)=\sum_{n=1}^{\infty}\frac{1}{n^{a}}\] - -\end_inset - -is the Riemann zeta function. - Zipf distributions have been shown to characterize use of words in a natural - language (like English), the popularity of library books, and even the - use of the web. - The Zipf distribution describes collections that have a few items whose - probability of selection is very high, a medium number of items whose probabili -ty of selection is medium, and a huge number of items whose probability - of selection is very low. -\begin_inset LatexCommand index -name "random!discrete|)" - -\end_inset - - -\end_layout - -\begin_layout Subsection -Continuous Distributions -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "random!continuous|(" - -\end_inset - -Continuous random numbers can take on an uncountable number of values. - Therefore, the value returned by a continuous distribution is denoted -\begin_inset Formula $x$ -\end_inset - -. - Because there is an uncountable number of possibilities for the random - number -\begin_inset Foot -status open - -\begin_layout Standard -A computer actually always generates a random number from a discrete distributio -n because there are only a finite set of numbers that can be represented - by a computer. - However, for continuous random number generators, the resulting random - numbers usually approximate the continuous distribution well enough to - ignore the subtlety. -\end_layout - -\end_inset - -, a continuous distribution is modeled by a probability density function, - -\begin_inset Formula $f\left(x;\cdot\right).$ -\end_inset - - To obtain the probability that the random number generated by -\begin_inset Formula $X\left(\cdot\right)$ -\end_inset - - is in a certain interval, we integrate this density function: -\begin_inset Formula \[ -\int_{-\infty}^{b}f\left(x\right)dx=\textrm{Probability}\left\{ X\left(\cdot\right)\leq b\right\} .\] - -\end_inset - - -\end_layout - -\begin_layout Standard -To obtain a probability, we have to integrate -\begin_inset Formula $f\left(x\right)$ -\end_inset - - which is why it is called a density function. - Most continuous distributions are defined by their probability density - functions (pdf). - Some have basic origins, a few are derived from other distributions, and - some are used mainly for modelling unknown distributions. - -\end_layout - -\begin_layout Standard -Some of the parameters of the distributions are labeled as location ( -\emph on -loc -\emph default -) and -\emph on -scale -\emph default - parameters. - These parameters are not shown in the equation for the pdf. - because they affect the distribution in a known way. - This is due to the fact that if -\begin_inset Formula $X$ -\end_inset - - is a number drawn from a distribution with pdf -\begin_inset Formula $f_{X}\left(x\right),$ -\end_inset - - then -\begin_inset Formula $Y=Sx+L$ -\end_inset - - is a number drawn from a distribution with pdf -\begin_inset Formula \[ -f_{Y}\left(y\right)=\frac{1}{S}f_{X}\left(\frac{y-L}{S}\right).\] - -\end_inset - - Thus, from the standard from provided, the pdf of the actual random numbers - generated by fixing the location and scale parameters can be quickly found. -\end_layout - -\begin_layout Standard -In this section, the indicator function -\begin_inset Formula $I_{A}\left(x\right)$ -\end_inset - - will be used where -\begin_inset Formula $A$ -\end_inset - - is a set defined over all the real numbers. - For clarity, -\begin_inset Formula \[ -I_{A}\left(x\right)=\left\{ \begin{array}{cc} -1 & x\in A,\\ -0 & x\not\in A.\end{array}\right.\] - -\end_inset - - Also, the following functions are used in the definitions: -\begin_inset Formula \begin{eqnarray*} -\Gamma\left(x\right) & = & \int_{0}^{\infty}t^{x-1}e^{-t}dt=\left(x-1\right)\Gamma\left(x-1\right),\\ -B\left(a,b\right) & = & \frac{\Gamma\left(a\right)\Gamma\left(b\right)}{\Gamma\left(a+b\right)}.\end{eqnarray*} - -\end_inset - - -\end_layout - -\begin_layout Description -beta ( -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $b$ -\end_inset - -, size=None) -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -f\left(x;a,b\right)=\frac{1}{B\left(a,b\right)}x^{a-1}\left(1-x\right)^{b-1}I_{\left(0,1\right)}\left(x\right).\] - -\end_inset - - -\end_layout - -\begin_layout Description -chisquare ( -\begin_inset Formula $\nu$ -\end_inset - -, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - If -\begin_inset Formula $Z_{1},\ldots,Z_{\nu}$ -\end_inset - - are random numbers from standard normal distributions, then -\begin_inset Formula $W=\sum_{k=1}^{\nu}Z_{k}^{2}$ -\end_inset - - is a random number from the chi-square -\begin_inset Formula $\left(\chi^{2}\right)$ -\end_inset - - distribution with -\begin_inset Formula $\nu$ -\end_inset - - degrees of freedom. - -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -f\left(x;\nu\right)=\frac{1}{2\Gamma\left(\frac{\nu}{2}\right)}\left(\frac{x}{2}\right)^{\nu/2-1}e^{-x/2}I_{\left[0,\infty\right)}\left(x\right).\] - -\end_inset - - -\end_layout - -\begin_layout Description -dirichlet ( -\begin_inset Formula $\boldsymbol{\alpha},$ -\end_inset - - size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - A vector of random numbers which are drawn from a multivariate Dirichlet - distribution. - The length of the parameter vector, -\begin_inset Formula $\boldsymbol{\alpha},$ -\end_inset - - is the length, -\begin_inset Formula $N$ -\end_inset - -, of the random vector. - The joint pdf is: -\end_layout - -\begin_layout Description -\begin_inset Formula \[ -f\left(\mathbf{x},\boldsymbol{\alpha}\right)=\frac{\prod_{i=1}^{N}\Gamma\left(\alpha_{i}\right)}{\Gamma\left(\sum_{i=1}^{N}\alpha_{i}\right)}\prod_{i=1}^{N}x_{i}^{\alpha_{i}-1}.\] - -\end_inset - - -\series medium - -\end_layout - -\begin_layout Description -exponential (scale=1.0, size=None) -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -f\left(x\right)=e^{-x}I_{\left[0,\infty\right)}\left(x\right).\] - -\end_inset - - -\end_layout - -\begin_layout Description -f ( -\begin_inset Formula $\nu_{1}$ -\end_inset - -, -\begin_inset Formula $\nu_{2}$ -\end_inset - -, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - The distribution of -\begin_inset Formula $\frac{X_{1}/\nu_{1}}{X_{2}/\nu_{2}}$ -\end_inset - - where -\begin_inset Formula $X_{i}$ -\end_inset - - is chi-squared with -\begin_inset Formula $\nu_{i}$ -\end_inset - - degrees of freedom. -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -f\left(x;\nu_{1},\nu_{2}\right)=\frac{\nu_{2}^{\nu_{2}/2}\nu_{1}^{\nu_{1}/2}x^{\nu_{1}/2-1}}{\left(\nu_{2}+\nu_{1}x\right)^{\left(\nu_{1}+\nu_{2}\right)/2}B\left(\frac{\nu_{1}}{2},\frac{\nu_{2}}{2}\right)}I_{\left[0,\infty\right)}\left(x\right).\] - -\end_inset - - -\end_layout - -\begin_layout Description -gamma ( -\begin_inset Formula $a$ -\end_inset - -, scale=1.0, size=None) -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -f\left(x;a\right)=\frac{1}{\Gamma\left(a\right)}x^{a-1}e^{-x}I_{\left[0,\infty\right)}\left(x\right).\] - -\end_inset - - -\end_layout - -\begin_layout Description -gumbel (loc=0.0, scale=1.0, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - A right-skewed extreme value distribution. - -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -f\left(x\right)=\exp\left[-x-e^{-x}\right].\] - -\end_inset - - -\end_layout - -\begin_layout Description -laplace (loc=0.0, scale=1.0, size=None) -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -f\left(x\right)=\frac{1}{2}e^{-\left|x\right|}.\] - -\end_inset - - -\end_layout - -\begin_layout Description -lognormal ( -\begin_inset Formula $\mu$ -\end_inset - -=0.0, -\begin_inset Formula $\sigma$ -\end_inset - -=1.0, size=None) -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -f\left(x;\mu,\sigma\right)=\frac{1}{\sigma x\sqrt{2\pi}}\exp\left[-\frac{1}{2}\left(\frac{\log x-\mu}{\sigma}\right)^{2}\right]I_{\left[0,\infty\right)}\left(x\right),\] - -\end_inset - -The parameters, -\begin_inset Formula $\mu$ -\end_inset - - and -\begin_inset Formula $\sigma$ -\end_inset - - are not the mean and variance of this distribution, but the parameters - of the underlying normal distribution. - Random numbers from this distribution are generated as -\begin_inset Formula $e^{\sigma Z+\mu}$ -\end_inset - - where -\begin_inset Formula $Z$ -\end_inset - - is a standard normal random number. - -\end_layout - -\begin_layout Description -logistic (loc=0.0, scale=1.0, size=None) -\begin_inset Formula \[ -f\left(x\right)=\frac{e^{-x}}{\left[1+e^{-x}\right]^{2}}I_{\left[0,\infty\right)}\left(x\right)\] - -\end_inset - - -\end_layout - -\begin_layout Description -multivariate_normal ( -\begin_inset Formula $\mathbf{\boldsymbol{\mu}}$ -\end_inset - -, -\begin_inset Formula $\mathbf{C}$ -\end_inset - -, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns a vector of random numbers which are jointly drawn from a multivariate - normal distribution. - The last-dimension of the output array contains the sample vector, which - is of length -\begin_inset Formula $N=\textrm{len}\left(mean\right).$ -\end_inset - - The covariance matrix must be -\begin_inset Formula $N\times N$ -\end_inset - -. - If -\begin_inset Formula $\boldsymbol{\mu}\equiv mean$ -\end_inset - - and -\begin_inset Formula $\mathbf{C}=cov$ -\end_inset - -, then the joint-pdf representing the returned random vector(s) is -\begin_inset Formula \[ -f\left(\mathbf{x}\right)=\frac{1}{\sqrt{\left(2\pi\right)^{N}\left|\mathbf{C}\right|}}\exp\left[-\frac{1}{2}\left(\mathbf{x}-\boldsymbol{\mu}\right)^{T}\mathbf{C}^{-1}\left(\mathbf{x}-\boldsymbol{\mu}\right)\right].\] - -\end_inset - - -\end_layout - -\begin_layout Description -noncentral_chisquare ( -\begin_inset Formula $\nu$ -\end_inset - -, -\begin_inset Formula $\lambda$ -\end_inset - -, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This is the distribution of -\begin_inset Formula $\sum_{i=1}^{\nu}\left(Z_{i}+\delta_{i}\right)^{2}$ -\end_inset - - where -\begin_inset Formula $Z_{i}$ -\end_inset - - are independent standard normal random numbers and -\begin_inset Formula $\delta_{i}$ -\end_inset - - are constants. - It is a a generalized Rayleigh-Rice distribution: -\end_layout - -\begin_deeper -\begin_layout Standard -\begin_inset Formula \[ -f\left(x;\nu,\lambda\right)=e^{-\left(\lambda+x\right)/2}\frac{1}{2}\left(\frac{x}{\lambda}\right)^{\left(\nu-2\right)/4}I_{\left(\nu-2\right)/2}\left(\sqrt{\lambda x}\right)I_{\left(0,\infty\right)}\left(x\right),\] - -\end_inset - - where -\begin_inset Formula $I_{\nu}\left(z\right)$ -\end_inset - - (a real-number in the subscript, not an interval) is the modified Bessel - Function of the first kind. - -\end_layout - -\end_deeper -\begin_layout Description -noncentral_f ( -\begin_inset Formula $\nu_{1}$ -\end_inset - -, -\begin_inset Formula $\nu_{2}$ -\end_inset - -, -\begin_inset Formula $\lambda$ -\end_inset - -, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - The pdf of this distribution is -\begin_inset Formula \begin{eqnarray*} -f\left(x;\nu_{1},\nu_{2},\lambda\right) & = & \exp\left[\frac{\lambda}{2}+\frac{\lambda v_{1}x}{2\left(\nu_{1}x+\nu_{2}\right)}\right]\nu_{1}^{\nu_{1}/2}\nu_{2}^{\nu_{2}/2}x^{\nu_{1}/2-1}\\ - & & \times\left(\nu_{2}+\nu_{1}x\right)^{-\left(\nu_{1}+\nu_{2}\right)/2}\\ - & & \times\frac{\Gamma\left(\frac{\nu_{1}}{2}\right)\Gamma\left(1+\frac{\nu_{2}}{2}\right)L_{n_{2}/2}^{n_{1}/2-1}\left(-\frac{\lambda\nu_{1}x}{2\left(\nu_{1}x+\nu_{2}\right)}\right)}{B\left(\frac{\nu_{1}}{2},\frac{\nu_{2}}{2}\right)\Gamma\left(\frac{\nu_{1}+\nu_{2}}{2}\right)}.\end{eqnarray*} - -\end_inset - - -\end_layout - -\begin_layout Description -normal (loc=0.0, scale=1.0, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - The normal, or Gaussian, distribution is the limiting distribution of independe -nt samples from any sufficiently well-behaved distributions (this is the - content of the celebrated central limit theorem). - The normal distribution is also the distribution of maximum entropy when - the mean and variance alone are fixed. - These two facts account for its name as well as the wide variety of situations - that can be usefully modelled using the normal distribution. - Because it is so widely used, the full pdf with the location -\begin_inset Formula $\left(\mu\right)$ -\end_inset - - and scale -\begin_inset Formula $\left(\sigma\right)$ -\end_inset - - parameters is provided: -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -f\left(x\right)=\frac{1}{\sigma\sqrt{2\pi}}\exp\left[-\frac{\left(x-\mu\right)^{2}}{2\sigma^{2}}\right].\] - -\end_inset - - -\end_layout - -\begin_layout Description -pareto ( -\begin_inset Formula $a$ -\end_inset - -, size=None) -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -f\left(x;a\right)=\frac{a}{x^{a+1}}I_{\left[1,\infty\right)}\left(x\right).\] - -\end_inset - - -\end_layout - -\begin_layout Description -power ( -\begin_inset Formula $a$ -\end_inset - -, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - A special case of the beta distribution with -\begin_inset Formula $b=1.$ -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -f\left(x;a\right)=ax^{a-1}I_{\left[0,1\right]}\left(x\right).\] - -\end_inset - - -\end_layout - -\begin_layout Description -rand ( -\begin_inset Formula $d_{1}$ -\end_inset - -, -\begin_inset Formula $d_{2}$ -\end_inset - -, -\begin_inset Formula $\ldots$ -\end_inset - -, -\begin_inset Formula $d_{n}$ -\end_inset - -) -\end_layout - -\begin_layout Description -\InsetSpace ~ - A convenient interface to obtain an array of shape -\begin_inset Formula $\left(d_{1},d_{2},\ldots,d_{n}\right)$ -\end_inset - - of uniform random numbers in the interval -\begin_inset Formula $\left[0,1\right).$ -\end_inset - - Notice the different convention for passing in the shape (as separate arguments - instead of a tuple). - The standard convention is used in the function numpy.random.random(shape) - for which this function is merely a convenient short-hand. - If you have a tuple named shape, then rand(*shape) will work correctly. -\end_layout - -\begin_layout Description -randint (low, high=None, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Equally probably random integers in the range -\begin_inset Formula $low\leq x<high$ -\end_inset - -. - If -\begin_inset Formula $high$ -\end_inset - - is None, then the range is -\begin_inset Formula $0\leq x<low$ -\end_inset - -. - Similar to random_integers, but check the difference on the bounds. -\end_layout - -\begin_layout Description -randn ( -\begin_inset Formula $d_{1}$ -\end_inset - -, -\begin_inset Formula $d_{2}$ -\end_inset - -, -\begin_inset Formula $\ldots$ -\end_inset - -, -\begin_inset Formula $d_{n}$ -\end_inset - -) -\end_layout - -\begin_layout Description -\InsetSpace ~ - A convenient interface to obtain an array of shape -\begin_inset Formula $\left(d_{1},d_{2},\ldots,d_{n}\right)$ -\end_inset - - of standard normal -\begin_inset Formula $\left(\mu=0,\,\sigma=1\right)$ -\end_inset - - random numbers. - Notice the different convention for passing in the shape (as separate arguments - intead of a tuple). - The standard convention is used in the function numpy.random.standard_normal(shap -e) for which this function is merely a convenient short-hand. - If you have a tuple named shape, then randn(*shape) will work correctly. -\end_layout - -\begin_layout Description -random_integers (low, high=None, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Equally probably random integers in the range -\begin_inset Formula $low\leq x\leq high$ -\end_inset - -. - If high is None, then the range is -\begin_inset Formula $1\leq x\leq low$ -\end_inset - -. - Similar to randint, but check the difference on the bounds. -\end_layout - -\begin_layout Description -rayleigh (scale=1.0, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Rayleigh-distributed random numbers can be obtained as -\begin_inset Formula $X=\sqrt{Z_{1}^{2}+Z_{2}^{2}}$ -\end_inset - - where -\begin_inset Formula $Z_{i}$ -\end_inset - - are independent standard normal random numbers. - The scale parameter is also the mode of the distribution (the value of - -\begin_inset Formula $X$ -\end_inset - - with highest probability). - -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -f\left(x\right)=xe^{-x^{2}/2}I_{[0,\infty)}\left(x\right)\] - -\end_inset - - -\end_layout - -\begin_layout Description -standard_cauchy (size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - A Cauchy distribution is a heavy-tailed distribution with no variance. - It's distribution is that of the ratio of two standard normal distributions - -\begin_inset Formula $Z_{1}/Z_{2}.$ -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -f\left(x\right)=\frac{1}{\pi\left(1+x^{2}\right)}.\] - -\end_inset - - -\end_layout - -\begin_layout Description -standard_exponential (size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - A standard exponetial random number with scale=1.0. - The pdf was given under the description of -\family typewriter -random.exponential -\family default -. -\end_layout - -\begin_layout Description -standard_gamma ( -\begin_inset Formula $a$ -\end_inset - -, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - A standard gamma random number with scale=1.0. - The pdf was given under the description of -\family typewriter -random.gamma -\family default -. -\end_layout - -\begin_layout Description -standard_normal (size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - A zero-mean, unit-variance, normally distributed random number often denoted - -\begin_inset Formula $Z.$ -\end_inset - - -\begin_inset Formula \[ -f\left(x\right)=\frac{1}{\sqrt{2\pi}}e^{-x^{2}/2}.\] - -\end_inset - - -\end_layout - -\begin_layout Description -standard_t ( -\begin_inset Formula $\nu$ -\end_inset - -, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Often called Student's t distribution, this random number distribution - arises in the problem of estimating the mean of normally distributed samples - when the sample-size is small. - The first parameter, -\begin_inset Formula $\nu$ -\end_inset - -, is the number of degrees of freedom of the distribution. - -\begin_inset Formula \[ -f\left(x;\nu\right)\frac{\Gamma\left(\frac{\nu+1}{2}\right)}{\sqrt{\pi\nu}\Gamma\left(\frac{\nu}{2}\right)\left[1+\frac{x^{2}}{\nu}\right]^{\frac{\nu+1}{2}}}.\] - -\end_inset - - -\end_layout - -\begin_layout Description -triangular (left, mode, right, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns random numbers according to a triangularly-shaped density that - starts at left, peaks at mode, and ends at right. -\end_layout - -\begin_layout Description -uniform (low=0.0, high=1.0, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns random numbers that are equally probable over the range -\begin_inset Formula $\left[low,\, high\right).$ -\end_inset - - -\end_layout - -\begin_layout Description -vonmises ( -\begin_inset Formula $\mu$ -\end_inset - -, -\begin_inset Formula $\kappa$ -\end_inset - -, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - A continuous distribution that is well suited for circular attributes such - as angles, time of day, day of the year, etc. - The mean direction is -\begin_inset Formula $\mu$ -\end_inset - - and concentration (or dispersion) parameter is -\begin_inset Formula $\kappa.$ -\end_inset - - For small -\begin_inset Formula $\kappa$ -\end_inset - - the distribution tends towards a uniform distribution over -\begin_inset Formula $\left[-\pi,\pi\right].$ -\end_inset - - For large -\begin_inset Formula $\kappa$ -\end_inset - -, the distribution tends towards a normal distribution with mean -\begin_inset Formula $\mu$ -\end_inset - - and variance -\begin_inset Formula $1/\kappa.$ -\end_inset - - -\begin_inset Formula \[ -f\left(x\right)=\frac{e^{\kappa\cos\left(x-\mu\right)}}{2\pi I_{0}\left(\kappa\right)}I_{\left[-\pi,\pi\right]}\left(x\right).\] - -\end_inset - - -\end_layout - -\begin_layout Description -wald ( -\begin_inset Formula $\mu$ -\end_inset - -, -\begin_inset Formula $\lambda$ -\end_inset - -, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - This distribution is also called the inverse Gaussian distribution (and - the Wald distribution considered as a special case when -\begin_inset Formula $\mu=\lambda$ -\end_inset - -). - It can be generated by noticing that if -\begin_inset Formula $X$ -\end_inset - - is a wald random number then -\begin_inset Formula $\frac{\lambda\left(X-\mu\right)^{2}}{\mu^{2}X}$ -\end_inset - - is the square of a standard normal random number (i.e. - it is chi-square with one degree of freedom). - The pdf is -\begin_inset Formula \[ -f\left(x\right)=\sqrt{\frac{\lambda}{2\pi x^{3}}}e^{-\frac{\lambda\left(x-\mu\right)^{2}}{2\mu^{2}x}}.\] - -\end_inset - - -\end_layout - -\begin_layout Description -weibull ( -\begin_inset Formula $a$ -\end_inset - -, size=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - An extreme-value distribution: -\end_layout - -\begin_layout Standard -\begin_inset Formula \[ -f\left(x;c\right)=ax^{a-1}\exp\left(-x^{a}\right)I_{\left(0,\infty\right)}\left(x\right).\] - -\end_inset - - -\end_layout - -\begin_layout Subsection -Miscellaneous utilities -\end_layout - -\begin_layout Description -bytes (length) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a string of random bytes of the provided length. -\end_layout - -\begin_layout Description -get_state () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an object that holds the state of the random number generator (allows - you to restart simulations where you left off). -\end_layout - -\begin_layout Description -set_state (state) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Set the state of the random number generator. - The argument should be the returned object of a previous get_state command. -\end_layout - -\begin_layout Description -shuffle (sequence) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Randomly permute the items of any sequence. - If sequence is an array, then it must be 1-d. -\end_layout - -\begin_layout Description -permutation (n) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a permutation of the integers from 0 to n-1. - -\begin_inset LatexCommand index -name "random!continuous|)" - -\end_inset - - -\begin_inset LatexCommand index -name "random|)" - -\end_inset - - -\end_layout - -\begin_layout Section -Matrix-specific functions (matlib) -\end_layout - -\begin_layout Standard -This module contains functions that are geared specifically toward matrix - objects. - In particular it includes the functions -\series bold -empty -\series default -, -\series bold -ones -\series default -, -\series bold -zeros -\series default -, -\series bold -identity -\series default -, -\series bold -eye -\series default -, -\series bold -rand -\series default -, and -\series bold -randn -\series default - each of which returns a matrix object by default instead of an ndarray - object. -\end_layout - -\begin_layout Section -Ctypes utiltity functions (ctypeslib) -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "ctypeslib" - -\end_inset - -This module contains utility functions that make it easier to work with - the ctypes module. - -\end_layout - -\begin_layout Description -load_library (name, path) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Load a shared library named -\begin_inset Quotes eld -\end_inset - -name -\begin_inset Quotes erd -\end_inset - - (use the full name including any prefix but excluding the extension) located - in the directory indicated by path and return a ctypes library object whose - attributes are the functions in the library. - If ctypes is not available, this function will raise an ImportError. - If there is an error loading the library, ctypes raises an OSError. - The extension is appended to the library name (on a platform-dependent - basis) unless the name includes the -\begin_inset Quotes eld -\end_inset - -. -\begin_inset Quotes erd -\end_inset - - character in which case name is assumed to be the -\begin_inset Quotes eld -\end_inset - -full-name -\begin_inset Quotes erd -\end_inset - - of the library. - -\end_layout - -\begin_layout Description -ndpointer (dtype=None, ndim=None, shape=None, flags=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Create a class object that can be used in the argtypes list of a ctypes - function that will do basic type, number-of-dimensions, shape, and flags - checking on input array objects. - Setting an argtypes entry with the result of this function allows passing - arrays directly to ctypes-wrapped functions. - The returned class object will contain a from_param method as required - by ctypes. - This from_param method takes the array object, does data-type, number-of-dimens -ions, shape, and flags checking on the object and if all tests pass returns - an object that ctypes can use as the data area of the array. - Checking is not performed for any entries which are None in this class - creation function. - -\end_layout - -\begin_layout Chapter -Testing and Packaging -\end_layout - -\begin_layout Quotation -Research is what I'm doing when I don't know what I'm doing. -\end_layout - -\begin_layout Right Address ---- -\emph on -Werner von Braun -\end_layout - -\begin_layout Quotation -The most likely way for the world to be destroyed, most experts agree, is - by accident. - That's where we come in; we're computer professionals. - We cause accidents. -\end_layout - -\begin_layout Right Address ---- -\emph on -Nathaniel Borenstein -\end_layout - -\begin_layout Standard -There are two additional sub-packages distributed with NumPy that simplify - the process of distributing and testing code based on NumPy. - The numpy.distutils sub-package extends the standard distutils package to - handle Fortran code along with providing support for the auto-generated - code in NumPy. - The numpy.testing sub-package defines a few functions and classes for standardiz -ing unit-tests in NumPy. - These facilities can be used in your own packages that build on top of - NumPy. - -\end_layout - -\begin_layout Section -Testing -\end_layout - -\begin_layout Standard -In this sub-package are two classes and some useful utilities for writing - unit-tests -\end_layout - -\begin_layout Description -NumpyTestCase a subclass of unittest.TestCase which adds a measure method - that can determine the elasped time to execute a code string and enhances - the __call__ method -\end_layout - -\begin_layout Description -NumpyTest the test manager for NumPy which was extracted originally from - the SciPy code base. - This test manager makes it easy to add unit-tests to a package simply by - creating a tests sub-directory with files named test_<module>.py. - These test files should then define sub-classes of NumpyTestCase (or unittest.Te -stCase) named -\begin_inset Quotes eld -\end_inset - -test* -\begin_inset Quotes erd -\end_inset - -. - These classes should then define functions named -\begin_inset Quotes eld -\end_inset - -test* -\begin_inset Quotes erd -\end_inset - - or -\begin_inset Quotes eld -\end_inset - -bench* -\begin_inset Quotes erd -\end_inset - - or -\begin_inset Quotes eld -\end_inset - -check* -\begin_inset Quotes erd -\end_inset - - that contain the actual unit-tests. - The first keyword argument should specify the level above which this test - should be run. - -\end_layout - -\begin_layout Description -\InsetSpace ~ - To run the tests excecute NumpyTest(<package>).test(level=1, verbosity=1) - which will run all tests above the given level using the given verbosity. - Here <package> can be either a string or a previously imported module. - You can get the level and verbosity arguments from sys.argv using NumpyTest(<pac -kage>).run() with -v or --verbosity and -l or --level as command-line arguments. -\end_layout - -\begin_layout Description -set_local_path (reldir='', level=1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - prepend local directory (+ reldir) to sys.path. - The caller is responsible for removing this path using restore_path(). -\end_layout - -\begin_layout Description -set_package_path (level=1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - prepend package directory to sys.path. - This should be called from a test_file.py that satisfies the tree structure: - <somepath>/<somedir>/test_file.py. - The, the first existing path name from the list <somepath>/build/lib.<platform>- -<version>, <somepath>/.. - is pre-pended to sys.path. - The caller is responsible for removing this path using restore_path(). -\end_layout - -\begin_layout Description -restore_path () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Remove the first entry from sys.path. -\end_layout - -\begin_layout Description -assert_equal (actual, desired, err_msg='', verbose=1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Raise an assertion error if the two items are not equal. - Automatically calls assert_array_equal if actual or desired is an ndarray. - -\end_layout - -\begin_layout Description -assert_almost_equal (actual, desired, decimal=7, err_msg='', verbose=1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Raise an assertion error if the two items are not equal within decimal - places. - Automatically calls assert_array_almost_equal if actual or desired is an - ndarray. -\end_layout - -\begin_layout Description -assert_approx_equal (actual, desired, significant=7, err_msg='', verbose=1) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Raise an assertion error if the two items are not equal to within the given - significant digits. - Does not work on arrays. - -\end_layout - -\begin_layout Description -assert_array_equal (x, y, err_msg='') -\end_layout - -\begin_layout Description -\InsetSpace ~ - Raise an error if the two arrays x and y are not equal at every element. - -\end_layout - -\begin_layout Description -assert_array_less (x, y, err_msg='') -\end_layout - -\begin_layout Description -\InsetSpace ~ - Raise an error if the two arrays x and y have different shapes or if x - is not less than y at every element. - -\end_layout - -\begin_layout Description -assert_array_almost_equal (x, y, decimal=6, err_msg='') -\end_layout - -\begin_layout Description -\InsetSpace ~ - Raise an error if x and y are not equal to decimal places at every element. -\end_layout - -\begin_layout Description -jiffies () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a number of 1/100ths of a second that this process has been scheduled - in user mode. - Implemented using time.time() unless on Linux where the special /proc directory - filesystem is used. - -\end_layout - -\begin_layout Description -memusage () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the virtual memory size in bytes of the running python. - If the operation is not supported on the platform, then return None. - This works only on linux for now. -\end_layout - -\begin_layout Description -rand (*args) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return an array of random numbers with the given shape using only the standard - library random number generator. -\end_layout - -\begin_layout Description -runstring (astr, dict) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Run the given string in the dictionary provided. - Functional form for (exec astr in dict) that is useful for the failUnlessRaises - method of unittest.TestCase class. -\end_layout - -\begin_layout Section -NumPy Distutils -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "distutils" - -\end_inset - -NumPy provides enhanced distutils functionality to make it easier to build - and install sub-packages, auto-generate code, and extension modules that - use Fortran-compiled libraries. - To use features of numpy distutils use the setup command from numpy.distutils.cor -e. - A useful Configuration class is also provided in numpy.distutils.misc_util - that can make it easier to construct keyword arguments to pass to the setup - function (by passing the dictionary obtained from the todict() method of - the class). - More information is available in the NumPy Distutils Users Guide in <site-packa -ges>/numpy/doc/DISTUTILS.txt. -\end_layout - -\begin_layout Subsection -misc_util -\end_layout - -\begin_layout Description -Configuration (package_name=None, parent_name=None, top_path=None, package_path= -None, **attrs) -\end_layout - -\begin_layout Description -\InsetSpace ~ - -\begin_inset LatexCommand index -name "Configuration" - -\end_inset - -Construct a configuration instance for the given package name. - If parent_name is not None, then construct the package as a sub-package - of the parent_name package. - If top_path and package_path are None then they are assumed equal to the - path of the file this instance was created in. - The setup.py files in the numpy distribution are good examples of how to - use the Configuration instance. -\end_layout - -\begin_deeper -\begin_layout Description -self.todict () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a dictionary compatible with the keyword arguments of distutils - setup function. - Thus, this method may be used as setup(**config.todict()). -\end_layout - -\begin_layout Description -self.get_distribution () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the distutils distribution object for self. -\end_layout - -\begin_layout Description -self.get_subpackage (subpackage_name, subpackage_path=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a Configuration instance for the sub-package given. - If subpackage_path is None then the path is assumed to be the local path - plus the subpackage_name. - If a setup.py file is not found in the subpackage_path, then a default configura -tion is used. -\end_layout - -\begin_layout Description -self.add_subpackage (subpackage_name, subpackage_path=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Add a sub-package to the current Configuration instance. - This is useful in a setup.py script for adding sub-packages to a package. - The sub-package is contained in subpackage_path / subpackage_name and this - directory may contain a setup.py script or else a default setup (suitable - for Python-code-only subpackages) is assumed. - If the subpackage_path is None, then it is assumed to be located in the - local path / subpackage_name. - -\end_layout - -\begin_layout Description -self.add_data_files (*files) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Add files to the list of data_files to be included with the package. - The form of each element of the files sequence is very flexible allowing - many combinations of where to get the files from the package and where - they should ultimately be installed on the system. - The most basic usage is for an element of the files argument sequence to - be a simple filename. - This will cause that file from the local path to be installed to the installati -on path of the self.name package (package path). - The file argument can also be a relative path in which case the entire - relative path will be installed into the package directory. - Finally, the file can be an absolute path name in which case the file will - be found at the absolute path name but installed to the package path. -\end_layout - -\begin_layout Description -\InsetSpace ~ - This basic behavior can be augmented by passing a 2-tuple in as the file - argument. - The first element of the tuple should specify the relative path (under - the package install directory) where the remaining sequence of files should - be installed to (it has nothing to do with the file-names in the source - distribution). - The second element of the tuple is the sequence of files that should be - installed. - The files in this sequence can be filenames, relative paths, or absolute - paths. - For absolute paths the file will be installed in the top-level package - installation directory (regardless of the first argument). - Filenames and relative path names will be installed in the package install - directory under the path name given as the first element of the tuple. - An example may clarify: -\end_layout - -\begin_deeper -\begin_layout LyX-Code -self.add_data_files('foo.dat', -\newline -('fun', ['gun.dat', 'nun/pun.dat', '/tmp/sun.dat']), - -\newline -'bar/cat.dat', -\newline -'/full/path/to/can.dat') -\end_layout - -\begin_layout Standard -will install these data files to: -\end_layout - -\begin_layout LyX-Code -<package install directory>/ -\newline - foo.dat -\newline - fun/ -\newline - gun.dat -\newline - nun/ -\newline - pun.dat -\newline - sun.dat -\newline - - bar/ -\newline - car.dat -\newline - can.dat -\end_layout - -\begin_layout Standard -where <package install directory> is the package (or sub-package) directory - such as '/usr/lib/python2.4/site-packages/mypackage' ('C: -\backslash - -\backslash -Python2.4 -\backslash - -\backslash -Lib -\backslash - -\backslash -site-packages -\backslash - -\backslash -mypackage') or '/usr/lib/python2.4/site-packages/mypackage/mysubpackage' - ('C: -\backslash - -\backslash -Python2.4 -\backslash - -\backslash -Lib -\backslash - -\backslash -site-packages -\backslash - -\backslash -mypackage -\backslash - -\backslash -mysubpackage'). -\end_layout - -\end_deeper -\begin_layout Standard -\InsetSpace ~ - An additional feature is that the path to a data-file can actually be a - function that takes no arguments and returns the actual path(s) to the - data-files. - This is useful when the data files are generated while building the package. - -\end_layout - -\begin_layout Description -self.add_data_dir (data_path) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Recursively add files under data_path to the list of data_files to be installed - (and distributed). - The data_path can be either a relative path-name, or an absolute path-name, - or a 2-tuple where the first argument shows where in the install directory - the data directory should be installed to. - For example suppose the source directory contains fun/foo.dat and fun/bar/car.dat -\end_layout - -\begin_layout LyX-Code -self.add_data_dir('fun') -\newline -self.add_data_dir(('sun', 'fun')) -\newline -self.add_data_dir(('gun', - '/full/path/to/fun')) -\end_layout - -\begin_layout Standard -\InsetSpace ~ - Will install data-files to the locations -\end_layout - -\begin_layout LyX-Code -<package install directory>/ -\newline - fun/ -\newline - foo.dat -\newline - bar/ -\newline - car.dat -\newline - sun/ -\newline - - foo.dat -\newline - bar/ -\newline - car.dat -\newline - gun/ -\newline - foo.dat -\newline - car.dat -\end_layout - -\begin_layout Description -self.add_include_dirs (*paths) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Add the given sequence of paths to the beginning of the include_dirs list. - This list will be visible to all extension modules of the current package. -\end_layout - -\begin_layout Description -self.add_headers (*files) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Add the given sequence of files to the beginning of the headers list. - By default, headers will be installed under <python-include>/<self.name.replace('. -','/')>/ directory. - If an item of files is a tuple, then its first argument specifies the actual - installation location relative to the <python-include> path. -\end_layout - -\begin_layout Description -self.add_extension (name, sources, **kw) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Create and add an Extension instance to the ext_modules list. - The first argument defines the name of the extension module that will be - installed under the self.name package. - The second argument is a list of sources. - This method also takes the following optional keyword arguments that are - passed on to the Extension constructor: include_dirs, define_macros, undef_macr -os, library_dirs, libraries, runtime_library_dirs, extra_objects, swig_opts, - depends, language, f2py_options, module_dirs, and extra_info. - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The self.paths(...) method is applied to all lists that may contain paths. - The extra_info is a dictionary or a list of dictionaries whose content - will be appended to the keyword arguments. - The depends list contains paths to files or directories that the sources - of the extension module depend on. - If any path in the depends list is newer than the extension module, then - the module will be rebuilt. - -\end_layout - -\begin_layout Description -\InsetSpace ~ - The list of sources may contain functions (called source generators) which - must take an extension instance and a build directory as inputs and return - a source file or list of source files or None. - If None is returned then no sources are generated. - If the Extension instance has no sources after processing all source generators -, then no extension module is built. - -\end_layout - -\begin_layout Description -self.add_library (name, sources, **build_info) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Add a library to the list of libraries. - Allowed keyword arguments are depends, macros, include_dirs, extra_compiler_arg -s, and f2py_options. - The name is the name of the library to be built and sources is a list of - sources (or source generating functions) to add to the library. -\end_layout - -\begin_layout Description -self.add_scripts (*files) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Add the sequence of files to the beginning of the scripts list. - Scripts will be installed under the <prefix>/bin/ directory. - -\end_layout - -\begin_layout Description -self.paths (*paths) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Applies glob.glob(...) to each path in the sequence (if needed) and pre-pends - the local_path if needed. - Because this is called on all source lists, this allows wildcard characters - to be specified in lists of sources for extension modules and libraries - and scripts and allows path-names be relative to the source directory. -\end_layout - -\begin_layout Description -self.get_config_cmd () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns the numpy.distutils config command instance. -\end_layout - -\begin_layout Description -self.get_build_temp_dir () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a path to a temporary directory where temporary files should be - placed. -\end_layout - -\begin_layout Description -self.have_f77c () -\end_layout - -\begin_layout Description -\InsetSpace ~ - True if a Fortran 77 compiler is available (because a simple Fortran 77 - code was able to be compiled successfully). -\end_layout - -\begin_layout Description -self.have_f90c () -\end_layout - -\begin_layout Description -\InsetSpace ~ - True if a Fortran 90 compiler is available (because a simple Fortran 90 - code was able to be compiled successfully) -\end_layout - -\begin_layout Description -self.get_version () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a version string of the current package or None if the version informati -on could not be detected. - This method scans files named __version__.py, <packagename>_version.py, version.py -, and __svn_version__.py for string variables version, __version__, and <packagen -ame>_version, until a version number is found. -\end_layout - -\begin_layout Description -self.make_svn_version_py () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Appends a data function to the data_files list that will generate __svn_version -__.py file to the current package directory. - This file will be removed from the source directory when Python exits (so - that it can be re-generated next time the package is built). - This is intended for working with source directories that are in an SVN - repository. - -\end_layout - -\begin_layout Description -self.make_config_py () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Generate a package __config__.py file containing system information used - during the building of the package. - This file is installed to the package installation directory. -\end_layout - -\begin_layout Description -self.get_info (*names) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return information (from system_info.get_info) for all of the names in the - argument list in a single dictionary. - -\end_layout - -\end_deeper -\begin_layout Description -get_numpy_include_dirs () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the include directory where the numpy/arrayobject.h and numpy/ufuncobject. -h files are found. - This should be added to the include_dirs of any extension module built - using NumPy. - If numpy.distutils is used to build the extension, then this directory is - added automatically. - -\end_layout - -\begin_layout Description -get_numarray_include_dirs () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the include directory where the numpy/libnumarray.h file is found. - This should be added to the include_dirs of any extension module that relies - on the Numarray-compatible C-API. - -\end_layout - -\begin_layout Description -dict_append (d, **kwds) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Add the keyword arguments given as entries in the dictionary provided as - the first argument. - If the entry is already present, then assume it is a list and extend the - list with the keyword value. -\end_layout - -\begin_layout Description -appendpath (prefix, path) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Platform-independent intelligence for appending path to prefix. - It replaces '/' in the prefix and the path with the correct path-separator - on the platform ad returns a full path name that will be valid for the - platform. - -\end_layout - -\begin_layout Description -allpath (name) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Convert a '/' separated pathname to one using the platform's path separator. -\end_layout - -\begin_layout Description -dot_join (*args) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Converts a sequence of string arguments to a string joined by '.' (removing - any empty strings). - -\end_layout - -\begin_layout Description -generate_config_py (extension, build_dir) -\end_layout - -\begin_layout Description -\InsetSpace ~ - A suitable function that can be used in a source list. - This constructs a python file that contains system_info information used - during building the package. - Generally easier to use a Configuration instance and the config.make_config_py() - method. -\end_layout - -\begin_layout Description -get_cmd (cmdname, _cache={}) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns an instance of the distutils command object named cmdname if the - setup distribution instance has been initialized. - Caches the result in _cache[cmdname] and gets it from there if present. -\end_layout - -\begin_layout Description -terminal_has_colors () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Tries to determine if the stdout terminal can be written to using ANSI - colors. - Returns 1 if it can be determined that ANSI colors are acceptable or 0 - if not. - -\end_layout - -\begin_layout Description -red_text (s) -\end_layout - -\begin_layout Description -green_text (s) -\end_layout - -\begin_layout Description -yellow_text (s) -\end_layout - -\begin_layout Description -blue_text (s) -\end_layout - -\begin_layout Description -cyan_text (s) -\end_layout - -\begin_layout Description -\InsetSpace ~ - If terminal_has_colors() is true, then these commands return a string with - the necessary codes prepended to display the given string argument in the - specified color on an ANSI terminal. - If terminal_has_colors() is false, then these functions simply return the - input argument. - -\end_layout - -\begin_layout Description -cyg2win32 (path) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Convert a cygwin path beginning with /cygdrive to a standard win32 path - name. - -\end_layout - -\begin_layout Description -all_strings (lst) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return True if all items in the input list are string objects otherwise - return False. -\end_layout - -\begin_layout Description -has_f_sources (sources) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return True if any of the source files listed in the input argument are - Fortran files because its name matches against the compiled regular expression - -\series bold -fortran_ext_match -\series default -. -\end_layout - -\begin_layout Description -has_cxx_sources (sources) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return True if any of the source files listed in the input argument are - C++ files because its name matches against the compiled regular expression - -\series bold -cxx_ext_match -\series default -. -\end_layout - -\begin_layout Description -filter_sources (sources) -\end_layout - -\begin_layout Description -\InsetSpace ~ - From the provided list of sources, return four lists of filenames containing - C, C++, Fortran, and Fortran 90 module sources respectively. - The compiled regular expressions used in this search (which are also available - in the misc_util module) are cxx_ext_match, fortran_ext_match, f90_ext_match, - and f90_module_name_match. - -\end_layout - -\begin_layout Description -get_dependencies (sources) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Scan the files in the sources list for include statements. -\end_layout - -\begin_layout Description -is_local_src_dir (directory) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return True if the provided directory is the local current working directory. - -\end_layout - -\begin_layout Description -get_ext_source_files (ext) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Get sources and any include files in the same directory from an Extension - instance. -\end_layout - -\begin_layout Description -get_script_files (scripts) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Returns the list scripts with all non-string arguments removed. -\end_layout - -\begin_layout Subsection -Other modules -\end_layout - -\begin_layout Description -system_info.get_info (name) -\end_layout - -\begin_layout Description -\InsetSpace ~ - For the given string representing a particular resource, return a dictionary - that is compatible with the distutils.setup keyword arguments. - If this is an empty dictionary, then the requested resource is not available. - Some of the names that can be checked are 'lapack_opt', 'blas_opt', 'fft_opt', - 'fftw', 'fftw3', 'fftw2', 'djbfft', 'numpy', 'numarray', 'boost_python', - 'agg2', 'wx', 'gdk', 'xft', 'freetype2'. - -\end_layout - -\begin_layout Description -system_info.get_standard_file (filename) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return a list of length 0 to 3 containing the full-path filenames for the - filename provided. - The filename is searched for in three places in the following order 1) - the system-wide location which is the directory that the system_info file - is located in; 2) the directory specified by the environment variable HOME; - and 3) the current local directory. - -\end_layout - -\begin_layout Description -cpuinfo.cpu an instance of a cpuinfo class that defines methods for checking - various aspects of the cpu. - The info attribute is a list of length (# of CPUs). - Each entry is a dictionary providing technical information about that CPU. - -\end_layout - -\begin_layout Description -log.set_verbosity (level) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Set the distutils logging threshold and return the previously stored value. - The level is an integer that corresponds to distutils.log thresholds: -1 - <--> ERROR, 0 <--> WARN, 1 <--> INFO, and 2 <--> DEBUG. - -\end_layout - -\begin_layout Description -exec_command -\end_layout - -\begin_deeper -\begin_layout Description -exec_command (command, execute_in='', use_shell=None, use_tee=None, _with_python -=1, **env) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return (status, output) of the executed command. - The command input is a string of executable and arguments. - The output contains both stderr and stdout messages. - If execute_in is given, then change to the provided directory prior to - executing the command and afterwords restore to the current directory. - On NT, and DOS systems the returned status is correct for external commands. - However, wild cards will not work for non-posix systems. -\end_layout - -\begin_layout Description -splitcmdline (line) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Inverse of ' '.join(sys.argv) -\end_layout - -\begin_layout Description -find_executable (exe, path=None) -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return full path of an executable using information from the PATH environment - variable. - Equivalent to the POSIX 'which' command. -\end_layout - -\begin_layout Description -get_pythonexe () -\end_layout - -\begin_layout Description -\InsetSpace ~ - Return the full path to the python executable with some fixes for nt and - dos to replace pythonw with python if it is encountered. - A basic wrapper around sys.executable. -\end_layout - -\end_deeper -\begin_layout Section -Conversion of .src files -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand index -name "code generation" - -\end_inset - -NumPy distutils supports automatic conversion of source files named <somefile>.sr -c. - This facility can be used to maintain very similar code blocks requiring - only simple changes between blocks. - During the build phase of setup, if a template file named <somefile>.src - is encountered, a new file named <somefile> is constructed from the template - and placed in the build directory to be used instead. - Two forms of template conversion are supported. - The first form occurs for files named named <file>.ext.src where ext is a - recognized Fortran extension (f, f90, f95, f77, for, ftn, pyf). - The second form is used for all other cases. - -\end_layout - -\begin_layout Subsection -Fortran files -\end_layout - -\begin_layout Standard -This template converter will replicate all -\series bold -function -\series default - and -\series bold -subroutine -\series default - blocks in the file with names that contain '<...>' according to the rules - in '<...>'. - The number of comma-separated words in '<...>' determines the number of times - the block is repeated. - What these words are indicates what that repeat rule, '<...>', should be replaced - with in each block. - All of the repeat rules in a block must contain the same number of comma-separa -ted words indicating the number of times that block should be repeated. - If the word in the repeat rule needs a comma, leftarrow, or rightarrow, - then prepend it with a backslash ' -\backslash -'. - If a word in the repeat rule matches ' -\backslash - -\backslash -<index>' then it will be replaced with the <index>-th word in the same repeat - specification. - There are two forms for the repeat rule: named and short. -\end_layout - -\begin_layout Subsubsection -Named repeat rule -\end_layout - -\begin_layout Standard -A named repeat rule is useful when the same set of repeats must be used - several times in a block. - It is specified using <rule1=item1, item2, item3,..., itemN>, where N is the - number of times the block should be repeated. - On each repeat of the block, the entire expression, '<...>' will be replaced - first with item1, and then with item2, and so forth until N repeats are - accomplished. - Once a named repeat specification has been introduced, the same repeat - rule may be used -\series bold -in the current block -\series default - by referring only to the name (i.e. - <rule1>. - -\end_layout - -\begin_layout Subsubsection -Short repeat rule -\end_layout - -\begin_layout Standard -A short repeat rule looks like <item1, item2, item3, ..., itemN>. - The rule specifies that the entire expression, '<...>' should be replaced - first with item1, and then with item2, and so forth until N repeats are - accomplished. - -\end_layout - -\begin_layout Subsubsection -Pre-defined names -\end_layout - -\begin_layout Standard -The following predefined named repeat rules are available: -\end_layout - -\begin_layout Itemize -<prefix=s,d,c,z> -\end_layout - -\begin_layout Itemize -<_c=s,d,c,z> -\end_layout - -\begin_layout Itemize -<_t=real, double precision, complex, double complex> -\end_layout - -\begin_layout Itemize -<ftype=real, double precision, complex, double complex> -\end_layout - -\begin_layout Itemize -<ctype=float, double, complex_float, complex_double> -\end_layout - -\begin_layout Itemize -<ftypereal=float, double precision, -\backslash - -\backslash -0, -\backslash - -\backslash -1> -\end_layout - -\begin_layout Itemize -<ctypereal=float, double, -\backslash - -\backslash -0, -\backslash - -\backslash -1> -\end_layout - -\begin_layout Subsection -Other files -\end_layout - -\begin_layout Standard -Non-Fortran files use a separate syntax for defining template blocks that - should be repeated using a variable expansion similar to the named repeat - rules of the Fortran-specific repeats. - The template rules for these files are: -\end_layout - -\begin_layout Enumerate -\begin_inset Quotes eld -\end_inset - -/**begin repeat -\begin_inset Quotes erd -\end_inset - - on a line by itself marks the beginning of a segment that should be repeated. -\end_layout - -\begin_layout Enumerate -Named variable expansions are defined using #name=item1, item2, item3, ..., - itemN# and placed on successive lines. - These variables are replaced in each repeat block with corresponding word. - All named variables in the same repeat block must define the same number - of words. - -\end_layout - -\begin_layout Enumerate -In specifying the repeat rule for a named variable, item*N is short-hand - for item, item, ..., item repeated N times. - In addition, parenthesis in combination with *N can be used for grouping - several items that should be repeated. - Thus, #name=(item1, item2)*4# is equivalent to #name=item1, item2, item1, - item2, item1, item2, item1, item2# -\end_layout - -\begin_layout Enumerate -\begin_inset Quotes eld -\end_inset - -*/ -\begin_inset Quotes erd -\end_inset - - on a line by itself marks the end of the the variable expansion naming. - The next line is the first line that will be repeated using the named rules. -\end_layout - -\begin_layout Enumerate -Inside the block to be repeated, the variables that should be expanded are - specified as @name@. - -\end_layout - -\begin_layout Enumerate -\begin_inset Quotes eld -\end_inset - -/**end repeat**/ -\begin_inset Quotes erd -\end_inset - - on a line by itself marks the previous line as the last line of the block - to be repeated. - -\end_layout - -\begin_layout Standard -\begin_inset Include \input{capi.lyx} -preview false - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset LatexCommand printindex - -\end_inset - - -\end_layout - -\end_body -\end_document |