Pandas DataFrame.to_period() method: Explained with examples

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


Pandas is a versatile and powerful data manipulation and analysis library for Python. Among its numerous methods, to_period() is a method that often flies under the radar despite its utility in time series analysis. This method is specifically useful when dealing with data indexed by timestamps, allowing users to convert these timestamps into periods which can be more meaningful for certain types of analysis. In this article, we will explore the to_period() method in-depth, providing examples that illustrate its functionality from basic usage to more advanced applications.

Understanding DataFrame.to_period()

to_period() converts the DateTimeIndex of a DataFrame into PeriodIndex, which represents time intervals. The method is especially useful in financial and economic analysis, where one often deals with quarterly, monthly, or annual data. A period can be thought of as a span of time (e.g., a month, quarter, or year) rather than a precise point in time, making analysis at these broader timeframes more intuitive.

Basic Example

import pandas as pd

# Create a DataFrame with DateTimeIndex
df = pd.DataFrame({
    'value': [10, 20, 30, 40],
}, index=pd.to_datetime(['2021-01-01', '2021-03-01', '2021-05-01', '2021-07-01']))

# Convert DateTimeIndex to PeriodIndex with monthly frequency
df_period = df.to_period('M')


The output:

2021-01    10
2021-03    20
2021-05    30
2021-07    40

In this basic example, the DateTimeIndex of the original DataFrame is converted into PeriodIndex with a monthly frequency, as indicated by the ‘M’ parameter. The representation changes such that it reflects periods (in this case, months) instead of specific dates, providing a more generalized view of the data.

Handling Quarterly Data

import pandas as pd

# Quarterly data example
df_quarter = pd.DataFrame({
    'revenue': [100, 150, 200, 250],
}, index=pd.to_datetime(['2021-01-01', '2021-04-01', '2021-07-01', '2021-10-01']))

# Convert to quarterly period
df_quarter_period = df_quarter.to_period('Q')


The output:

2021Q1      100
2021Q2      150
2021Q3      200
2021Q4      250

This example demonstrates the utility in converting timestamp-indexed data into a period-indexed format when dealing with quarterly data. Each row now represents a financial quarter, making the dataset more aligned with how financial data is typically analyzed and reported.

Aggregating Monthly Data to Annual Data

Sometimes, data are available in a more granular format than needed. The to_period() method can be instrumental in aggregating this data. Below is an example of how to aggregate monthly data into annual data using this method:

import pandas as pd
import numpy as np

# Monthly data to be aggregated to annual
df_monthly = pd.DataFrame({
    'sales': np.random.randint(10, 100, size=24),
}, index=pd.date_range(start='2020-01-01', periods=24, freq='M'))

df_annual = df_monthly.to_period('A')


Note that aggregating data in this way does not sum or modify the underlying data; rather, it changes the indices to reflect annual periods. Further aggregation or summarization methods would be required to consolidate the data values themselves across the new period indices.

Advanced Techniques

Moving beyond straightforward conversions, to_period() can be combined with Pandas’ other functionality to perform more complex time series analyses. Let’s dive deeper into some of these advanced applications.

Period Rolling Windows

When paired with rolling window calculations, the to_period() method shines in its ability to provide insights into trends over specified periods. Here is how you can implement a rolling average over annual periods:

import pandas as pd

# Example DataFrame with monthly data
df = pd.DataFrame({
    'value': np.random.poisson(10, 48),
}, index=pd.date_range(start='2018-01-01', periods=48, freq='M'))

# Convert to annual periods and compute rolling average
df_period = df.to_period('A').rolling(window=2).mean()


Here, we converted the original monthly data into annual periods, then applied a rolling window of 2 periods to calculate the mean. This example showcases how to_period() can enhance time series analysis by allowing rolling calculations across periods, which can be more informative for identifying longer-term trends.


As demonstrated through these examples, the to_period() method in Pandas provides invaluable functionality for time series analysis. It bridges the gap between precise point-in-time data and broader time intervals, allowing for more nuanced and insightful analysis of temporal data. Whether you’re working with financial quarters, monthly sales data, or any other time-stamped dataset, to_period() can help you view and analyze your data in the periods that matter most to your analysis.