In this post, we will explore simple methods to convert NumPy arrays to lists. For example, we can utilize the Python function list() or the NumPy array method tolist().
Both ways are similar, but there are some differences to consider to choose the right one for each application.
Python Function list()
The function list() accepts as input the array to convert, and it is equivalent to the following python code:
my_list = []
for el in my_arr:
my_list.append(el)
This algorithm processes only the first level of the array preserving the NumPy scalar data type, i.e., it will return a list of NumPy objects.
NumPy scalar types are a more sophisticated way to represent data useful for scientific calculation where precision, RAM usage, or compatibility with C programming language are essential.
Let’s see some code examples for arrays of dimensions one, two, or more and the particular case of zero dimension.
Case 1: One-dimensional arrays (1D)
We first import the NumPy package and create a sample array. Then, we can make the array of the data type needed using the optional parameter dtype. In this case, an array of 8 bits integers, i.e., we can have integer numbers in the range [-127,127].
Then we convert it to a list using the function list().
The last few lines of code check that the data type of the resulting object is a list and that the data type of elements of the list has not changed.
# converting a 1D array to lists using the function list()
# import numpy package
import numpy as np
import sys
# create a sample 1D array of 8-bit integers:
arr = np.array([1, 2, 3, 4], dtype=np.int8)
# let's check the generated sample array and its type
print('\nSample array: \n', arr)
print('\nData type of the array's elements: ', arr.dtype)
# conversion using the function list()
new_list = list(arr)
# check the created object type
print('\nList created: \n', new_list)
# check data types for the created object and one of its elements
print('\nObject type: ', str(type(new_list)))
print('Data type of the lists's elements: ', new_list[0].dtype)
The output of the code is:
Sample array:
[1 2 3 4]
Data type of the array's elements: int8
List created:
[1, 2, 3, 4]
Object type: <class 'list'>
Data type of the lists's elements: int8
The output shows that we converted the 1D array into a list. Moreover, the data type of the list elements is not changed.
Case 2: Two-dimensional arrays (2D)
In this case, we replace the array definition with a two-dimensional array of NumPy data type int8, then we check the type of the object contained in the list and the data type of one of its elements.
# converting a 2D array to lists using the function list()
# import numpy package
import numpy as np
# create an 2D array of the default data type (int8):
arr = np.array([[1, 2], [3, 4]], dtype=np.int8)
# let's check the generated sample array and its type
print('\nSample array: \n', arr)
print('\nData type of the array's elements: ', arr.dtype)
# conversion using the function list()
new_list = list(arr)
# check the created object type
print('\nList created: \n', new_list)
# check data types for the created object and the class and data type of one of its elements
print('\nObject type: ', str(type(new_list)))
print('Data type of the lists's elements: ', str(type(new_list[0])))
print('Data type of an element of the arrays belonging to the list: ', new_list[0].dtype)
The output of the code is:
Sample array:
[[1 2]
[3 4]]
Data type of the array's elements: int8
List created:
[array([1, 2], dtype=int8), array([3, 4], dtype=int8)]
Object type: <class 'list'>
Data type of the lists's elements: <class 'numpy.ndarray'>
Data type of an element of the arrays belonging to the list: int8
Pay attention here: the list() function creates a list of arrays. It does not create a list of lists, i.e., the iteration stops at the first level!!!
Moreover, each element of these arrays is still NumPy 8-bit integer. We will see that the behavior of the tolist() method is different.
Case 3: zero-dimensional arrays (0D).
Let’s now look at the particular case of NumPy arrays of zero length, replacing the array definition.
# converting a 0D array to lists using the function list()
# import numpy package
import numpy as np
# create a sample 0D array of 8 bit integers:
arr = np.array(7, dtype=np.int8)
# let's check the generated sample array and its type
print('\nSample array: \n', arr)
print('\nData type of the array's elements: ', arr.dtype)
# conversion using the function list()
new_list = list(arr)
# check the created object type
print('\nList created: \n', new_list)
# check data types for the created object and its element
print('\nObject type: ', str(type(new_list)))
print('Data type of the lists's elements: ', new_list[0].dtype)
Running the code generates an error!
Sample array:
7
Data type of the array's elements: int8
Traceback (most recent call last):
(....)
File "/#####/NumpyArrayConv.py", line xxx, in <module>
new_list = list(arr)
TypeError: iteration over a 0-d array
The array of zero dimension is not an iterable object, and we get an execution error!
Arrays of zero dimension are an uncommon occurrence. Still, when analyzing edge cases or data science applications where NumPy arrays are widely used, it is something to consider.
Numpy Array Method tolist()
The NumPy method tolist() does not take any argument and converts an array iteratively to a list.
This means that in case of arrays of two or more dimensions, it will return a nested list.
Each element of the lists is then converted from the NumPy scalars data type ‘to the nearest compatible built-in Python type’ (i.e., it will return a list of Python objects).
The Python objects data types are less sophisticated and are suitable for the vast majority of applications. For instance, in the case of integers, the only available data type is 64-bit integers.
Let’s see some examples of how to use the tolist() method.
Case 1: One-dimensional arrays (1D)
Similarly to the above mentioned cases, we first import the NumPy package and create a sample array.
Next, we will create an array of a specific data type using the optional parameter dtype.
In this case, an array of 8 bits integers, i.e., we can have integer numbers in the range [-127,127].
Then we convert it to a list using the method tolist().
Also, in this case, we will check the data type of the resulting objects to show the method tolist() behavior and how it differs from the list() function.
# converting a 1D array to lists using the NumPy method tolist()
# import numpy package
import numpy as np
# create a sample 1D array of 8 bit integers:
arr = np.array([1, 2, 3, 4], dtype=np.int8)
# let's check the generated sample array and its type
print('\nSample array: \n', arr)
print('\nData type of the array's elements: ', arr.dtype)
# conversion using the function list()
new_list = arr.tolist()
# check the created object type
print('\nList created: \n', new_list)
# check data types for the created object and one of its elements
print('\nObject type: ', str(type(new_list)))
print('Data type of the lists's elements: ', str(type(new_list[0])))
The output of the code is:
Sample array:
[1 2 3 4]
Data type of the array's elements: int8
List created:
[1, 2, 3, 4]
Object type: <class 'list'>
Data type of the lists's elements: <class 'int'>
We can see that the method tolist() creates a list of python objects of the class 'int' that correspond to 64-bit integers instead of creating NumPy objects of data type int8.
The main implication is that we would not be able to use NumPy array methods on the elements of the newly created list.
Case 2: Two-dimensional arrays (2D)
Also, in this case, we replace the array definition with a two-dimensional array of NumPy data type int8, then we check the type of the object contained in the list and the data type of one of its elements.
# converting a 2D array to lists using the NumPy method tolist()
# import numpy package
import numpy as np
# create a sample 2D array of 8 bit integers:
arr = np.array([[1, 2], [3, 4]], dtype=np.int8)
# let's check the generated sample array and its type
print('\nSample array: \n', arr)
print('\nData type of the array's elements: ', arr.dtype)
# conversion using the function list()
new_list = arr.tolist()
# check the created object type
print('\nList created: \n', new_list)
# check data types for the created object and the class and data type of one of its elements
print('\nObject type: ', str(type(new_list)))
print('Data type of the lists's elements: ', str(type(new_list[0])))
print('Data type of an element of the nested list: ', str(type(new_list[0][0])))
The output of the code is:
Sample array:
[[1 2]
[3 4]]
Data type of the array's elements: int8
List created:
[[1, 2], [3, 4]]
Object type: <class 'list'>
Data type of the lists's elements: <class 'list'>
Data type of an element of the nested list: <class 'int'>
We can notice that the output shows that we created a list of lists, and the elements of the list are the standard Python 64-bit integers, i.e., the data type of the elements of the lists has changed!
Case 3: Zero-dimensional arrays (0D).
Let’s check again the particular case of NumPy arrays of zero length using the tolist() method
# converting a 0D array to lists using the NumPy method tolist()
# import numpy package
import numpy as np
# create a sample 0D array of 8 bit integers:
arr = np.array(1, dtype=np.int8)
# let's check the generated sample array and its type
print('\nSample array: \n', arr)
print('\nData type of the array's elements: ', arr.dtype)
# conversion using the function list()
new_list = arr.tolist()
# check the created object type
print('\nList created: \n', new_list)
# check data types for the created object and its element
print('\nObject type: ', str(type(new_list)))
The output of the code is:
Sample array:
1
Data type of the array's elements: int8
List created:
1
Object type: <class 'int'>
We can successfully convert the zero-dimension array to a list!
The only element of the list is a Python object of the integer class. Like in the previous case, using this method will result in a data type change.
Conclusions
The Python function list() and the NumPy method tolist() are very similar, but they behave differently depending on the array dimensionality.
In the case of a zero-dimension array, the function list will produce an error since a 0D array is not iterable. However, if we use the NumPy method tolist() instead, we obtain a list of Python objects of the nearest corresponding data type.
In the case of a one-dimensional array, the behavior of the function and the method are almost the same; the only difference is the resulting data type: list() preserves it, tolist() converts from NumPy to Python data types.
In the case of two or more dimensions, the function differs again: list() returns a list of NumPy objects, i.e., if they are nested arrays, it will not convert them to lists; tolist() instead converts the nested arrays in nested lists.