Python Pandas - Calculate TimedeltaArray of difference between index values and index converted to PeriodArray at specified freq

To calculate TimedeltaArray of difference between index values and index converted to PeriodArray at specified frequency, use the to_perioddelta() method on a DatetimeIndex. Set the frequency using the freq parameter.

What is to_perioddelta()?

The to_perioddelta() method calculates the time difference between each datetime value and the start of its corresponding period. For example, with monthly frequency ('M'), it shows how far into each month each datetime falls.

Creating a DatetimeIndex

First, create a DatetimeIndex with specific periods and frequency ?

import pandas as pd

# Create DatetimeIndex with 5 periods, every 2 years
datetimeindex = pd.date_range('2021-10-18 07:20:32.261811624', periods=5, freq='2Y')
print("DateTimeIndex...")
print(datetimeindex)

DateTimeIndex...
DatetimeIndex(['2021-12-31 07:20:32.261811624',
               '2023-12-31 07:20:32.261811624',
               '2025-12-31 07:20:32.261811624',
               '2027-12-31 07:20:32.261811624',
               '2029-12-31 07:20:32.261811624'],
              dtype='datetime64[ns]', freq='2A-DEC')

Converting to Period

Convert the DatetimeIndex to periods with monthly frequency ?

import pandas as pd

datetimeindex = pd.date_range('2021-10-18 07:20:32.261811624', periods=5, freq='2Y')

# Convert to periods with monthly frequency
periods = datetimeindex.to_period(freq='M')
print("Convert DateTimeIndex to Period...")
print(periods)

Convert DateTimeIndex to Period...
PeriodIndex(['2021-12', '2023-12', '2025-12', '2027-12', '2029-12'], dtype='period[M]')

Calculating PeriodDelta

Calculate the TimedeltaArray showing how far into each period the datetime values fall ?

import pandas as pd

datetimeindex = pd.date_range('2021-10-18 07:20:32.261811624', periods=5, freq='2Y')

# Calculate TimedeltaArray of difference between index values and period start
period_delta = datetimeindex.to_perioddelta(freq='M')
print("Convert DateTimeIndex to PeriodDelta...")
print(period_delta)

Convert DateTimeIndex to PeriodDelta...
TimedeltaIndex(['30 days 07:20:32.261811624', '30 days 07:20:32.261811624',
                '30 days 07:20:32.261811624', '30 days 07:20:32.261811624',
                '30 days 07:20:32.261811624'],
               dtype='timedelta64[ns]', freq=None)

Complete Example

Here's the complete example showing all steps ?

import pandas as pd

# Create DatetimeIndex with 5 periods, every 2 years
datetimeindex = pd.date_range('2021-10-18 07:20:32.261811624', periods=5, freq='2Y')

# Display DateTimeIndex
print("DateTimeIndex...")
print(datetimeindex)

# Display frequency
print("\nDateTimeIndex frequency...")
print(datetimeindex.freq)

# Convert to periods with monthly frequency
print("\nConvert DateTimeIndex to Period...")
print(datetimeindex.to_period(freq='M'))

# Calculate TimedeltaArray showing offset within each month
print("\nConvert DateTimeIndex to PeriodDelta...")
print(datetimeindex.to_perioddelta(freq='M'))

DateTimeIndex...
DatetimeIndex(['2021-12-31 07:20:32.261811624',
               '2023-12-31 07:20:32.261811624',
               '2025-12-31 07:20:32.261811624',
               '2027-12-31 07:20:32.261811624',
               '2029-12-31 07:20:32.261811624'],
              dtype='datetime64[ns]', freq='2A-DEC')

DateTimeIndex frequency...
<2 * YearEnds: month=12>

Convert DateTimeIndex to Period...
PeriodIndex(['2021-12', '2023-12', '2025-12', '2027-12', '2029-12'], dtype='period[M]')

Convert DateTimeIndex to PeriodDelta...
TimedeltaIndex(['30 days 07:20:32.261811624', '30 days 07:20:32.261811624',
                '30 days 07:20:32.261811624', '30 days 07:20:32.261811624',
                '30 days 07:20:32.261811624'],
               dtype='timedelta64[ns]', freq=None)

How It Works

The to_perioddelta() method works by:

1. Converting each datetime to its corresponding period (e.g., '2021-12')
2. Finding the start of that period (e.g., '2021-12-01 00:00:00')
3. Calculating the difference between the original datetime and period start
4. Returning a TimedeltaIndex showing these offsets

In this example, all dates are December 31st, so they're 30 days into their respective months.

Conclusion

Use to_perioddelta() to find how far into a period each datetime falls. This is useful for analyzing temporal patterns and calculating period-relative offsets in time series data.