Using Timedelta and Period to create DateTime based indexes in Pandas

Last Updated : 31 Oct, 2025

Working with time is a common requirement in data analysis. Pandas provides powerful tools to handle different types of time-related data using:

  • Timestamp: a specific point in time (like 2025-10-01 10:30:00).
  • Period: a fixed span/interval of time (like a month, quarter, or year).
  • Timedelta: the duration or difference between two points in time.

These can also be used as indices in DataFrames, enabling time-based selection, filtering, and analysis.

Using Timestamp

A Timestamp is equivalent to Python’s datetime object and represents an exact moment in time.

Syntax:

pd.Timestamp('YYYY-MM-DD')

Example:

Python 
import pandas as pd
ts = pd.Timestamp('2018-06-02')
print(ts)

Output
2018-06-02 00:00:00

Explanation:

  • pd.Timestamp(): Creates a Pandas Timestamp object.
  • '2018-06-02': Input date string (ISO format is preferred).
  • The object represents June 2, 2018, at midnight.

Timestamps as Index

Timestamps become powerful when used as indexes, allowing Pandas to treat rows as points in time for time-based aggregation or filtering.

Python 
import pandas as pd

df = pd.DataFrame({
    'City': ['Lisbon', 'Parague', 'Macao', 'Venice'],
    'Event': ['Music', 'Poetry', 'Theatre', 'Comedy'],
    'Cost': [10000, 5000, 15000, 2000]
})

index_ = [
    pd.Timestamp('2018-06-01'),
    pd.Timestamp('2018-06-04'),
    pd.Timestamp('2018-06-07'),
    pd.Timestamp('2018-06-10')
]

df.index = index_
print(df)

Output
               City    Event   Cost
2018-06-01   Lisbon    Music  10000
2018-06-04  Parague   Poetry   5000
2018-06-07    Macao  Theatre  15000
2018-06-10   Venice   Comedy   2000

Output: Now we will see the type of dataframe index which is made up of individual timestamps.

Python 
print(type(df.index))

Output

24

Using Period

Unlike Timestamps, which represent a single instant, Periods represent an interval (like a month, year, or quarter).

Syntax:

pd.Period('YYYY-MM', freq='M')

Example:

Python 
import pandas as pd
pr = pd.Period('2018-06','Y')
print(pr)

Output
2018

Explanation: freq = 'Y' filters only the year part of the time.

Periods as Index

Periods are often used as indexes in time-series data to group or analyze data over consistent time intervals.

Python 
import pandas as pd

df = pd.DataFrame({
    'City': ['Lisbon', 'Parague', 'Macao', 'Venice'],
    'Event': ['Music', 'Poetry', 'Theatre', 'Comedy'],
    'Cost': [10000, 5000, 15000, 2000]
})

ind = [
    pd.Period('2018-02'),
    pd.Period('2018-04'),
    pd.Period('2018-06'),
    pd.Period('2018-10')
]

df.index = ind
print(df)
print(type(df.index))

Output
            City    Event   Cost
2018-02   Lisbon    Music  10000
2018-04  Parague   Poetry   5000
2018-06    Macao  Theatre  15000
2018-10   Venice   Comedy   2000
<class 'pandas.core.indexes.period....

Using Timedelta

A Timedelta represents the difference between two dates or times. This is useful when dealing with durations, shifts, or elapsed time.

Syntax:

pd.Timedelta('X days Y hours')

Example:

Python 
import pandas as pd
td = pd.Timedelta('5 days 3 hours')
print(td)

Output
5 days 03:00:00

Timedelta as Index

Python 
import pandas as pd

index_ = pd.timedelta_range(start='1 day', periods=4, freq='2D')

df = pd.DataFrame({
    'Task': ['Start', 'Check', 'Review', 'Finish'],
    'Status': ['Done', 'Pending', 'Done', 'Pending']
}, index=index_)

print(df)
print(type(df.index))

Output
          Task   Status
1 days   Start     Done
3 days   Check  Pending
5 days  Review     Done
7 days  Finish  Pending
<class 'pandas.core.indexes.timedeltas.TimedeltaIndex'>
Comment

Explore