9.3 时间索引

说明

pandas 提供了三种与时间相关的索引类型：DatetimeIndex、TimedeltaIndex、PeriodIndex，它们支持时间切片、对齐、重采样等高级操作。其详细属性与方法见 3. Index。

DatetimeIndex

说明

由 datetime64 类型构成的时间索引，通常由 pd.date_range() 或 pd.to_datetime() 生成。

import pandas as pd
 
idx = pd.date_range('2026-08-01', periods=4, freq='D')
print(idx)
# DatetimeIndex(['2026-08-01', '2026-08-02', '2026-08-03', '2026-08-04'], dtype='datetime64[ns]', freq='D')
 
# 频率属性
print(idx.freq)            # <Day>
print(idx.freqstr)         # 'D'
print(idx.inferred_freq)   # 'D'（从数据推断频率）
print(idx.tz)              # None
print(idx.timezone)        # None（与 tz 相同）
 
# 日期组件属性（与 .dt 访问器对应）
print(idx.year)      # Index([2026, 2026, 2026, 2026])
print(idx.month)     # Index([8, 8, 8, 8])
print(idx.day)       # Index([1, 2, 3, 4])
print(idx.dayofweek) # Index([5, 6, 0, 1])
print(idx.dayofyear) # Index([213, 214, 215, 216])
print(idx.quarter)   # Index([3, 3, 3, 3])
print(idx.days_in_month)  # Index([31, 31, 31, 31])
print(idx.is_month_start) # array([True, False, False, False])
print(idx.is_year_start)  # array([False, False, False, False])
 
# 方法
print(idx.month_name())    # Index(['August', ...])
print(idx.day_name())      # Index(['Saturday', 'Sunday', 'Monday', 'Tuesday'])
print(idx.to_period('M'))  # PeriodIndex(['2026-08', ...], freq='M')
print(idx.to_pydatetime()) # 转 Python datetime 数组
print(idx.normalize())     # 时间归一到 0 点
print(idx.round('D'))      # 取整到日
print(idx.floor('D'))
print(idx.ceil('D'))
print(idx.strftime('%Y/%m/%d'))
print(idx.snap('MS'))      # 快照到最近的频率起点
print(idx.as_unit('s'))    # 转换精度单位

tz_localize 与 tz_convert

• tz_localize()：给无时区索引添加时区。
• tz_convert()：将有时区索引转换到其他时区。
• 详见 9.6 时区处理。

TimedeltaIndex

说明

由 timedelta64 类型构成的时间差索引，由 pd.to_timedelta() 或 pd.timedelta_range() 生成。

tdi = pd.to_timedelta(['1 days 02:00:00', '2 days 04:00:00', '3 days 06:00:00'])
print(tdi)
# TimedeltaIndex(['1 days 02:00:00', '2 days 04:00:00', '3 days 06:00:00'], dtype='timedelta64[ns]', freq=None)
 
# 属性
print(tdi.days)           # Index([1, 2, 3])
print(tdi.seconds)        # Index([7200, 14400, 21600])
print(tdi.microseconds)   # Index([0, 0, 0])
print(tdi.nanoseconds)    # Index([0, 0, 0])
print(tdi.components)     # DataFrame：days / hours / minutes / seconds / ...
print(tdi.total_seconds())  # Index([93600.0, 187200.0, 280800.0])
 
# 方法
print(tdi.to_pytimedelta())  # 转 Python timedelta 数组
print(tdi.round('h'))
print(tdi.floor('h'))
print(tdi.ceil('h'))

PeriodIndex

说明

由 period 类型构成的索引，表示等间距时间段，由 pd.period_range() 生成。

pidx = pd.period_range('2026-01', periods=4, freq='M')
print(pidx)
# PeriodIndex(['2026-01', '2026-02', '2026-03', '2026-04'], dtype='period[M]', freq='M')
 
# 属性
print(pidx.freq)            # <MonthEnd>
print(pidx.start_time)      # DatetimeIndex(['2026-01-01', '2026-02-01', ...])
print(pidx.end_time)        # DatetimeIndex(['2026-01-31', '2026-02-28', ...])
print(pidx.year, pidx.month, pidx.quarter)
print(pidx.day, pidx.hour, pidx.minute, pidx.second)
print(pidx.week, pidx.dayofweek, pidx.dayofyear)
print(pidx.days_in_month)   # Index([31, 28, 31, 30])
print(pidx.daysinmonth)     # 别名
 
# 方法
print(pidx.to_timestamp())             # 转 DatetimeIndex（默认区间起点）
print(pidx.to_timestamp(how='end'))    # 区间终点
print(pidx.tz_localize('UTC'))         # 本地化时区
print(pidx.tz_convert('Asia/Shanghai'))

频率字符串

说明

频率字符串是 pandas 时间序列的核心参数，用于 date_range()、resample()、to_period() 等场景。

别名	说明	别名	说明
D	日历日	B	工作日
W	每周（默认周日）	W-MON	每周一锚定
M	月末	MS	月初
BM	工作月末	BMS	工作月初
Q	季末（默认 12 月）	QS	季初
Q-DEC	12 月锚定季末	BQ / BQS	工作季末 / 工作季初
Y 或 A	年末	YS 或 AS	年初
Y-DEC	12 月锚定年末	BY / BYS	工作年末 / 工作年初
H	小时	T 或 min	分钟
S	秒	L 或 ms	毫秒
U 或 us	微秒	N	纳秒
ME	月末（pandas 2.2+ 推荐）	YE	年末（pandas 2.2+ 推荐）

# 频率倍数
print(pd.date_range('2026-01-01', periods=3, freq='2h'))
print(pd.date_range('2026-01-01', periods=3, freq='90min'))

频率字符串别名变更

pandas 2.2+ 将 M/Q/Y 等月末/季末/年末频率逐步迁移为 ME/QE/YE，建议新代码使用新别名。

时区处理

说明

时间索引支持时区信息，存储在 tz 属性中，dtype 形如 datetime64[ns, Asia/Shanghai]。

idx_utc = pd.date_range('2026-01-01', periods=3, freq='h', tz='UTC')
print(idx_utc.tz)   # datetime.timezone.utc
 
idx_cn = idx_utc.tz_convert('Asia/Shanghai')
print(idx_cn)
# DatetimeIndex(['2026-01-01 08:00:00+08:00', ...], dtype='datetime64[ns, Asia/Shanghai]', freq='h')

本地化与转换

说明

• 本地化（localize）：为无时区的时间数据指定时区，不改变墙钟时间。
• 转换（convert）：将已有时区的数据转换到目标时区，改变墙钟时间。

# 无时区索引
idx_naive = pd.date_range('2026-01-01 08:00', periods=2, freq='h')
 
# tz_localize：指定为 UTC（时间不变）
idx_utc = idx_naive.tz_localize('UTC')
# DatetimeIndex(['2026-01-01 08:00:00+00:00', ...], dtype='datetime64[ns, UTC]')
 
# tz_convert：转换到上海时区（时间 +8 小时）
idx_sh = idx_utc.tz_convert('Asia/Shanghai')
# DatetimeIndex(['2026-01-01 16:00:00+08:00', ...], dtype='datetime64[ns, Asia/Shanghai]')

🔗 相关链接

• 9.2 创建方法 - 生成三种时间索引
• 9.4 .dt 访问器 - 对 Series 提取时间组件
• 9.5 时间序列操作 - 基于时间索引的重采样与切片
• 9.6 时区处理 - 时区本地化与转换的完整说明