How to understand Numpy documentation
By: Kamwoh Ng
Tags: Numpy, Machine Learning, Python

When we start to learn Data Science, Machine Learning, Deep Learning or any excited fields that will be using Python as programming language, most probably all of us will be using numpy as well. In this post, I will be writing numpy basics and how to read documentation properly based on my experience of using numpy. Before reading my post, it is good if you know the basics of programming language and python. I will be using python 3.6 as examples.

What is Numpy

You might wonder why all machine learning tutorials will be using numpy, why not other libraries? Please let me talk about what is Python before we go into numpy.

Python is a programming language that we can import library that is written in C++ magically. C++ is a very fast language and the code will be compiled to machine code directly, hence library in C++ can perform faster than library written purely by python.

Numpy is fast! And it is maintained by a lot of great programmers over the Internet.

Numpy is an open source library written in C++, it is the fundamental package for scientific computing with Python. It is very easy to be installed like below:

pip install numpy

It contains a lot of tools, algorithms for most of the machine learning tasks such as

powerful N-dimensional array object sophisticated (broadcasting) functions useful linear algebra, Fourier transform, and random number capabilities

Common technical terms in numpy

shape

np.random.rand(d0, d1, …, dn) — Random values in a given shape.

np.full(shape, fill_value, dtype=None, order=’C’) — Return a new array of given shape and type, filled with fill_value.

Whenever the description said “shape”, it means the array size, or dimension size. If “shape” of a numpy array is [4, 3, 2], meaning it is a 3d array, because the shape itself has 3 values 4, 3, and 2. Let see the image below.

An array with shape of [4, 3, 2]. 4 2d array with [3,2]. For each 2d array, it has 3 rows and 2 columns.

For array with shape of 4d, you can think the array contains many 3d arrays. Then you can imagine the data using 3d array like the image above.

scalar

When you see “scalar” in the description, it is just a single value. For example, x = 1, y = 3.0. All these are considered as “scalar”.

dtype

dtype is data type, where common data type are uint8 (unsigned 8-bit integer, 0–255) for image, int32 (signed 32-bit integer, -²³² to ²³²-1) for scalar, float32 (signed 32-bit float) for scalar. Most operation will be using float32 as there are a lot of decimals in machine learning data.

It can be read as {signed/unsigned}_{int/float}_{number of bit, 8, 16, 32, …}.

array_like

array_like usually means numpy array or list, which can be interpret as array. Inside the library, it will help to convert to numpy array.

ndarray

input must be a numpy array, cannot be list,

Powerful N-dimensional array object

In machine learning, we will be always dealing with “data”. In layman term, data is an excel file, storing information about something. (e.g. sales records for a company)

Illustration of a simple sales record

The above example is a very simple sales record which is having date, item name, and price.

When we want to load this file into python, most probably we will use numpy or pandas (another library based on numpy) to load the file. After loading, it will become a numpy array with an array shape of (3, 3), meaning 3 row of data with 3 columns of information.

For better understanding what is a numpy array, or N-d array, we can imagine that 1-d array is a vector or a list of items, 2-d array is a matrix, 3-d array can be list of matrix. You can refer the image above for illustration.

Numpy will be automatically convert the data into N-d array, so that we can perform more operations as simple as addition and as sophisticated as matrix multiplication.

Sophisticated (broadcasting) functions

This might be a little bit complicated to explain, when you become experienced in numpy, that you will understand what is broadcasting properly.

Broadcasting is more like an automatic array allocation. In Java, we have ArrayList which it will automatic expand the array size. Broadcasting is more like magically performing the array expansion to perform some arithmetic operations such as addition.

Example on what is broadcasting

In the above example, we have a 2-d array x with shape (2, 3) and 1-d array y with shape (3,). x is an array with 2 rows, for each row, we have 3 columns. First row is [0, 1, 2] and second row is [3, 4, 5].

Performing a simple addition operation which is just adding x and y by the syntax: z = x + y, storing the result to z. However, you might wonder, two of them having different array size, why it can be achieved as simple as x + y. This is how “broadcasting” works. It can be understood as for each row of x, return x[i] + y. Then the output z will be automatically created with shape of x (2, 3), storing result of x + y.

How to read numpy documentation

Alright, finally comes to the main topic! Whenever you face problem on the numpy function usage and you don’t know how to use it, you can Google Search with keyword like “np.dot”.

how to search numpy function

Usually the first one will be what you want, enter the page would be something like below

numpy.dot documentation page

When I first read the documentation, I found it difficult because I don’t know where to look at, the text seems complicated and messy. However, after familiar with numpy, I only search for what I want to know, i.e. input and output.

numpy.dot documentation page highlight

First, is it the function that you want? For example, you want to perform dot product on two 2-d array (a.k.a matrix) where C = AB. So now you look at the first line of the documentation, is it describing what you want? Hmmmm, “Dot product of two arrays” seems like correct.

numpy.dot documentation page more description

Seems like a lot of text for me as a beginner. Sometime I just skip this section because I feel like it doesn’t help me 😂. After you familiar with numpy, I suggest you to read the description, might be helping you to further understand how it works. However, I will always look at the parameters and sample input and output.

numpy.dot documentation parameter

Whenever we see array_like, it means the function input is a numpy array, from the meaning of dot product, you should aware that input is either 1-d or 2-d array (although can accept N-d (N > 2) as well). Almost most of the numpy operations have out as parameter, this is for memory reference probably for memory efficient program, however, I recommend that we always call the function like this: out = np.dot(a, b) instead of np.dot(a, b, out). It is linked to some programming language concept, I always use the first way which is out = np.dot(a, b).

Most of the numpy operations return ndarray which is a numpy array. Only some of the operations return something else such as tuple or indices.

numpy.dot documentation output

I always look at the examples to find out how to use the function, however sometime you might confuse on which to look.

In this case, you should try to run the sample, or put any values into the sample to test if the function can output the result you expected.

TLDR;

Read first few lines of the description, is it matching with what you want. You might find out a lot of information in the documentation page, search for parameters only. Look at the examples. Keep on doing trial and error.

Let me know what problem you are facing when you read numpy documentation, so that I can continue writing good tutorial on reading numpy documentation (or any library documentation that are common, e.g. pytorch).