Mastering DataFrame.diff() method in Pandas (5 examples)

Updated: February 20, 2024 By: Guest Contributor Post a comment


In this tutorial, we’ll explore the DataFrame.diff() method in Pandas, a powerful tool for data analysis that helps in computing the difference between consecutive elements of a DataFrame. Whether you’re a beginner or looking to enhance your Pandas skills, understanding how to effectively use this method can greatly improve your data manipulation capabilities. Through 5 practical examples, we’ll cover everything from basic usage to more advanced applications of the diff() method.

The Syntax of DataFrame.diff() Method

Before diving into examples, let’s first understand what DataFrame.diff() does. It calculates the difference of a DataFrame element compared with another element in the DataFrame (default is the element in the previous row). This is especially useful in time series data to find the change in data points over time. The basic syntax is:

DataFrame.diff(periods=1, axis=0)

where periods specifies the spacing between the elements to compare, and axis determines whether to apply the function to the rows (0) or columns (1).

Basic Usage

To begin with, let’s create a simple DataFrame:

import pandas as pd

df = pd.DataFrame({
    "A": [1, 2, 4, 7, 11],
    "B": [4, 5, 6, 7, 8]

Applying df.diff() will show us the difference between each row:



     A    B
0  NaN  NaN
1  1.0  1.0
2  2.0  1.0
3  3.0  1.0
4  4.0  1.0

The first row is NaN because there is nothing to subtract from the first element. This example highlights the method’s basic functionality—calculating differences between consecutive rows.

Comparing Non-consecutive Elements

To examine changes over a longer period, change the periods parameter:



     A    B
0  NaN  NaN
1  NaN  NaN
2  3.0  2.0
3  5.0  2.0
4  7.0  2.0

This allows us to see the difference between elements spaced further apart, showing a clearer trend over time.

Applied Across Columns

By adjusting the axis parameter, you can apply the difference calculation across columns instead of rows:



    A    B
0 NaN  3.0
1 NaN  3.0
2 NaN  2.0
3 NaN  0.0
4 NaN -3.0

Here, we see the difference between each column for every row, useful for comparing changes between variables over time.

Handling Missing Data

While using df.diff(), you might encounter DataFrames with missing values. Let’s see how it handles this scenario:

df = pd.DataFrame({
    "A": [1, pd.NA, 4, 7, 11],
    "B": [4, 5, pd.NA, 7, 8]



      A     B
0   NaN   NaN
1   NaN   1.0
2   NaN   NaN
3   3.0   NaN
4   4.0   1.0

Notice that the method automatically handles missing values without throwing an error, resulting in NaN for calculations involving NaN values.

Working with Time Series Data

For a more complex example, consider time series data:

date_rng = pd.date_range(start='1/1/2020', end='1/10/2020', freq='D')
df = pd.DataFrame(date_rng, columns=['date'])
df['data'] = np.random.randint(0,100,size=(len(date_rng)))


This demonstrates the diff() method’s effectiveness in analyzing daily changes in time series datasets, providing insights into trends and patterns over time.


Throughout this tutorial, we’ve explored various applications of the Pandas DataFrame.diff() method, from simple to more complex scenarios. By mastering this function, you can enhance your data analysis skills, uncovering trends and changes in your datasets more effectively. Whether you’re working with basic datasets or complex time series data, the diff() method is an invaluable tool in your data science toolkit.