How to Use Period in pandas for Time Series Data

In pandas, Period represents a time span like a month or year, not a single timestamp. You can create periods using pd.Period() and use PeriodIndex for indexing time series data by periods.

Syntax

The main syntax to create a period is pd.Period(value, freq), where value is a date string or timestamp and freq is the frequency like 'M' for month or 'A' for year.

For multiple periods, use pd.period_range(start, end, freq) to create a range of periods.

python

import pandas as pd

# Create a single period
p = pd.Period('2023-04', freq='M')

# Create a range of periods
periods = pd.period_range(start='2023-01', end='2023-04', freq='M')

Example

This example shows how to create a Period object and a PeriodIndex to index a DataFrame by months.

python

import pandas as pd

# Create a Period for April 2023
p = pd.Period('2023-04', freq='M')

# Create a PeriodIndex for 4 months
period_index = pd.period_range('2023-01', '2023-04', freq='M')

# Create a DataFrame indexed by periods
data = pd.DataFrame({'Sales': [200, 220, 250, 270]}, index=period_index)

print(p)
print(data)

Output

2023-04
        Sales
2023-01    200
2023-02    220
2023-03    250
2023-04    270

Common Pitfalls

• Using Period when you need exact timestamps can cause confusion because periods represent spans, not points in time.
• Mixing DatetimeIndex and PeriodIndex without conversion can lead to errors.
• For arithmetic, ensure periods have the same frequency.

python

import pandas as pd

# Wrong: mixing Period and Timestamp
try:
    p = pd.Period('2023-04', freq='M')
    ts = pd.Timestamp('2023-04-01')
    print(p + ts)  # This will raise an error
except Exception as e:
    print(f'Error: {e}')

# Right: convert Timestamp to Period first
p = pd.Period('2023-04', freq='M')
ts = pd.Timestamp('2023-04-01')
ts_period = ts.to_period('M')
print(p + 1)  # Next month
print(p == ts_period)  # True

Output

Error: unsupported operand type(s) for +: 'Period' and 'Timestamp'
2023-05
True

Quick Reference

Function	Description	Example
pd.Period(value, freq)	Create a single period	pd.Period('2023-04', freq='M')
pd.period_range(start, end, freq)	Create a range of periods	pd.period_range('2023-01', '2023-04', freq='M')
to_period(freq)	Convert Timestamp to Period	pd.Timestamp('2023-04-01').to_period('M')
PeriodIndex	Index DataFrame by periods	pd.period_range('2023-01', '2023-04', freq='M')

Key Takeaways

Use pd.Period to represent time spans like months or years, not exact timestamps.

Create multiple periods with pd.period_range for indexing time series data.

Avoid mixing Period and Timestamp types without conversion to prevent errors.

Period arithmetic requires matching frequencies for correct results.

PeriodIndex is useful for indexing pandas objects by time periods.