11/30/23, 4:23 PM
The NumPy Illustrated Library. Softening the rough edges of NumPy | by Lev Maximov | Better Programming
Open in app
You're reading for free via Lev Maximov's Friend Link. Upgrade to access the best of Medium.
Member-only story
The NumPy Illustrated Library
Softening the rough edges of NumPy
Lev Maximov · Follow
Published in Better Programming
5 min read · May 12
Listen
Share
More
All images by author
Two and a half years ago, I published the “NumPy Illustrated” visual guide,
highlighting certain areas for improvement in NumPy that could be implemented
with little or no effort. Since then, some issues have been addressed (e.g., concat
alias¹ for concatenate), while others have not.
In this article, I present my implementation of the outlined issues.
https://betterprogramming.pub/the-numpy-illustrated-library-7531a7c43ffb
1/13
11/30/23, 4:23 PM
The NumPy Illustrated Library. Softening the rough edges of NumPy | by Lev Maximov | Better Programming
Contents
argmin / argmax
T_
returning a tuple
for transpose
irange ,
sort
the inclusive range
for sorting by column
find , first_above , first_nonzero
search functions
Installation
The installation is pretty straightforward:
pip install numpy-illustrated
To save a few keystrokes, the package itself has a shorter name,
npi :
import npi
argmin/argmax returning a tuple
Instead of returning a tuple with the coordinates of the element in question (the
first encounter of the minimal and maximal value) these two NumPy functions
return a scalar. To convert it to a tuple, you need to write a tedious
np.unravel_index(a.argmin(), a.shape) . With npi ,
There are also nan-safe versions,
npi.nanargmin
https://betterprogramming.pub/the-numpy-illustrated-library-7531a7c43ffb
it is as simple as
and
npi.argmin() .
npi.nanargmax .
2/13
11/30/23, 4:23 PM
The NumPy Illustrated Library. Softening the rough edges of NumPy | by Lev Maximov | Better Programming
T_ for Transpose
I bet everyone was a bit puzzled at first by
np.array([1,2,3]).T == np.array([1,2,3])
The new
T_
function transposes row vectors to column vectors and vice versa:
In 3D and above,
T_
interprets the array as a stack of matrices residing in the last
two indexes (same convention as in
np.matmul )
This contradicts the convention used in
the axes as
(x, y, color) ,
hstack
and swaps the last two dimensions:
and
vstack
in 3D, which interprets
but it should not be a big deal because transposition is
not something you usually apply to images.
sort for Sorting by Column
An extension of the original NumPy sort function that allows sorting by column,
just like
pd.sort_values()
in Pandas (see #14989³). For example, the following code
sorts the rows of the array by the second column resolving the ties using the first
column:
https://betterprogramming.pub/the-numpy-illustrated-library-7531a7c43ffb
3/13
11/30/23, 4:23 PM
The NumPy Illustrated Library. Softening the rough edges of NumPy | by Lev Maximov | Better Programming
Like in Pandas, the optional
ascending
argument allows you to choose between the
ascending and descending order for all columns at once (scalar bool) or each of the
columns in particular (list of bools). For example, the following command sorts the
rows by the first column in ascending order, resolving the ties using the second
column in descending order:
The columns not mentioned in the ‘by’ argument also take part in tie resolution in
the left-to-right order. This also holds true for
by=None
(which is the default).
In 3D and above, the arrays are interpreted as a stack of matrices residing in the last
two dimensions, each sorted independently.
irange, the inclusive range
This function returns an array of equidistant integers that includes both the left and
right ends of the interval (see issues #5808³, #18776⁴, #23443⁵, #23712⁶). For
example, to generate a sequence of numbers from 0 to 1 with a step of 0.1 without
worrying about the effect of the binary representation of decimal fractions, use the
following:
Similarly, to get a sequence from -π to π inclusively with a step of π/4, write:
https://betterprogramming.pub/the-numpy-illustrated-library-7531a7c43ffb
4/13
11/30/23, 4:23 PM
If
The NumPy Illustrated Library. Softening the rough edges of NumPy | by Lev Maximov | Better Programming
stop-start
is not evenly divisible by
step
(=the calculated number of steps
deviates from the nearest integer more than
unless the
raises=False
tol=1e-6 ),
a
ValueError
is raised:
argument is provided, which makes it work just like the
ordinary np.arange in this particular case:
find, first_above, first_nonzero search functions
They serve as the NumPy counterpart of the
index
function for lists (the second
most wanted feature for NumPy since 2010⁷).
These search functions bail out immediately after finding the required value, which
means a 1000x speedup against the usual
np.where
approach for huge arrays. For
better portability, the numpy-illustrated library only contains the unoptimized
pure-python version (using
a separate library called
np.where ). The
ndfind
actual cython-optimized code resides in
(installed with
pip install ndfind) . The
are provided for Python 3.8–3.11 on Windows, Linux, and MacOS. Once
installed, calling the three functions from
from
npi
binaries
ndfind
is
executes the accelerated versions
ndfind .
https://betterprogramming.pub/the-numpy-illustrated-library-7531a7c43ffb
5/13
11/30/23, 4:23 PM
The NumPy Illustrated Library. Softening the rough edges of NumPy | by Lev Maximov | Better Programming
If either the array or the value to be found is of floating type,
find
floating comparison mode so that
npi.find([0.1+0.2], 0.3) == 0
absolute tolerances are just like in
np.isclose ).
If the array is sorted,
the
sorted=True
find
and
first_above
switches to the
(the relative and
can be made even faster by providing
argument, which enables the binary search mode (via
np.searchsorted ).
Conclusion
The new open-source MIT-licensed library provides functions that help overcome
some long-standing inconveniences of NumPy.
All functions have been thoroughly tested on Python 3.8–3.11 under Windows,
Linux, and Mac OS.
More detailed documentation can be found on the project page on GitHub.
Let me know if the library proved useful to you, if you have run into any problems
using it, or if you have an idea of a function or method worth including here.
References
1. alias of
np.concatenate
added as
np.concat
(PR #23454, issue #16469)
2. ENH: Reverse param in ordering functions #14989
3.
numpy.arange
4. Numpy
stop precision issue #5808
arange
5. BUG:
arange
6. ENH:
intrange
returns right-border-inclusive array #18776
problem with float #23443
for inclusive integer intervals, #23712
7. first nonzero element (Trac #1673) #2269
Python
Numpy
Data Science
AI
https://betterprogramming.pub/the-numpy-illustrated-library-7531a7c43ffb
Python Programming
6/13
11/30/23, 4:23 PM
The NumPy Illustrated Library. Softening the rough edges of NumPy | by Lev Maximov | Better Programming
Follow
Written by Lev Maximov
1.3K Followers · Writer for Better Programming
Thrilled about programming
More from Lev Maximov and Better Programming
Lev Maximov in Towards Data Science
Broadcasting in NumPy
Broadcasting is an operation of matching the dimensions of differently shaped arrays in order
to be able to perform further operations on…
· 4 min read · Jan 2, 2021
72
https://betterprogramming.pub/the-numpy-illustrated-library-7531a7c43ffb
7/13
11/30/23, 4:23 PM
The NumPy Illustrated Library. Softening the rough edges of NumPy | by Lev Maximov | Better Programming
Sanil Khurana in Better Programming
System Design Series: ElasticSearch, Architecting for search
Understanding Elasticsearch architecture and full-text search
10 min read · Oct 25
514
6
Christine van Wyk in Better Programming
How to Be a Better Leader by Communicating More Assertively
Communication tips for empathetic people
6 min read · Jun 29
https://betterprogramming.pub/the-numpy-illustrated-library-7531a7c43ffb
8/13
11/30/23, 4:23 PM
2K
The NumPy Illustrated Library. Softening the rough edges of NumPy | by Lev Maximov | Better Programming
25
Lev Maximov in Better Programming
How to Build Countable Classes in Python
Or how to make ‘hashable’ objects that can act as keys in dicts
· 4 min read · Apr 18, 2022
163
See all from Lev Maximov
See all from Better Programming
Recommended from Medium
https://betterprogramming.pub/the-numpy-illustrated-library-7531a7c43ffb
9/13
11/30/23, 4:23 PM
The NumPy Illustrated Library. Softening the rough edges of NumPy | by Lev Maximov | Better Programming
Ayush Thakur
Wait! What are Pipelines in Python?
If you are a Python developer, you might have heard of the term pipeline. But what exactly is a
pipeline and why is it useful? In this blog…
5 min read · Nov 6
627
13
Hiroaki Kubo
Building a Multi Layer Perceptron from Scratch
https://betterprogramming.pub/the-numpy-illustrated-library-7531a7c43ffb
10/13
11/30/23, 4:23 PM
The NumPy Illustrated Library. Softening the rough edges of NumPy | by Lev Maximov | Better Programming
I will share the code and description of how I built a multi-layer perceptron from scratch. The
5 min read · Aug 20
90
Lists
Predictive Modeling w/ Python
20 stories · 647 saves
Coding & Development
11 stories · 291 saves
New_Reading_List
174 stories · 209 saves
Practical Guides to Machine Learning
10 stories · 727 saves
Everton Gomede, PhD
The Fourier Transform and its Application in Machine Learning
Introduction
5 min read · Nov 3
https://betterprogramming.pub/the-numpy-illustrated-library-7531a7c43ffb
11/13
11/30/23, 4:23 PM
324
The NumPy Illustrated Library. Softening the rough edges of NumPy | by Lev Maximov | Better Programming
2
Varun Singh
10 Python Tricks — You must know in 2023
2023 is already here and not knowing these Python tricks is not going to make it easy for any
Python Developer. I learned things the hard…
3 min read · Oct 6
300
3
https://betterprogramming.pub/the-numpy-illustrated-library-7531a7c43ffb
12/13
11/30/23, 4:23 PM
The NumPy Illustrated Library. Softening the rough edges of NumPy | by Lev Maximov | Better Programming
scinopio
From Vectors to Tensors
The dynamics of many complex systems frequented in Engineering and Physics can be
formulated elegantly in terms of Vectors and Tensors.
8 min read · Nov 12
155
2
Benjamin Lee in Towards Data Science
The New Best Python Package for Visualising Network Graphs
A guide on who should use it, when to use it, how to use it, and why I was wrong before…
· 10 min read · 6 days ago
651
8
See more recommendations
https://betterprogramming.pub/the-numpy-illustrated-library-7531a7c43ffb
13/13