Pandas pd.Timestamp() 函数

pd.Timestamp() 是 Pandas 库中用于创建时间戳的函数。它可以接受多种格式的日期时间输入，并返回一个精确的 Timestamp 对象。

Timestamp 是 Pandas 中用于表示单一时间点的数据类型，它是 Python 标准库 datetime.datetime 的增强版本，提供了更丰富的功能和更好的性能。

单词释义： Timestamp 意为"时间戳"，即表示某个具体的时刻。

基本语法与参数

pd.Timestamp() 是 Pandas 库的顶级函数，用于创建精确的时间戳对象。

语法格式

pd.Timestamp(year=None, month=None, day=None, hour=None, minute=None, second=None, microsecond=None, nanosecond=None, tzinfo=None, freq=None)
pd.Timestamp(value)

参数说明

参数	类型	是否必填	说明	默认值
value	字符串、datetime、int、float	可选	要转换的时间值。	None
year	整数	可选	年份（4位数字）。	None
month	整数	可选	月份（1-12）。	None
day	整数	可选	日期（1-31）。	None
hour	整数	可选	小时（0-23）。	None
minute	整数	可选	分钟（0-59）。	None
second	整数	可选	秒（0-59）。	None
microsecond	整数	可选	微秒（0-999999）。	None
nanosecond	整数	可选	纳秒（0-999999）。	None
tz	字符串或 tzinfo	可选	时区信息，如 'UTC'、'Asia/Shanghai'。	None

返回值说明

返回值：返回一个 Timestamp 对象，类似于 datetime.datetime。
效果：将各种格式的时间数据转换为精确的 Pandas 时间戳。

实例

让我们通过一系列从简单到复杂的例子，彻底掌握 pd.Timestamp() 的用法。

示例 1：基础用法 - 创建时间戳

实例

import pandas as pd

# 1. 使用字符串创建时间戳
print("=== 字符串创建时间戳 ===")
ts1 = pd.Timestamp('2023-01-01')
print(f"pd.Timestamp('2023-01-01'): {ts1}")

ts2 = pd.Timestamp('2023-01-01 12:30:45')
print(f"pd.Timestamp('2023-01-01 12:30:45'): {ts2}")

ts3 = pd.Timestamp('2023-05-15 08:00:00.123456')
print(f"带微秒: {ts3}")

# 2. 使用关键字参数创建时间戳
print("n=== 关键字参数创建 ===")
ts4 = pd.Timestamp(year=2023, month=6, day=15, hour=10, minute=30)
print(f"pd.Timestamp(year=2023, month=6, day=15, hour=10, minute=30): {ts4}")

# 3. 从 datetime 对象创建
print("n=== datetime 对象创建 ===")
import datetime
dt = datetime.datetime(2023, 8, 20, 14, 45, 30)
ts5 = pd.Timestamp(dt)
print(f"从 datetime 创建: {ts5}")

# 4. 查看时间戳的属性
print("n=== 时间戳属性 ===")
ts = pd.Timestamp('2023-03-15 10:30:45.123456')
print(f"时间戳: {ts}")
print(f"年份: {ts.year}")
print(f"月份: {ts.month}")
print(f"日期: {ts.day}")
print(f"小时: {ts.hour}")
print(f"分钟: {ts.minute}")
print(f"秒: {ts.second}")
print(f"微秒: {ts.microsecond}")
print(f"星期几 (0=周一): {ts.dayofweek}")
print(f"季度: {ts.quarter}")

运行结果:

=== 字符串创建时间戳 ===
pd.Timestamp('2023-01-01'): 2023-01-01 00:00:00
pd.Timestamp('2023-01-01 12:30:45'): 2023-01-01 12:30:45
带微秒: 2023-05-15 08:00:00.123456

=== 关键字参数创建 ===
pd.Timestamp(year=2023, month=6, day=15, hour=10, minute=30): 2023-06-15 10:30:00

=== datetime 对象创建 ===
从 datetime 创建: 2023-08-20 14:45:30

=== 时间戳属性 ===
时间戳: 2023-03-15 10:30:45.123456
年份: 2023
月份: 3
日期: 15
小时: 10
分钟: 30
秒: 45
微秒: 123456
星期几 (0=周一): 2
季度: 1

代码解析:

pd.Timestamp() 可以接受多种格式的输入，包括字符串、datetime 对象等。
时间戳提供了丰富的属性用于获取日期时间的各个部分。
dayofweek 返回 0-6，其中 0 表示周一。

示例 2：时区处理

实例

import pandas as pd

# 1. 创建带时区的时间戳
print("=== 创建带时区的时间戳 ===")
ts_utc = pd.Timestamp('2023-01-01 12:00:00', tz='UTC')
print(f"UTC 时区: {ts_utc}")

ts_shanghai = pd.Timestamp('2023-01-01 20:00:00', tz='Asia/Shanghai')
print(f"上海时区: {ts_shanghai}")

# 2. 不同时区之间的转换
print("n=== 时区转换 ===")
ts_utc = pd.Timestamp('2023-01-01 12:00:00', tz='UTC')
ts_local = ts_utc.tz_convert('Asia/Shanghai')
print(f"UTC 时间: {ts_utc}")
print(f"转换到上海: {ts_local}")

# 3. 创建本地时区的时间戳（无时区转带时区）
print("n=== 本地时间转带时区 ===")
ts_naive = pd.Timestamp('2023-01-01 12:00:00')
print(f"无时区: {ts_naive}")
ts_aware = ts_naive.tz_localize('Asia/Shanghai')
print(f"添加上海时区: {ts_aware}")

# 4. 使用 tz 参数的简写形式
print("n=== 时区简写 ===")
ts1 = pd.Timestamp('2023-01-01 12:00', tz='US/Eastern')
print(f"美国东部: {ts1}")
ts2 = pd.Timestamp('2023-01-01 12:00', tz='Europe/London')
print(f"伦敦: {ts2}")

运行结果:

=== 创建带时区的时间戳 ===
UTC 时区: 2023-01-01 12:00:00+00:00
上海时区: 2023-01-01 20:00:00+08:00

=== 时区转换 ===
UTC 时间: 2023-01-01 12:00:00+00:00
转换到上海: 2023-01-01 20:00:00+08:00

=== 本地时间转带时区 ===
无时区: 2023-01-01 12:00:00
添加上海时区: 2023-01-01 12:00:00+08:00

=== 时区简写 ===
美国东部: 2023-01-01 12:00:00-05:00
伦敦: 2023-01-01 12:00:00+00:00

代码解析:

tz_localize 用于将无时区的 Timestamp 添加时区信息。
tz_convert 用于在不同时区之间转换。

示例 3：时间戳的比较和运算

实例

import pandas as pd

# 1. 时间戳比较
print("=== 时间戳比较 ===")
ts1 = pd.Timestamp('2023-01-01')
ts2 = pd.Timestamp('2023-01-15')
ts3 = pd.Timestamp('2023-01-01')

print(f"ts1: {ts1}")
print(f"ts2: {ts2}")
print(f"ts1 < ts2: {ts1 < ts2}")
print(f"ts1 == ts3: {ts1 == ts3}")
print(f"ts1 != ts2: {ts1 != ts2}")

# 2. 时间戳与 Timedelta 运算
print("n=== 时间戳与时间差运算 ===")
ts = pd.Timestamp('2023-01-01 12:00:00')
td = pd.Timedelta(days=5, hours=3)

print(f"原时间戳: {ts}")
print(f"时间差: {td}")
print(f"ts + td: {ts + td}")
print(f"ts - td: {ts - td}")

# 3. 两个时间戳相减得到 Timedelta
print("n=== 两个时间戳相减 ===")
ts1 = pd.Timestamp('2023-01-15 18:00:00')
ts2 = pd.Timestamp('2023-01-10 09:00:00')

diff = ts1 - ts2
print(f"ts1: {ts1}")
print(f"ts2: {ts2}")
print(f"ts1 - ts2: {diff}")
print(f"天数: {diff.days}")
print(f"小时: {diff.seconds / 3600}")

# 4. 在 DataFrame 中使用时间戳
print("n=== DataFrame 中的时间戳 ===")
df = pd.DataFrame({
'event': ['event_a', 'event_b', 'event_c'],
'timestamp': [
pd.Timestamp('2023-01-01 10:00:00'),
pd.Timestamp('2023-01-02 15:30:00'),
pd.Timestamp('2023-01-03 09:45:00')
]
})
print(df)
print(f"n事件持续时间（相对于第一个事件）:")
df['relative_days'] = (df['timestamp'] - df['timestamp'].iloc[0]).dt.days
print(df)

运行结果:

=== 时间戳比较 ===
ts1: 2023-01-01 00:00:00
ts2: 2023-01-15 00:00:00
ts1 &lt; ts2: True
ts1 == ts3: True
ts1 != ts2: True

=== 时间戳与时间差运算 ===
原时间戳: 2023-01-01 12:00:00
时间差: 5 days 03:00:00
ts + td: 2023-01-06 15:00:00
ts - td: 2022-12-27 09:00:00

=== 两个时间戳相减 ===
ts1: 2023-01-15 18:00:00
ts2: 2023-01-10 09:00:00
ts1 - ts2: 5 days 09:00:00
天数: 5
小时: 9.0

=== DataFrame 中的时间戳 ===
        event           timestamp
0  event_a  2023-01-01 10:00:00
1  event_b  2023-01-02 15:30:00
2  event_c  2023-01-03 09:45:00

事件持续时间（相对于第一个事件）:
        event           timestamp  relative_days
0  event_a  2023-01-01 10:00:00             0
1  event_b  2023-01-02 15:30:00             1
2  event_c  2023-01-03 09:45:00             2

代码解析:

时间戳支持直接比较运算（, ==, !=）。
时间戳与 Timedelta 相加或相减会得到新的时间戳或时间差。
两个时间戳相减会得到 Timedelta 对象。
在 DataFrame 中可以方便地进行时间相关的计算。

注意事项

重要提示：

pd.Timestamp 类似于 Python 的 datetime，但提供了更高的性能和更多的方法。

时间戳对象是不可变的，修改操作会返回新的对象。

时区信息最好在创建时指定，后期修改时区可能产生歧义。

使用 pd.NaT（Not a Time）表示缺失的时间值。

Pandas 通用函数 Pandas 常用函数

返回顶部

菜鸟教程

Pandas pd.Timestamp() 函数

基本语法与参数

语法格式

参数说明

返回值说明

实例

示例 1：基础用法 - 创建时间戳

实例

示例 2：时区处理

实例

示例 3：时间戳的比较和运算

实例

注意事项