Periods and Period Arithmetic

Timestamps vs periods

A Timestamp is an instant — one exact point in time. A Period is a span — “the whole month of March 2024” or “fiscal Q4 2024.” Payroll, budgeting, and reporting usually think in periods, not instants, so pandas gives Period its own type instead of forcing you to fake spans with pairs of timestamps.

A single Period

import pandas as pd
 
p = pd.Period("2024", freq="Y-DEC")
print(p)  # the whole year 2024

Period arithmetic

Adding or subtracting an integer shifts the period by that many units of its own frequency — no need to think in days:

Shifting periods

print(p + 5)   # 2029
print(p - 2)   # 2022
 
q1 = pd.Period("2024", freq="Y-DEC")
q2 = pd.Period("2027", freq="Y-DEC")
print(q2 - q1)  # <3 * YearEnds: month=12>

Subtracting two periods of the same frequency gives you the number of periods between them — like subtracting two dates gives you a timedelta.

PeriodIndex and period_range

A range of periods

periods = pd.period_range("2024-01", "2024-06", freq="M")
print(periods)
 
ts = pd.Series(range(6), index=periods)
print(ts)

Converting frequency with asfreq

asfreq re-expresses a period at a different granularity. Since a year contains months, you must say whether you want the start or end sub-period:

asfreq: start vs end

p = pd.Period("2024", freq="Y-JUN")  # fiscal year ending in June
 
print(p.asfreq("M", how="start"))  # 2023-07 — the fiscal year begins in July
print(p.asfreq("M", how="end"))    # 2024-06 — and ends in June

Quarterly periods

Quarterly reporting is usually anchored to a fiscal year end. Q-DEC means quarters line up with a December year end (a normal calendar quarter):

Quarterly period

q = pd.Period("2024Q4", freq="Q-DEC")
print(q)
print(q.asfreq("D", how="start"))  # first day of the quarter
print(q.asfreq("D", how="end"))    # last day of the quarter

Converting timestamps to periods (and back)

to_period / to_timestamp

dates = pd.date_range("2024-01-01", periods=3, freq="ME")
ts = pd.Series(range(3), index=dates)
 
pts = ts.to_period()          # timestamps -> periods
print(pts)
 
print(pts.to_timestamp())     # periods -> timestamps (start of period, by default)

Common pitfalls

• A timestamp belongs to exactly one period for a given frequency — but the same period can repeat (e.g. two dates in January both map to 2024-01).
• Period("Aug-2011", "M").asfreq("A-JUN") maps August into the next fiscal year — frequency conversion depends on where the fiscal year boundary falls, not just the date.
• to_timestamp() returns the start of the period unless you pass how="end".

Visualize it

diagram Timestamp vs Period vs frequency conversion mermaid

  flowchart LR
  A["Timestamp
'2024-03-15 10:00'"] -->|"to_period()"| B["Period('2024-03', 'M')
the whole month"]
  B -->|"asfreq('D', how='start')"| C["First day: 2024-03-01"]
  B -->|"asfreq('D', how='end')"| D["Last day: 2024-03-31"]
  B -->|"asfreq('Y-DEC')"| E["Period('2024', 'Y-DEC')
the whole year"]

A Timestamp is a single instant; a Period is a whole span; asfreq re-expresses that span at a different granularity.

From the book

McKinney describes Period("2011", "A-DEC") as a “cursor pointing to a span of time.” Frequency conversion with asfreq doesn’t move that cursor — it just zooms in (to months, days) or out (to years) while staying anchored to the same span. This is why how="start" vs how="end" matters so much when zooming in: a year has many possible months, so you must say which one you mean.

🧪 Try It Yourself

Exercise 1 – Shift a Period by Integer Arithmetic

pch.exerciseTag pch.exerciseTitle

Exercise 2 – Build a Monthly PeriodIndex

pch.exerciseTag pch.exerciseTitle

Exercise 3 – Convert a Year Period Down to Its Start Month

pch.exerciseTag pch.exerciseTitle

Next

Periods describe fixed spans — Resampling and Frequency Conversion shows how to actually convert an irregular or high-frequency series into those spans, with real aggregation.