Generating Dates: date_range & Periods

Often you need dates that are not in your data: a fixture calendar for a new season, one row for every day so that days without matches show up as zero, or a timeline of hourly ball-by-ball snapshots. Typing them by hand is impossible — pd.date_range generates them. Munna's notebook (video 09) starts the DateTime part exactly here: pd.date_range(start='01/01/2024', end='31/12/2024'), then tries periods= and different freq values.

Definition

pd.date_range() returns a DatetimeIndex of equally spaced dates or times. You describe the sequence with any three of start, end, periods (how many dates) and freq (the step, such as "D" day, "W" week, "ME" month end, "h" hour). A Period is different: it represents a whole span (e.g. March 2024) instead of a single instant.

• DatetimeIndex — an index made of Timestamps; you can use it as a DataFrame index, loop over it, or turn it into a column.
• Equally spaced — every gap equals freq (calendar-aware: "ME" always lands on the last day of each month).
• Any three — with start + end + freq pandas counts the periods itself; with start + end + periods it computes the spacing, like np.linspace.

Syntax

pd.date_range(start=None, end=None, periods=None, freq=None,
              tz=None, normalize=False, name=None, inclusive="both")
pd.period_range(start=None, end=None, periods=None, freq=None)
pd.Period("2024-03", freq="M")

Frequency aliases

Note (pandas 3): the old aliases "M", "Q", "Y"/"A", "H" and "T" were removed — they now raise ValueError: Invalid frequency. Use "ME", "QE", "YE", "h" and "min". (Munna's notebook already shows the 'H' is deprecated warning that led to this change.)

Example — start + end (daily)

days = pd.date_range(start="2024-03-22", end="2024-03-28")
print(days)
print(len(days), type(days).__name__)

DatetimeIndex(['2024-03-22', '2024-03-23', '2024-03-24', '2024-03-25',
               '2024-03-26', '2024-03-27', '2024-03-28'],
              dtype='datetime64[us]', freq='D')
7 DatetimeIndex

How it works: with no freq, the step is one calendar day, and both endpoints are included. The freq='D' at the end shows the step pandas used.

Example — start + periods + freq

print(pd.date_range("2024-03-22", periods=4, freq="W"))
print(pd.date_range("2024-03-22", periods=4, freq="2D"))
print(pd.date_range("2024-01-01", periods=3, freq="ME"))
print(pd.date_range("2024-01-01", periods=3, freq="MS"))
print(pd.date_range("2024-03-22 19:30", periods=4, freq="h"))

DatetimeIndex(['2024-03-24', '2024-03-31', '2024-04-07', '2024-04-14'], dtype='datetime64[us]', freq='W-SUN')
DatetimeIndex(['2024-03-22', '2024-03-24', '2024-03-26', '2024-03-28'], dtype='datetime64[us]', freq='2D')
DatetimeIndex(['2024-01-31', '2024-02-29', '2024-03-31'], dtype='datetime64[us]', freq='ME')
DatetimeIndex(['2024-01-01', '2024-02-01', '2024-03-01'], dtype='datetime64[us]', freq='MS')
DatetimeIndex(['2024-03-22 19:30:00', '2024-03-22 20:30:00',
               '2024-03-22 21:30:00', '2024-03-22 22:30:00'],
              dtype='datetime64[us]', freq='h')

How it works:

• "W" jumps to Sundays — the first Sunday on or after 22 March is 24 March.
• "ME" gives the last day of each month (29 Feb — 2024 is a leap year); "MS" gives the first.
• "h" steps one hour; times are kept.

Example — start + end + periods (like linspace)

print(pd.date_range(start="2024-01-01", end="2024-03-31", periods=3))

DatetimeIndex(['2024-01-01', '2024-02-15', '2024-03-31'], dtype='datetime64[us]', freq=None)

The three dates are spread evenly from start to end — the same idea as np.linspace. Here freq=None, because the gap (45 days) is computed, not a named frequency.

Example — business days and an IPL fixture grid

weekdays = pd.date_range("2024-04-01", "2024-04-10", freq="B")
print(weekdays.day_name().tolist())

fixtures = pd.DataFrame({"date": pd.date_range("2024-03-22", periods=5, freq="D")})
fixtures["match_no"] = range(1, 6)
fixtures["day"] = fixtures["date"].dt.day_name()
print(fixtures)

['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Monday', 'Tuesday', 'Wednesday']
        date  match_no       day
0 2024-03-22         1    Friday
1 2024-03-23         2  Saturday
2 2024-03-24         3    Sunday
3 2024-03-25         4    Monday
4 2024-03-26         5   Tuesday

"B" skips Saturdays and Sundays. A DatetimeIndex also has .day_name(), .month etc. directly (no .dt needed — .dt is only for Series).

Example — fill in missing days with reindex

A team's runs are recorded only on match days. To see every day (zeros on rest days), reindex onto a full date range:

runs = pd.Series([182, 166, 210], index=pd.to_datetime(["2024-03-24", "2024-03-27", "2024-03-29"]))
all_days = pd.date_range(runs.index.min(), runs.index.max(), freq="D")
print(runs.reindex(all_days, fill_value=0))

2024-03-24    182
2024-03-25      0
2024-03-26      0
2024-03-27    166
2024-03-28      0
2024-03-29    210
Freq: D, dtype: int64

Periods — whole months, quarters, years

p = pd.Period("2024-03", freq="M")
print(p, "|", p.start_time, "->", p.end_time)
print(pd.period_range("2024-03", periods=3, freq="M"))
dates = pd.Series(pd.to_datetime(["2024-03-22", "2024-04-14", "2024-05-26"]))
print(dates.dt.to_period("M"))
print(dates.dt.to_period("Q"))

2024-03 | 2024-03-01 00:00:00 -> 2024-03-31 23:59:59.999999
PeriodIndex(['2024-03', '2024-04', '2024-05'], dtype='period[M]')
0    2024-03
1    2024-04
2    2024-05
dtype: period[M]
0    2024Q1
1    2024Q2
2    2024Q2
dtype: period[Q-DEC]

How it works: a Period is a span: 2024-03 covers everything from 1 March 00:00 to 31 March 23:59:59.999999. dt.to_period("M") labels each date with its month — a handy key for grouping ("matches per month"). Note that for periods the monthly alias is still "M" (the "ME" rename only applies to date offsets / date_range).

Comparison — Timestamp vs Period vs DatetimeIndex

Common mistakes

• ❌ freq="M" or freq="H" in pandas 3 → ValueError. ✅ "ME" / "MS" and "h".
• ❌ Giving all four of start, end, periods, freq → ValueError. ✅ Exactly three.
• ❌ start="01/02/2024" meaning 1 Feb — pandas reads it as January 2. ✅ Use ISO strings "2024-02-01".
• ❌ Expecting "W" to start on the given date. ✅ It snaps to Sundays; use "7D" for "every 7 days from the start".

Interview tip

Q: Difference between freq="ME" and freq="MS"? A: "ME" generates month-end dates (31 Jan, 29 Feb, …), "MS" generates month-start dates (1 Jan, 1 Feb, …).