Python Pandas - Timedelta

Pandas - Timedelta Objects

Timedelta objects in Pandas represent a duration or a difference between two dates or times. They are the Pandas equivalent of Python’s datetime.timedelta and are implemented efficiently using NumPy’s timedelta64[ns] type (nanosecond precision).

Timedeltas can be positive or negative and are expressed in units like days, hours, minutes, seconds, milliseconds, microseconds, or nanoseconds.

You can create Timedelta objects in several ways:

Creating from Strings

Pandas can parse string representations of durations.

import pandas as pd

# Create Timedelta from a string
td1 = pd.Timedelta('2 days 2 hours 15 minutes 30 seconds')
print(f"String '2 days 2 hours 15 minutes 30 seconds': {td1}")

td2 = pd.Timedelta('5d 3h') # Abbreviated format
print(f"String '5d 3h': {td2}")

td3 = pd.Timedelta('-1 days + 12:00:00') # Negative timedelta
print(f"String '-1 days + 12:00:00': {td3}")

Output:

String '2 days 2 hours 15 minutes 30 seconds': 2 days 02:15:30
String '5d 3h': 5 days 03:00:00
String '-1 days + 12:00:00': -1 days +12:00:00

Creating from Integers with Units

Pass an integer value along with a time unit specified by the unit parameter.

import pandas as pd

# Create Timedelta from integer and unit
td_hours = pd.Timedelta(6, unit='h') # 6 hours
print(f"Integer 6, unit='h': {td_hours}")

td_minutes = pd.Timedelta(150, unit='m') # 150 minutes
print(f"Integer 150, unit='m': {td_minutes}")

td_days = pd.Timedelta(3, unit='D') # 3 days (Use 'D' for days)
print(f"Integer 3, unit='D': {td_days}")

Output:

Integer 6, unit='h': 0 days 06:00:00
Integer 150, unit='m': 0 days 02:30:00
Integer 3, unit='D': 3 days 00:00:00

Common units include: 'W', 'D', 'h', 'm', 's', 'ms', 'us', 'ns'.

Creating using Keyword Arguments (Offsets)

Similar to Python’s datetime.timedelta, you can use keyword arguments like weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds.

import pandas as pd

# Create Timedelta using keyword arguments
td_days_kw = pd.Timedelta(days=2)
print(f"Keyword days=2: {td_days_kw}")

td_complex = pd.Timedelta(days=1, hours=5, minutes=30)
print(f"Keyword days=1, hours=5, minutes=30: {td_complex}")

Output:

Keyword days=2: 2 days 00:00:00
Keyword days=1, hours=5, minutes=30: 1 days 05:30:00

Converting Data using pd.to_timedelta()

The top-level pd.to_timedelta() function is a versatile tool for converting various inputs (scalars, arrays, lists, Series) into Timedelta objects. It intelligently parses strings or interprets numbers based on the specified unit.

import pandas as pd

# Convert a list of strings
str_list = ['1h 30m', '2 days', '-50s']
td_index = pd.to_timedelta(str_list)
print(f"Converted from list of strings:\n{td_index}")

# Convert a Series of numbers (assuming unit is days)
num_series = pd.Series([1, 2.5, -0.5])
td_series_days = pd.to_timedelta(num_series, unit='D')
print(f"\nConverted from Series (unit='D'):\n{td_series_days}")

# Handling errors during conversion
bad_input = ['3 hours', '4 days', 'invalid data']
td_with_errors = pd.to_timedelta(bad_input, errors='coerce') # 'coerce' turns errors into NaT
print(f"\nConverted with errors='coerce':\n{td_with_errors}")

Output:

Converted from list of strings:
TimedeltaIndex(['0 days 01:30:00', '2 days 00:00:00', '-1 days +23:59:10'],
               dtype='timedelta64[ns]', freq=None)

Converted from Series (unit='D'):
0   1 days 00:00:00
1   2 days 12:00:00
2  -1 days +12:00:00
dtype: timedelta64[ns]

Converted with errors='coerce':
TimedeltaIndex(['0 days 03:00:00', '4 days 00:00:00', NaT],
               dtype='timedelta64[ns]', freq=None)

The errors parameter in to_timedelta can be 'raise' (default), 'coerce' (invalid parsing becomes NaT - Not a Time), or 'ignore' (returns the input if it can’t be parsed).

Operations with Timedeltas

Timedeltas can be added to or subtracted from Timestamp or datetime objects to shift them in time. You can also perform arithmetic operations between Timedeltas.

Let’s create a DataFrame involving Timestamps and Timedeltas:

import pandas as pd

# Series of Timestamps
timestamps = pd.Series(pd.date_range('2023-03-10', periods=4, freq='D'))

# Series of Timedeltas
durations = pd.Series([pd.Timedelta(days=i, hours=i*6) for i in range(4)])

df = pd.DataFrame({'Start_Time': timestamps, 'Duration': durations})

print("Original DataFrame:")
print(df)

Output:

Original DataFrame:
  Start_Time        Duration
0 2023-03-10 0 days 00:00:00
1 2023-03-11 1 days 06:00:00
2 2023-03-12 2 days 12:00:00
3 2023-03-13 3 days 18:00:00

Addition Operations

Add a Timedelta to a Timestamp to get a future Timestamp.

# (Using df from previous example)

# Calculate End_Time = Start_Time + Duration
df['End_Time'] = df['Start_Time'] + df['Duration']

# Add a fixed duration (e.g., 1 hour) to Start_Time
df['Start_Plus_1H'] = df['Start_Time'] + pd.Timedelta(hours=1)

print("\nDataFrame after Addition Operations:")
print(df)

Output:

DataFrame after Addition Operations:
  Start_Time        Duration            End_Time     Start_Plus_1H
0 2023-03-10 0 days 00:00:00 2023-03-10 00:00:00 2023-03-10 01:00:00
1 2023-03-11 1 days 06:00:00 2023-03-12 06:00:00 2023-03-11 01:00:00
2 2023-03-12 2 days 12:00:00 2023-03-14 12:00:00 2023-03-12 01:00:00
3 2023-03-13 3 days 18:00:00 2023-03-17 06:00:00 2023-03-13 01:00:00

Subtraction Operations

Subtracting two Timestamps yields a Timedelta. Subtracting a Timedelta from a Timestamp yields a past Timestamp.

# (Using df with 'End_Time' from previous example)

# Calculate the difference between End_Time and Start_Time (should equal Duration)
df['Calculated_Duration'] = df['End_Time'] - df['Start_Time']

# Calculate Time Before Start = Start_Time - 12 hours
df['Start_Minus_12H'] = df['Start_Time'] - pd.Timedelta(hours=12)

print("\nDataFrame after Subtraction Operations:")
# Display relevant columns for clarity
print(df[['Start_Time', 'End_Time', 'Duration', 'Calculated_Duration', 'Start_Minus_12H']])

Output:

DataFrame after Subtraction Operations:
  Start_Time            End_Time        Duration Calculated_Duration   Start_Minus_12H
0 2023-03-10 2023-03-10 00:00:00 0 days 00:00:00   0 days 00:00:00 2023-03-09 12:00:00
1 2023-03-11 2023-03-12 06:00:00 1 days 06:00:00   1 days 06:00:00 2023-03-10 12:00:00
2 2023-03-12 2023-03-14 12:00:00 2 days 12:00:00   2 days 12:00:00 2023-03-11 12:00:00
3 2023-03-13 2023-03-17 06:00:00 3 days 18:00:00   3 days 18:00:00 2023-03-12 12:00:00

Timedeltas are essential for time-based calculations, interval analysis, and feature engineering in time series data.