numpy-illustrated
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:
findfirst_abovefirst_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:
argminargmaxnanargminnanargmax
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.