Understanding PeriodIndex in Pandas (6 examples)

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


Pandas is an open source, BSD-licensed library providing high-performance, easy-to-use data structures and data analysis tools for the Python programming language. Among its advanced features is PeriodIndex, which is incredibly useful for time series data. In this tutorial, we’re going to delve into PeriodIndex with 6 practical examples, showing its flexibility and power in handling time-based data.

What is PeriodIndex?

PeriodIndex represents a sequence of time periods, such as days, months, or years. It is especially useful for time series data where you need to work with periods rather than precise timestamps. This allows for more intuitive time series operations, where you can think of the data in terms of these larger time periods.

Example 1: Creating PeriodIndex

Let’s start with how to create a PeriodIndex. You can define a PeriodIndex from a list of strings or numbers, specifying the period frequency with the freq argument.

import pandas as pd

# Creating a PeriodIndex with monthly frequency
dates = pd.PeriodIndex(['2021-01', '2021-02', '2021-03'], freq='M')


PeriodIndex(['2021-01', '2021-02', '2021-03'], dtype='period[M]')

This creates a PeriodIndex representing the first three months of 2021.

Example 2: Creating a Series with PeriodIndex

Now that you know how to create a PeriodIndex, you might wonder how to use it with Pandas’ data structures. Here, we create a Series with a PeriodIndex.

sales = pd.Series([450, 350, 600], index=dates)


 2021-01    450
 2021-02    350
 2021-03    600
 Freq: M, dtype: int64

This demonstrates how you can associate data with each period in the index.

Example 3: Period Arithmetic

One useful feature of PeriodIndex is the ability to perform arithmetic with the periods. This can be useful for shifting data in time or creating sequences of periods.

# Adding a month to each period
next_month = dates + 1


PeriodIndex(['2021-02', '2021-03', '2021-04'], dtype='period[M]')

Shows how periods can be easily manipulated arithmetically.

Example 4: Resampling Time Series Data

PeriodIndex makes resampling time series data straightforward. Here’s how to aggregate monthly sales data into quarterly sales.

quarterly_sales = sales.resample('Q').sum()


2021Q1    1400
Freq: Q-DEC, dtype: int64

This example shows the ease with which you can resample and aggregate time series data using PeriodIndex.

Example 5: Converting Between Timestamp and Period

It’s common to need to convert between timestamps and periods. Pandas provides easy tools for this conversion, making working with time series data even more flexible.

# Converting a Timestamp index to a PeriodIndex
# Let's start with a timestamped series
df = pd.date_range('2021-01-01', periods=3, freq='M')
sales_timestamp = pd.Series([450, 350, 600], index=df)

# Now converting to a period
sales_period = sales_timestamp.to_period('M')


 2021-01    450
 2021-02    350
 2021-03    600
 Freq: M, dtype: int64

This showcases the straightforward nature of converting between period and timestamp representations.

Example 6: Handling Periods Across Multiple Dimensions

Advanced example involving multi-dimensional PeriodIndex. Here, we’ll demonstrate creating a multi-index DataFrame with period indices covering multiple dimensions.

multi_period_index = pd.PeriodIndex.from_product([[2021, 2022], ['Q1', 'Q2']], names=['year', 'quarter'])
data = [[450, 350], [600, 400], [500, 550], [700, 650]]
df = pd.DataFrame(data, index=multi_period_index, columns=['Sales', 'Returns'])


              Sales  Returns
 year quarter
 2021 Q1        450      350
      Q2        600      400
 2022 Q1        500      550
      Q2        700      650

This illustrates handling more complex data structures utilizing PeriodIndex.


In this tutorial, we explored the nuances of PeriodIndex in Pandas through six diverse examples, progressing from basic to more advanced use cases. As we’ve seen, PeriodIndex is immensely helpful for working with time series data, providing intuitive and efficient ways to represent and manipulate time periods. Its flexibility makes it essential for data scientists and analysts dealing with temporal data.