NumPy docstrings

NumPy docstrings#

This page demonstrates NumPy docstrings for the theme, as well as some other common Sphinx directives for API documentation.

Added in version 0.1.1.

NumPy#

Provides

  1. An array object of arbitrary homogeneous items

  2. Fast mathematical operations over arrays

  3. Linear Algebra, Fourier Transforms, Random Number Generation

How to use the documentation#

Documentation is available in two forms: docstrings provided with the code, and a loose standing reference guide, available from the NumPy homepage.

We recommend exploring the docstrings using IPython, an advanced Python shell with TAB-completion and introspection capabilities. See below for further instructions.

The docstring examples assume that numpy has been imported as np:

>>> import numpy as np

Code snippets are indicated by three greater-than signs:

>>> x = 42
>>> x = x + 1

Use the built-in help function to view a function’s docstring:

>>> help(np.sort)
...

For some objects, np.info(obj) may provide additional help. This is particularly true if you see the line “Help on ufunc object:” at the top of the help() page. Ufuncs are implemented in C, not Python, for speed. The native Python help() does not know how to view their help, but our np.info() function does.

Available subpackages#

lib

Basic functions used by several sub-packages.

random

Core Random Tools

linalg

Core Linear Algebra Tools

fft

Core FFT routines

polynomial

Polynomial tools

testing

NumPy testing tools

distutils

Enhancements to distutils with support for Fortran compilers support and more (for Python <= 3.11)

Utilities#

test

Run numpy unittests

show_config

Show numpy build configuration

__version__

NumPy version string

Viewing documentation using IPython#

Start IPython and import numpy usually under the alias np: import numpy as np. Then, directly past or use the %cpaste magic to paste examples into the shell. To see which functions are available in numpy, type np.<TAB> (where <TAB> refers to the TAB key), or use np.*cos*?<ENTER> (where <ENTER> refers to the ENTER key) to narrow down the list. To view the docstring for a function, use np.cos?<ENTER> (to view the docstring) and np.cos??<ENTER> (to view the source code).

Copies vs. in-place operation#

Most of the functions in numpy return a copy of the array argument (e.g., np.sort). In-place versions of these functions are often available as array methods, i.e. x = np.array([1,2,3]); x.sort(). Exceptions to this rule are documented.

numpy.transpose(a, axes=None)#

Returns an array with axes transposed.

For a 1-D array, this returns an unchanged view of the original array, as a transposed vector is simply the same vector. To convert a 1-D array into a 2-D column vector, an additional dimension must be added, e.g., np.atleast_2d(a).T achieves this, as does a[:, np.newaxis]. For a 2-D array, this is the standard matrix transpose. For an n-D array, if axes are given, their order indicates how the axes are permuted (see Examples). If axes are not provided, then transpose(a).shape == a.shape[::-1].

Parameters:
aarray_like

Input array.

axestuple or list of ints, optional

If specified, it must be a tuple or list which contains a permutation of [0, 1, …, N-1] where N is the number of axes of a. Negative indices can also be used to specify axes. The i-th axis of the returned array will correspond to the axis numbered axes[i] of the input. If not specified, defaults to range(a.ndim)[::-1], which reverses the order of the axes.

Returns:
pndarray

a with its axes permuted. A view is returned whenever possible.

See also

ndarray.transpose

Equivalent method.

moveaxis

Move axes of an array to new positions.

argsort

Return the indices that would sort an array.

Notes

Use transpose(a, argsort(axes)) to invert the transposition of tensors when using the axes keyword argument.

Examples

>>> import numpy as np
>>> a = np.array([[1, 2], [3, 4]])
>>> a
array([[1, 2],
       [3, 4]])
>>> np.transpose(a)
array([[1, 3],
       [2, 4]])

>>> a = np.array([1, 2, 3, 4])
>>> a
array([1, 2, 3, 4])
>>> np.transpose(a)
array([1, 2, 3, 4])

>>> a = np.ones((1, 2, 3))
>>> np.transpose(a, (1, 0, 2)).shape
(2, 1, 3)

>>> a = np.ones((2, 3, 4, 5))
>>> np.transpose(a).shape
(5, 4, 3, 2)

>>> a = np.arange(3*4*5).reshape((3, 4, 5))
>>> np.transpose(a, (-1, 0, -2)).shape
(5, 3, 4)