Pandas TimedeltaIndex examples (basic to advanced)

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

In the world of data analysis with Python, Pandas stands out for its robust set of tools designed to work with time series data. Among its powerful features is the TimedeltaIndex, which is especially useful for time-based indexing and manipulation. This tutorial aims to provide a broad range of examples to help you understand and leverage the power of the TimedeltaIndex in your data analysis tasks, from basic to advanced applications.

Introduction to TimedeltaIndex

Before diving into the examples, let’s establish what a TimedeltaIndex is. A timedelta represents a duration, the difference between two dates or times. In Pandas, TimedeltaIndex is used for indexing or constructing a DataFrame based on time durations. This can be particularly useful for time series analysis, scheduling tasks, or any scenario where you need to work with time intervals.

Basic Examples

Let’s start with some basic usages of TimedeltaIndex.

Creating a TimedeltaIndex

import pandas as pd

# Creating a TimedeltaIndex from a list of durations
timedeltas = pd.TimedeltaIndex(['1 days 02:00:00', '2 days 03:30:45', '5 days 00:00:00'])

# Display the TimedeltaIndex

In this example, we’ve created a TimedeltaIndex from a list of string durations. When printed, it shows a list of Timedelta objects representing the durations provided.

Using TimedeltaIndex with DataFrames

import pandas as pd

# Create a DataFrame with a TimedeltaIndex
df = pd.DataFrame({"Data": ["A", "B", "C"]}, index=pd.TimedeltaIndex(['1 day', '2 days', '3 days']))

# Display the DataFrame

In this instance, we have a DataFrame indexed by time durations. This allows for easy data manipulation and querying based on time intervals.

Intermediate Examples

As you become more comfortable with the basics, let’s move on to more intermediate applications of TimedeltaIndex.

Slicing and Dicing with TimedeltaIndex

import pandas as pd

# Creating a DataFrame with TimedeltaIndex
pd.DataFrame({"Data": ["Item 1", "Item 2", "Item 3"]}, index=pd.TimedeltaIndex(['1 day', '2 days', '3 days']))

# Slicing the DataFrame based on TimedeltaIndex
df.loc[pd.Timedelta('1 day'):pd.Timedelta('2 days')]

This example showcases how to slice a DataFrame indexed by time intervals, allowing for easy extraction of data within specific ranges of time.

Operations on TimedeltaIndex

import pandas as pd

df = pd.DataFrame({"Start": ["2023-01-01", "2023-01-02", "2023-01-03"],
                   "Finish": ["2023-01-02", "2023-01-03", "2023-01-04"]})

df['Start'] = pd.to_datetime(df['Start'])

df['Finish'] = pd.to_datetime(df['Finish'])

df['Duration'] = df['Finish'] - df['Start']


This demonstrates how to compute durations between dates in a DataFrame and how these durations are automatically represented as a TimedeltaIndex when stored in a column.

Advanced Examples

Now, let’s look at some advanced functionality involving TimedeltaIndex.

Resampling Data with TimedeltaIndex

import pandas as pd

# Create a DataFrame with high frequency data
high_freq_df = pd.DataFrame({"Data": range(100)},
                            index=pd.date_range("2023-01-01", periods=100, freq="T"))

# Resample data by summing up every 10 minutes
decimated_df = high_freq_df.resample('10T').sum()


Resampling involves changing the frequency of your data points. In this case, we use TimedeltaIndex to aggregate data from a minutely to a 10-minute frequency, demonstrating its applicability in time series data downsampling.

Using Timedelta in Rolling Windows

import pandas as pd

# Example DataFrame
df = pd.DataFrame({"Data": ["A", "B", "C", "D", "E"]},
                  index=pd.date_range("2023-01-01", periods=5, freq='D'))

# Apply a rolling window operation based on time

In this example, a rolling window operation is applied to the DataFrame, using time durations as the window definition. It showcases how TimedeltaIndex can be used to conduct analyses over moving time intervals, making it invaluable for smooth data analysis and trend spotting.


Throughout this tutorial, we’ve explored the versatility and power of Pandas’ TimedeltaIndex feature. Starting from basic creation and manipulation, and moving through to advanced applications like resampling and rolling operations, it’s clear that understanding TimedeltaIndex can significantly enhance your ability to work with time series data in Pandas. By mastering the examples shared, you’ve taken important steps to becoming proficient in time-based data analysis.