date_range и временной индекс — pandas

Коротко

pd.date_range(start, end) или pd.date_range(start, periods=n, freq=…) — последовательность дат.
Частота freq: D — день, h — час, min — минута, W-MON — по понедельникам, ME — конец месяца, MS — начало месяца, QE, YE — конец квартала и года, B — рабочий день. Число впереди — шаг: 2h, 15min.
С датами в индексе (DatetimeIndex) можно выбирать строкой: s.loc["2024-03"] — весь март, s.loc["2024-03-01":"2024-03-10"] — диапазон с концом включительно.
У индекса есть те же части, что у .dt: index.month, index.dayofweek.
period_range — периоды (целый месяц, квартал), а не моменты времени.

Синтаксис

pd.date_range(start=None, end=None, periods=None, freq="D")
pd.bdate_range(start, end)          # рабочие дни
s.loc["2024-03"], s.loc["2024-03-01":"2024-03-10"]
s.index.dayofweek, s.index.month

Параметры

ПараметрЧто делаетПо умолчанию

start, endначало и конец; можно задать одно из них и periodsNone

periodsсколько датNone

freqшаг: "D", "h", "min", "W-MON", "ME", "MS", "QE", "YE", "B"…"D"

inclusiveвключать ли границы: "both", "left", "right", "neither""both"

Примеры

Данные для примеровиспользуются во всех примерах ниже

days = pd.date_range("2024-02-26", periods=10, freq="D")
visits = pd.Series([120, 135, 128, 150, 162, 90, 85, 140, 155, 149], index=days)

Дни от и до

pd.date_range("2024-03-01", "2024-03-05")        # по дням от и до

Вывод

DatetimeIndex(['2024-03-01', '2024-03-02', '2024-03-03', '2024-03-04',
               '2024-03-05'],
              dtype='datetime64[us]', freq='D')

Разные частоты

print(pd.date_range("2024-01-01", periods=4, freq="W-MON"))   # по понедельникам
print(pd.date_range("2024-01-01", periods=3, freq="ME"))      # концы месяцев
pd.date_range("2024-03-01 09:00", periods=3, freq="2h")       # каждые 2 часа

Вывод

DatetimeIndex(['2024-01-01', '2024-01-08', '2024-01-15', '2024-01-22'], dtype='datetime64[us]', freq='W-MON')
DatetimeIndex(['2024-01-31', '2024-02-29', '2024-03-31'], dtype='datetime64[us]', freq='ME')
DatetimeIndex(['2024-03-01 09:00:00', '2024-03-01 11:00:00',
               '2024-03-01 13:00:00'],
              dtype='datetime64[us]', freq='2h')

Series с датами в индексе

visits

Вывод

2024-02-26    120
2024-02-27    135
2024-02-28    128
2024-02-29    150
2024-03-01    162
2024-03-02     90
2024-03-03     85
2024-03-04    140
2024-03-05    155
2024-03-06    149
Freq: D, dtype: int64

Выбор месяца и диапазона строкой

print(visits.loc["2024-03"])                     # весь март
visits.loc["2024-02-28":"2024-03-01"]            # диапазон дат, конец включён

Вывод

2024-03-01    162
2024-03-02     90
2024-03-03     85
2024-03-04    140
2024-03-05    155
2024-03-06    149
Freq: D, dtype: int64
2024-02-28    128
2024-02-29    150
2024-03-01    162
Freq: D, dtype: int64

Выбор по дню недели

visits[visits.index.dayofweek >= 5]              # только выходные

Вывод

2024-03-02    90
2024-03-03    85
Freq: D, dtype: int64

Рабочие дни

pd.bdate_range("2024-03-01", "2024-03-12")       # рабочие дни

Вывод

DatetimeIndex(['2024-03-01', '2024-03-04', '2024-03-05', '2024-03-06',
               '2024-03-07', '2024-03-08', '2024-03-11', '2024-03-12'],
              dtype='datetime64[us]', freq='B')

Периоды

pd.period_range("2024-01", periods=3, freq="M")  # периоды: месяц целиком, а не момент

Вывод

PeriodIndex(['2024-01', '2024-02', '2024-03'], dtype='period[M]')

Подводные камни

Старые обозначения частот

freq='M' в date_rangeошибка: ValueError

pd.date_range("2024-01-01", periods=3, freq="M")

Ошибка

ValueError: Invalid frequency: M. Failed to parse with error message: ValueError("'M' is no longer supported for offsets. Please use 'ME' instead.")