Skip to main content

numpy-illustrated

pypi python pytest Coverage Badge Code style: black License

This repo contains code for a number of helper functions mentioned in the NumPy Illustrated guide.

Installation:

pip install numpy-illustrated

Supports Python 3.7 and newer with a compatible NumPy release, including NumPy 1.x and 2.x. CI tests NumPy 1.26.4 explicitly and the latest stable NumPy on Python 3.12–3.14.

For maintainers, see Publishing releases.

Contents

Three search functions that return immediately after finding the requested value resulting in a 1000x and more speedup for huge arrays:

  • find
  • first_above
  • first_nonzero

For better portability, in this library only the pure python/numpy implementation is provided (no speedup). The actual cython accelerated code is packaged separately in a library called ndfind. If this library is installed with pip install ndfind (binaries are provided for python 3.8 .. 3.11 under Windows, Linux and MacOS), the faster versions of the functions are used when calling npi.find, etc.

If either the array or the value to be found is of floating type, the floating point comparison with relative and absolute tolerances is used.

The next four functions act just like np.argmin, np.argmax, etc., but return a tuple rather than a scalar in 2D and above:

  • argmin
  • argmax
  • nanargmin
  • nanargmax

Alternative transpose function that converts 1D (row) vector into 2D column vector and back again:

  • T_(a)

Sort function that is able to sort by selected column(s) in ascending/descending order (like sort_values in Pandas):

  • sort

An inclusive range:

  • irange

An alias to concatenate:

  • concat

Documentation

  • find(a, v, rtol=1e-05, atol=1e-08, sorted=False, default=-1, raises=False)

Returns the index of the first element in a equal to v. If either a or v (or both) is of floating type, the parameters atol (absolute tolerance) and rtol (relative tolerance) are used for comparison (see np.isclose() for details).

Otherwise, returns the default value (-1 by default) or raises a ValueError if raises=True.

In 2D and above the the values in a are always tested and returned in row-major, C-style order.

For example,

    >>> find([3, 1, 4, 1, 5], 4)
    2
    >>> find([1, 2, 3], 7)
    -1
    >>> find([1.1, 1.2, 1.3], 1.2)
    1
    >>> find(np.arange(0, 1, 0.1), 0.3) 
    3
    >>> find([[3, 8, 4], [5, 2, 7]], 7)
    (1, 2)
    >>> find([[3, 8, 4], [5, 2, 7]], 9)
    -1
    >>> find([999980., 999990., 1e6], 1e6)
    1
    >>> find([999980., 999990., 1e6], 1e6, rtol=1e-9)
    2
  • first_above(a, v, sorted=False, missing=-1, raises=False)

Returns the index of the first element in a strictly greater than v. If either a or v (or both) is of floating type, the parameters atol (absolute tolerance) and rtol (relative tolerance) are used for comparison (see np.isclose() for details).

In 2D and above the the values in a are always tested and returned in row-major, C-style order.

If there is no value in a greater than v, returns the default value (-1 by default) or raises a ValueError if raises=True.

Parameters:
a : 1-D array_like
v : scalar sorted : use bisection to further accelerate the search. Only works for sorted arrays. missing : the value to return if no element in a is greater than v raises : if True return an exception instead of returning anything

For example,

    >>> first_above([4, 5, 8, 2, 7], 6)
    2 
    >>> first_above([[4, 5, 8], [2, 7, 3]], 6)
    (0, 2) 
    >>> first_above([5, 6, 7], 9)
    3 
  • first_nonzero(a, missing=-1, raises=False)

Returns the index of the first nonzero element in a.

In 2D and above the the values in a are always tested and returned in row-major, C-style order.

For example,

    >>> first_nonzero([0, 0, 7, 0, 5])
    2
    >>> first_nonzero([False, True, False, False, True])
    1
    >>> first_nonzero([[0, 0, 0, 0], [0, 0, 5, 3]])
    (1, 2)
  • argmin(a)

Returns the index of the minimum value. The result is scalar in 1D case and tuple of indices in 2D and above. If the maximum is encountered several times, returns the first match in the C order (irrespectively of the order of the array itself). E.g.:

    >>> argmin([4, 3, 5])
    1
    >>> argmin([[4, 8, 5], [9, 3, 1]])
    (1, 2)
  • argmax(a)

Returns the index of the maximum value. The result is scalar in 1D case and tuple of indices in 2D and above. If the maximum is encountered several times, returns the first match in the C order (irrespectively of the order of the array itself). E.g.:

    >>> argmax([4, 5, 3])
    1
    >>> argmax([[4, 3, 5], [5, 4, 3]])
    (0, 2)
  • nanargmin(a)

Returns the index of the minimum value. The result is scalar in 1D case and tuple of indices in 2D and above. If the maximum is encountered several times, returns the first match in the C order (irrespectively of the order of the array itself). E.g.:

    >>> nanargmin([4, 3, nan])
    1
    >>> nanargmin([[4, 8, 5], [9, 3, 1]])
    (1, 2)
  • nanargmax(a)

Returns the index of the maximum value. The result is scalar in 1D case and tuple of indices in 2D and above. If the maximum is encountered several times, returns the first match in the C order (irrespectively of the order of the array itself). E.g.:

    >>> nanargmax([nan,5,3])
    1
    >>> nanargmax([[4,3,5], [5,nan,3]])
    (0, 2)
  • T_(x)

Returns a view of the array with axes transposed:

  • transposes a matrix just like the original T;
  • transposes 1D array to a 2D column-vector and vica versa;
  • transposes (a less commonly used) 2D row-vector to a 2D column-vector;
  • for 3D arrays and above swaps the last two dimensions. E.g.:
    >>> T_(np.array([[1, 2], [3, 4]]))
    array([[1, 3],
           [2, 4]])
    >>> T_(np.array([1, 2, 3]))
    array([[1],
           [2],
           [3]])
    >>> T_(np.array([[1],
                     [2],
                     [3]])
    array([1, 2, 3])
    >>> T_(np.array([[1, 2, 3]]))
    array([[1],
           [2],
           [3]])
  • sort(a, by=None, axis=0, ascending=True)

Rearranges the rows so that the result is sorted by the specified columns An extension of sort that allows sorting by column(s), ascending and descending.

If by is a list [c1, c2, ..., cn], sorts by the column c1, resolving the ties using the column c2, and so on until cn (just like in pandas). Unlike pandas, the columns not present in the by argument are used for resolving the remaining ties in the left to right order.

by=None is the same as by=[0, 1, 2, ..., a.shape[-1]]

ascending can be either be a scalar or a list.

For example:

    >>>  sort([[1, 2, 3],
               [3, 1, 5],
               [1, 0, 6]])
    array([[1, 0, 6],
           [1, 2, 3],
           [3, 1, 5]])
  • irange(start, stop, step=1, dtype=None, tol=1e-6)

Returns an evenly spaced array from start to stop inclusively. If the range stop-start is not evenly divisible by step (=if the calculated number of steps is further from the nearest integer than tol), raises a ValueError exception.

  • concat

Just a shorter alias to np.concatenate

Testing

Run pytest in the project root.

Metadata

Release files for numpy-illustrated 0.3.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for numpy-illustrated 0.3.2
File Size Uploaded Provenance Actions
numpy_illustrated-0.3.2.tar.gz 12.9 kB With provenance Details for numpy_illustrated-0.3.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for numpy-illustrated 0.3.2
File Interpreter ABI Platform Actions
numpy_illustrated-0.3.2-py3-none-any.whl Python 3 none any Details for numpy_illustrated-0.3.2-py3-none-any.whl

Total release size: 22.1 kB

Release files / numpy_illustrated-0.3.2.tar.gz

Download URL numpy_illustrated-0.3.2.tar.gz
Size 12.9 kB
Tags Source
SHA-256 checksum
How to use checksums
4f1a48654cef460d9ff16fa8e195b0512e9f113c44c4a07afe337eb73a7c8a59
BLAKE2b-256 checksum
How to use checksums
d11cb3b34f18e4caaf532b5979943ae5c5ace2e3ebee85ccafd5ece3d4dbea6e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.

Transparency log

Release files / numpy_illustrated-0.3.2-py3-none-any.whl

Download URL numpy_illustrated-0.3.2-py3-none-any.whl
Size 9.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
885ec460cfbcdf462e41ab9f80690be41d64eb63aee31dfb9d6ef704f8c8ef31
BLAKE2b-256 checksum
How to use checksums
94820f84444a0c3fb618489bc77fd8f2128f5a100ef523e7b9f345873e1d1e0c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.

Transparency log

Security for numpy-illustrated 0.3.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for numpy_illustrated-0.3.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page