Python: numpy.ravel() function Tutorial with examples

In this article we will discuss the numpy.ravel() function and how we can use it in different ways to flatten a multidimensional numpy array.

numpy.ravel()

Python’s numpy module provides a built-in function,

numpy.ravel(a, order='C')

Parameters:

• a : array_like
  • It can be a numpy array or any other array-like sequence like list. Elements from it will be read based on given order.
• order: The order in which items from numpy array will be used,
  • ‘C’: Read items from array row wise i.e. using C-like index order.
  • ‘F’: Read items from array column wise i.e. using Fortran-like index order.
  • ‘K’: Read items from array based on memory order of items

It returns a flattened 1D view of the input array.

Let’s understand it with some examples,

First of all, import the numpy module,

import numpy as np

Flatten a matrix or 2D array to 1D array using numpy.ravel()

Suppose we have a 2D Numpy array,

# Create a 2D Numpy array
arr_2d = np.array([ [0, 1, 2],
                    [3, 4, 5],
                    [6, 7, 8]])

print('2D Numpy Array:')
print(arr_2d)

Output:

2D Numpy Array:
[[0 1 2]
 [3 4 5]
 [6 7 8]]

Let’s generate a flattened 1D view of this 2D numpy array using ravel() function,

# Get a flattened view of 2D Numpy array
flat_array = np.ravel(arr_2d)

print('Flattened view:')
print(flat_array)

Output:

Flattened view:
[0 1 2 3 4 5 6 7 8]

We didn’t provide any order parameter therefore the default value of order parameter ‘C’ was used and elements from the 2D array were read row by row.

numpy.ravel() returns a view

In the previous example, we created a flattened view flat_array of the original 2D numpy array arr_2d. Now let’s modify this view object,

# Modify the 2nd element  in flat array
flat_array[1] = 11

We changed the content of view object only, but the changes will be reflected in both the flattened 1D view object and original 2D numpy array,

# Changes will be reflected in both flat array and original 2D array
print(flat_array)
print(arr_2d)

Output:

[ 0 11  2  3  4  5  6  7  8]

[[ 0 11  2]
 [ 3  4  5]
 [ 6  7  8]]

How to access the original array from the flattened view object ?

Returned flattened view object has an attribute base, which points to the original numpy array,

# ndarray.base points to the original numpy array
print(flat_array.base)

Output:

[[ 0 11  2]
 [ 3  4  5]
 [ 6  7  8]]

Use numpy.ravel() along different axis with order parameter

ndarray.ravel() accepts an optional parameter order. It can be ‘C’ or ‘F’ or ‘A’, but the default value is ‘C’. It tells the order in which items from input numpy array will be used,

• ‘C’: Read items from array row wise i.e. using C-like index order.
• ‘F’: Read items from array column wise i.e. using Fortran-like index order.
• ‘A’: Read items from array based on memory order of items

Let’s discuss them one by one with examples,

We have a 2D Numpy array,

# Create a 2D Numpy array
arr_2d = np.array([[0, 1, 2],
                   [3, 4, 5],
                   [6, 7, 8]])

Get Flatten view of 2D array Row wise

If we don’t pass the order parameter in the ravel() function then its default value ‘C’ will be used. It means elements from a 2D array will be read row by row,

# Get a flattened view of 2D array by reading items row by row
flat_array = np.ravel(arr_2d, order='C')

print('Flattened View:')
print(flat_array)

Output:

Flattened View:
[0 1 2 3 4 5 6 7 8]

Get Flatten view of 2D array Column wise

If we pass ‘F’ as the order parameter in ravel() function then it means elements from a 2D array will be read column by column,

# Get a flattened view of 2D array by reading items column by column
flat_array = np.ravel(arr_2d, order='F')

print('Flattened View:')
print(flat_array)

Output:

Flattened View:
[0 3 6 1 4 7 2 5 8]

Get Flatten view of 2D array based on memory layout

Let’s create a transpose view of the 2D numpy array,

trans_arr = arr_2d.T

print('Transposed View of 2D Array')
print(trans_arr)

Output:

Transposed View of 2D Array
[[0 3 6]
 [1 4 7]
 [2 5 8]]

Now get a flatten view this transpose 2D array ROW WISE,

# Read items from 2D numpy array row by row based on current view
flat_array = np.ravel(trans_arr, order='C')

print('Flattened View:')
print(flat_array)

Output:

Flattened View:
[0 3 6 1 4 7 2 5 8]

As the order parameter was ‘C’, therefore it read the elements from view object row wise. But the original memory layout view was neglected and the current layout of the view object was used.

Now get flatten view of this transposed numpy array based on memory layout using argument ‘A’

# Read items from 2D numpy array row by row based on memory layout of
# the original numpy array underneath
flat_array = np.ravel(trans_arr, order='A')

print('Flattened View:')
print(flat_array)

Output:

Flattened View:
[0 1 2 3 4 5 6 7 8]

Instead of considering the current layout in view, it used the memory layout of the original array object to read items row wise.

Flatten a list of lists using numpy.ravel()

numpy.ravel() expects an array like parameter, from which it will create a flattened view. So, instead of a numpy array we can also pass list or list of lists in the ravel() function directly.

Suppose we have a list of lists,

# Create a list of lists
list_of_lists = [[1, 2, 3, 4, 5],
                 [1, 2, 3, 4, 5],
                 [1, 2, 3, 4, 5],
                 [1, 2, 3, 4, 5]]

Now let’s create a flattened numpy array from this list of list,

# Create a flattened numpy array from list of lists
flat_array = np.ravel(list_of_lists)

print('Flattened Numpy Array:')
print(flat_array)

Output:

Flattened Numpy Array:
[1 2 3 4 5 1 2 3 4 5 1 2 3 4 5 1 2 3 4 5]

We can also convert this flattened numpy array to a list,

# Convert array to list
print('Flattened List:')
print(list(flat_array))

Output:

Flattened List:
[1, 2, 3, 4, 5, 1, 2, 3, 4, 5, 1, 2, 3, 4, 5, 1, 2, 3, 4, 5]

So, basically we converted a list of lists to a flat list using numpy.ravel().

The complete example is as follows,

import numpy as np


def main():

    print('*** Flatten a matrix or 2D array to 1D array using numpy.ravel() ***')

    # Create a 2D Numpy array
    arr_2d = np.array([ [0, 1, 2],
                        [3, 4, 5],
                        [6, 7, 8]])

    print('2D Numpy Array:')
    print(arr_2d)

    # Get a flattened view of 2D Numpy array
    flat_array = np.ravel(arr_2d)

    print('Flattened view:')
    print(flat_array)

    print('**** numpy.ravel() returns a view of the input array ****')

    # Modify the 2nd element  in flat array
    flat_array[1] = 11

    # Changes will be reflected in both flat array and original 2D array
    print(flat_array)
    print(arr_2d)

    print('*** Access the original array from the flattened view object ***')

    # ndarray.base points to the original numpy array
    print(flat_array.base)


    print('*** Use numpy.ravel() along different axis with order parameter ***')

    # Create a 2D Numpy array
    arr_2d = np.array([[0, 1, 2],
                       [3, 4, 5],
                       [6, 7, 8]])

    print('2D Numpy array')
    print(arr_2d)

    print('Get Flatten view of 2D array Row wise')

    # Get a flattened view of 2D array by reading items row by row
    flat_array = np.ravel(arr_2d, order='C')

    print('Flattened View:')
    print(flat_array)


    print('Get Flatten view of 2D array Column Wise')

    # Get a flattened view of 2D array by reading items column by column
    flat_array = np.ravel(arr_2d, order='F')

    print('Flattened View:')
    print(flat_array)

    print('Get Flatten view of 2D array based on memory layout')

    trans_arr = arr_2d.T

    print('Transposed View of 2D Array')
    print(trans_arr)

    # Read items from 2D numpy array row by row based on current view
    flat_array = np.ravel(trans_arr, order='C')

    print('Flattened View:')
    print(flat_array)

    # Read items from 2D numpy array row by row based on memory layout of
    # the original numpy array underneath
    flat_array = np.ravel(trans_arr, order='A')

    print('Flattened View:')
    print(flat_array)

    print('**** Flatten a list of lists using numpy.ravel() ****')

    # Create a list of lists
    list_of_lists = [[1, 2, 3, 4, 5],
                     [1, 2, 3, 4, 5],
                     [1, 2, 3, 4, 5],
                     [1, 2, 3, 4, 5]]

    # Create a flattened numpy array from list of lists
    flat_array = np.ravel(list_of_lists)

    print('Flattened Numpy Array:')
    print(flat_array)

    # Convert array to list
    print('Flattened List:')
    print(list(flat_array))


if __name__ == '__main__':
    main()

Output:

*** Flatten a matrix or 2D array to 1D array using numpy.ravel() ***
2D Numpy Array:
[[0 1 2]
 [3 4 5]
 [6 7 8]]
Flattened view:
[0 1 2 3 4 5 6 7 8]
**** numpy.ravel() returns a view of the input array ****
[ 0 11  2  3  4  5  6  7  8]
[[ 0 11  2]
 [ 3  4  5]
 [ 6  7  8]]
*** Access the original array from the flattened view object ***
[[ 0 11  2]
 [ 3  4  5]
 [ 6  7  8]]
*** Use numpy.ravel() along different axis with order parameter ***
2D Numpy array
[[0 1 2]
 [3 4 5]
 [6 7 8]]
Get Flatten view of 2D array Row wise
Flattened View:
[0 1 2 3 4 5 6 7 8]
Get Flatten view of 2D array Column Wise
Flattened View:
[0 3 6 1 4 7 2 5 8]
Get Flatten view of 2D array based on memory layout
Transposed View of 2D Array
[[0 3 6]
 [1 4 7]
 [2 5 8]]
Flattened View:
[0 3 6 1 4 7 2 5 8]
Flattened View:
[0 1 2 3 4 5 6 7 8]
**** Flatten a list of lists using numpy.ravel() ****
Flattened Numpy Array:
[1 2 3 4 5 1 2 3 4 5 1 2 3 4 5 1 2 3 4 5]
Flattened List:
[1, 2, 3, 4, 5, 1, 2, 3, 4, 5, 1, 2, 3, 4, 5, 1, 2, 3, 4, 5]