Understanding pandas.Series.to_period() method (5 examples)

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


The pandas.Series.to_period() method is a powerful tool in Python for time series data manipulation, allowing you to convert datetime-indexed Series to PeriodIndex. Understanding how to effectively use to_period() can significantly enhance your data analysis capabilities, especially when dealing with time series data. In this tutorial, we’ll dive deep into the to_period() method, explore its parameters, and illustrate its usage through five practical examples.

Syntax & Parameters

Before jumping into examples, let’s establish a basic understanding of what the to_period() method does. In essence, this method converts a DateTimeIndex Series to a PeriodIndex, which is useful for time series analysis that requires data to be in periodic intervals such as years, months, or days.

The method signature is:

Series.to_period(freq=None, copy=True)

Where freq specifies the frequency of the periods (e.g., ‘D’ for daily, ‘M’ for monthly, ‘A’ for annual), and copy indicates whether to return a copy of the original data (default is True).

Example 1: Basic Conversion

import pandas as pd
import numpy as np
# Create a datetime series
dates = pd.date_range('2023-01-01', periods=5)
data = np.random.random(5)
series = pd.Series(data, index=dates)
# Convert to period (monthly)
series_per = series.to_period('M')


2023-01    0.786988
2023-01    0.884697
2023-01    0.641237
2023-01    0.642814
2023-01    0.997440
Freq: M, dtype: float64

This example demonstrates how straightforward it is to convert a datetime-indexed series into a monthly period-indexed series.

Example 2: Analyzing Financial Data

import pandas as pd

# Assuming you have financial data indexed by date
financial_data = pd.Series(
    [100, 200, 150, 300, 250], index=pd.date_range("2023-04-01", periods=5, freq="D")
# Convert to quarterly period to analyze quarterly performance
series_quarter = financial_data.to_period("Q")


2023Q2    100
2023Q2    200
2023Q2    150
2023Q2    300
2023Q2    250
Freq: Q-DEC, dtype: int64

In this example, we convert daily financial data into a quarterly period to facilitate analysis of quarterly performance trends.

Example 3: Handling Missing Data

import pandas as pd
import numpy as np

missing_dates = pd.Series(
    [1, np.nan, 2, np.nan, 3], index=pd.date_range("2023-01-01", periods=5, freq="D")
# Convert to daily period, handling missing data
missing_period = missing_dates.to_period("D")


2023-01-01    1.0
2023-01-02    NaN
2023-01-03    2.0
2023-01-04    NaN
2023-01-05    3.0
Freq: D, dtype: float64

Here, we demonstrate how to_period() effortlessly handles Series with missing data, converting the datetime index into daily periods while preserving NaN values.

Example 4: Aggregating Monthly Sales Data

=import pandas as pd
import numpy as np

sales_data = pd.Series([500, 600, 700, 800, 900], index=pd.date_range('2023-02-01', periods=5, freq='D'))
# Convert data to a single month period for aggregation
monthly_sales = sales_data.to_period('M')


2023-02    3500
Freq: M, dtype: int64

In this example, we illustrate how to aggregate daily sales data into monthly sales data using to_period() and then summing up all entries within the same month.

Example 5: Shifting Periods for Forecasting

import pandas as pd
import numpy as np

forecast_data = pd.Series(
    [20, 40, 60, 80], index=pd.date_range("2023-03-01", periods=4)
# Convert and then shift periods forward for forecasting
forecast_period = forecast_data.to_period("M").asfreq("M", how="start").shift(1)


2023-03     NaN
2023-03    20.0
2023-03    40.0
2023-03    60.0
Freq: M, dtype: float64

Our final example shows how to leverage to_period() in conjunction with shift() and asfreq() methods to prepare data for time series forecasting, shifting the time period forward by one month.

While these examples only scratch the surface, they highlight the versatility and utility of pandas’ Series.to_period() method. Properly utilized, it can be an invaluable tool in your data analysis and time series manipulation toolkit.