我的个人技术笔记

9.1 时间对象

4 min read

说明

pandas 中核心的时间对象有五种：Timestamp、Timedelta、Period、DateOffset 和 NaT，分别用于表示时刻、时间差、周期区间、日历偏移与缺失时间。

Timestamp

说明

表示单个时间戳，是 Python datetime.datetime 的 pandas 替代品，基于 numpy.datetime64 实现，支持高精度与向量化运算。

import pandas as pd
 
ts = pd.Timestamp('2026-08-19 13:05:30')
print(ts)
# 2026-08-19 13:05:30
 
# 属性
print(ts.year, ts.month, ts.day)      # 2026 8 19
print(ts.hour, ts.minute, ts.second)  # 13 5 30
print(ts.dayofweek, ts.dayofyear, ts.quarter)  # 2 231 3
 
# 方法
print(ts.to_pydatetime())   # 转 Python datetime
print(ts.strftime('%Y/%m/%d'))  # 2026/08/19
print(ts.timestamp())       # Unix 时间戳（浮点）
print(ts.to_period('M'))    # 2026-08

Timedelta

说明

表示时间差或持续时间，基于 numpy.timedelta64 实现，支持与 Timestamp 的加减运算。

td = pd.Timedelta(days=3, hours=5, minutes=30, seconds=15)
print(td)
# 3 days 05:30:15
 
# 属性
print(td.days)              # 3
print(td.seconds)           # 19815（当天内的秒数）
print(td.microseconds)      # 0
print(td.nanoseconds)       # 0
print(td.components)        # Components(days=3, hours=5, minutes=30, seconds=15, ...)
print(td.total_seconds())   # 286215.0（总秒数）
 
# 方法
print(td.to_pytimedelta())  # 转 Python timedelta
print(td.round('h'))        # 3 days 05:00:00
print(td.floor('h'))        # 3 days 05:00:00
print(td.ceil('h'))         # 3 days 06:00:00

Period

说明

表示固定频率的时间区间（如一个月、一个季度、一年），比 Timestamp 更适合周期类数据分析，且支持频率感知的算术运算。

p = pd.Period('2026-08', freq='M')
print(p)
# 2026-08
 
# 属性
print(p.freq)               # <MonthEnd>
print(p.start_time)         # 2026-08-01 00:00:00
print(p.end_time)           # 2026-08-31 23:59:59.999999999
print(p.year, p.month, p.quarter)   # 2026 8 3
print(p.day, p.hour, p.minute, p.second)  # 31 23 59 59（区间末端组件）
print(p.week, p.dayofweek, p.dayofyear)   # 35 2 231（示例值）
print(p.days_in_month)      # 31
 
# 方法
print(p.to_timestamp())     # 2026-08-01 00:00:00
 
# 频率感知算术
print(p + 1)                # 2026-09
print(p - 3)                # 2026-05

Period 与 Timestamp 区别

  • Timestamp：时间轴上的一个点。
  • Period：时间轴上的一段区间，加减运算自动处理频率边界（如月份长度差异）。

DateOffset

说明

表示日历相关的偏移量，遵循日历规则（如月末、工作日、节假日），与 Timedelta 的固定长度有本质区别。

from pandas.tseries.offsets import DateOffset
 
# 月份偏移：1 月 31 日加 1 个月自动落到 2 月末
print(pd.Timestamp('2026-01-31') + DateOffset(months=1))
# 2026-02-28 00:00:00
 
# 组合偏移
offset = DateOffset(years=1, months=2, days=3, hours=4)
print(pd.Timestamp('2026-08-19 13:05:00') + offset)
# 2027-10-22 17:05:00
 
# DateOffset 也用于固定频率（如每小时、每 90 分钟）
print(pd.Timestamp('2026-08-19') + DateOffset(hours=90))
# 2026-08-23 18:00:00

DateOffset 与 Timedelta

  • Timedelta 是绝对时长：1 天 恒为 86400 秒。
  • DateOffset 是日历时长：1 个月 可能是 28、29、30 或 31 天。

NaT

说明

NaT（Not a Time）是时间序列中的缺失值标识，相当于数值数据中的 NaN，用于 Timestamp、DatetimeIndex、Timedelta 等时间数据。

print(pd.NaT)                     # NaT
print(pd.isna(pd.NaT))            # True
print(pd.isna(pd.Timestamp('2026-01-01')))   # False
 
# 在 Series 中识别缺失时间
s = pd.Series([pd.Timestamp('2026-01-01'), pd.NaT, None])
print(pd.isna(s))
# 0    False
# 1     True
# 2     True
# dtype: bool
 
# 缺失值在运算中传播
print(pd.Timestamp('2026-01-01') + pd.NaT)   # NaT
print(pd.Timedelta(days=1) + pd.NaT)         # NaT

注意

pd.NaT 的 == 比较返回 False（与 np.nan 行为一致），判断缺失必须使用 pd.isna() / pd.notna()。

🔗 相关链接

Graph View

Backlinks