NumPy roll()

import numpy as np

# create an array
array1 = np.array([0, 1, 2, 3, 4])

# shift elements of array1 by 3 steps
array2 = np.roll(array1, 3)

print(array2)

# Output: [2 3 4 0 1]

roll() Syntax

The syntax of roll() is:

numpy.roll(array, shift, axis)

roll() Arguments

The roll() method takes three arguments:

• array - an array with elements to be rolled
• shift - how many steps the element shifts ( int or tuple )
• axis(optional) - axis to roll/shift ( int or tuple )

roll() Return Value

The roll() method returns the array with elements shifted.

Example 1: Roll a 1-D Array

import numpy as np

# create an array
array1 = np.array([0, 1, 2, 3, 4])

# roll elements of array1 by 3 steps
array2 = np.roll(array1, 3)

print(array2)

# roll elements of array1 backwards by 1 step
array3 = np.roll(array1, -1)

print(array3)

Output

[2 3 4 0 1]
[1 2 3 4 0]

Here, array3 is rolled by a negative value (-1), so it's shifted backward.

Example 2: Roll a 2-D Array

A 2-D array can be rolled on two axes. If the array is rolled on axis 0, it shifts vertically and if the array is rolled on axis 1, it shifts horizontally.

import numpy as np

# create an array
array1 = np.array([[0, 1, 2], [3, 4, 5]])

# roll elements of array1 by 1 step
array2 = np.roll(array1, 1)

# roll elements of array1 by 1 step on axis 0
array3 = np.roll(array1, 1, 0)

# roll elements of array1 by 1 step on axis 1
array4 = np.roll(array1, 1, 1)

# roll elements of array1 by 1 step on both axes
array5 = np.roll(array1, 1, (0, 1))


print('\nRoll one step:\n',array2)
print('\nRoll on axis 0:\n',array3)
print('\nRoll on axis 1:\n',array4)
print('\nRoll on both axes:\n',array5)

Output

Roll one step:
[[5 0 1]
 [2 3 4]]

Roll on axis 0:
 [[3 4 5]
 [0 1 2]]

Roll on axis 1:
 [[2 0 1]
 [5 3 4]]

Roll on both axes:
 [[5 3 4]
 [2 0 1]]

If the axis is not provided, the array is flattened, rolled, and reshaped back to its original shape.

Example 3: Roll a 2-D Array on Both Axes With Different Numbers of Shifts

The roll() method allows us to shift elements along multiple axes by specifying the number of times we want to roll each axis.

We can apply different rolling operations to different axes of an array.

import numpy as np

array1 = np.array(
    [[0, 1, 2],
    [3, 4, 5],
    [6, 7, 8]])

# roll elements by variable amounts
shift = (1, 2)

# uneven rolling of the elements 
rolledArray1 = np.roll(array1, shift)

# uneven rolling of the elements with axis provided 
rolledArray2 = np.roll(array1, shift, (1,0))

print('Default roll:\n',rolledArray1)
print('Roll with (1,0) axes:\n',rolledArray2)

Output

Default roll:
 [[6 7 8]
 [0 1 2]
 [3 4 5]]
Roll with (0,1) axes:
 [[6 7 8]
 [0 1 2]
 [3 4 5]]

The default axis is (0, 1). With the shift of (1, 2), the array shifts by 1 step in axis-0 and 2 steps in axis-1.