pandas pd.to_datetime() 转换为时间类型

看过来

《pandas 教程》持续更新中，提供建议、纠错、催更等加作者微信: gairuo123（备注：pandas教程）和关注公众号「盖若」ID: gairuo。跟作者学习，请进入 Python学习课程。欢迎关注作者出版的书籍：《深入浅出Pandas》和《Python之光》。

pandas.to_datetime 是一个非常强大的函数，用于将各种类型的日期或时间数据转换为 pandas.Timestamp 对象（即 pandas 的 datetime 数据类型）。这是进行时间序列分析的基础步骤之一。

数据类型支持

pandas.to_datetime 支持以下几种数据类型：

字符串：可以是单个日期字符串，也可以是一个日期字符串的列表或 Series。
整数或浮点数：表示 Unix 时间戳（1970年1月1日以来的秒数）。
datetime-like 对象：例如 datetime.datetime，datetime.date。
DataFrame：具有包含年、月、日等列的 DataFrame 可以转换为 datetime。

语法

pandas.to_datetime(
    arg,
    errors='raise',
    dayfirst=False,
    yearfirst=False,
    utc=False,
    format=None,
    exact=pandas._libs.lib.NoDefault.no_default,
    unit=None,
    infer_datetime_format=pandas._libs.lib.NoDefault.no_default,
    origin='unix',
    cache=True
)

参数意义

arg：要转换为 datetime 的数据。可以是单个字符串、列表、Series、整数、浮点数或 DataFrame 以及 dict-like。
- 如果提供了DataFrame，则该方法至少需要以下列：“year”、“month”、“day”。“年份”列必须以4位数字格式指定。
errors：指定如何处理无法解析的日期数据。
- 'raise'（默认）：遇到错误时抛出异常。
- 'coerce'：无法解析的数据会被转换为 NaT。
- 'ignore'：返回输入数据，不进行任何转换。
dayfirst：布尔值，指定日期解析时是否将第一个值视为天。默认为 False，即第一个值视为月。如果为True，则解析日期时以日开头，例如“10/11/12”解析为2012-11-10。
yearfirst：布尔值，指定日期解析时是否将第一个值视为年。默认为 False。
- 如果True解析日期时首先使用年份，例如“10/11/12”解析为2010-11-12。
- 如果dayfirst和yearfirst都为True，则yearfirst前面有（与dateutil相同）。
utc：布尔值，指定是否将输出时间设置为 UTC 时间。默认为 False。
format：字符串，指定解析日期时间的格式。例如，'%d/%m/%Y' 表示日期格式为 "日/月/年"。
exact：布尔值，指定是否要求日期字符串与格式严格匹配。默认为 True。
unit：字符串，指定输入数据的时间单位。常用单位包括 's'（秒）、'ms'（毫秒）、'us'（微秒）等。
infer_datetime_format：布尔值，指定是否要自动推断日期时间格式以提高解析速度。默认为 False。
- 自2.0.0版本起弃用：此参数的严格版本现在是默认值，传递它无效。
origin：指定 Unix 时间戳的起始点。默认值为 'unix'（1970-01-01），也可以是 'julian' 或者一个具体的日期。
cache：布尔值，指定是否缓存转换结果，以提高速度。默认为 True。

返回值

返回值是一个 pandas.DatetimeIndex 或 pandas.Series，具体取决于输入的类型。如果输入是单个日期字符串，则返回 Timestamp。

示例讲解

处理各种输入格式：

从DataFrame的多列组装日期时间。这些键可以是常见的缩写，如 [‘year’, ‘month’, ‘day’, ‘minute’, ‘second’, ‘ms’, ‘us’, ‘ns’] ，也可以是相同的复数形式。

df = pd.DataFrame({'year': [2015, 2016],
                   'month': [2, 3],
                   'day': [4, 5]})
pd.to_datetime(df)
'''
0   2015-02-04
1   2016-03-05
dtype: datetime64[ns]
'''

使用unix纪元时间:

pd.to_datetime(1490195805, unit='s')
# Timestamp('2017-03-22 15:16:45')
pd.to_datetime(1490195805433502912, unit='ns')
# Timestamp('2017-03-22 15:16:45.433502912')

警告：对于浮点数arg，可能会进行精确四舍五入。为了防止意外行为，请使用固定宽度的精确类型。

使用非unix纪元原点：

pd.to_datetime([1, 2, 3], unit='D',
               origin=pd.Timestamp('1960-01-01'))
'''
DatetimeIndex(['1960-01-02', '1960-01-03', '1960-01-04'],
              dtype='datetime64[ns]', freq=None)
'''

与 strptime 行为的差异：

“%f”将一直解析到纳秒。

pd.to_datetime('2018-10-26 12:00:00.0000000011',
               format='%Y-%m-%d %H:%M:%S.%f')
# Timestamp('2018-10-26 12:00:00.000000001')

不可转换的日期/时间:

除了将非日期（或不可解析的日期）强制为NaT之外，传递 errors='erce' 还将强制为NaT-一个越界日期。

pd.to_datetime('13000101', format='%Y%m%d', errors='coerce')
# NaT

时区和时间偏移:

默认行为（utc=False）如下：

时区初始输入转换为时区初始DatetimeIndex：

pd.to_datetime(['2018-10-26 12:00:00', '2018-10-26 13:00:15'])
'''
DatetimeIndex(['2018-10-26 12:00:00', '2018-10-26 13:00:15'],
              dtype='datetime64[ns]', freq=None)
'''

具有恒定时间偏移的时区感知输入转换为时区感知DatetimeIndex：

pd.to_datetime(['2018-10-26 12:00 -0500', '2018-10-26 13:00 -0500'])
'''
DatetimeIndex(['2018-10-26 12:00:00-05:00', '2018-10-26 13:00:00-05:00'],
              dtype='datetime64[ns, UTC-05:00]', freq=None)
'''

但是，具有混合时间偏移的时区感知输入（例如从具有夏令时的时区发出，如欧洲/巴黎）无法成功转换为DatetimeIndex。除非utc=True，否则解析混合时区的日期时间将显示警告。如果指定utc=False，将显示以下警告，并返回一个包含datetime.datetime对象的简单索引：

pd.to_datetime(['2020-10-25 02:00 +0200',
                '2020-10-25 04:00 +0100'])  
'''
FutureWarning: In a future version of pandas, parsing datetimes with mixed
time zones will raise an error unless `utc=True`. Please specify `utc=True`
to opt in to the new behaviour and silence this warning. To create a `Series`
with mixed offsets and `object` dtype, please use `apply` and
`datetime.datetime.strptime`.
Index([2020-10-25 02:00:00+02:00, 2020-10-25 04:00:00+01:00],
      dtype='object')
'''

时区感知和时区无关输入的组合也被转换为包含datetime.datetime对象的简单索引：

from datetime import datetime
pd.to_datetime(["2020-01-01 01:00:00-01:00",
                datetime(2020, 1, 1, 3, 0)])  
'''
FutureWarning: In a future version of pandas, parsing datetimes with mixed
time zones will raise an error unless `utc=True`. Please specify `utc=True`
to opt in to the new behaviour and silence this warning. To create a `Series`
with mixed offsets and `object` dtype, please use `apply` and
`datetime.datetime.strptime`.
Index([2020-01-01 01:00:00-01:00, 2020-01-01 03:00:00], dtype='object')
'''

设置utc=True可以解决上述大部分问题：

时区初始输入本地化为UTC

pd.to_datetime(['2018-10-26 12:00', '2018-10-26 13:00'], utc=True)
'''
DatetimeIndex(['2018-10-26 12:00:00+00:00', '2018-10-26 13:00:00+00:00'],
              dtype='datetime64[ns, UTC]', freq=None)
'''

时区感知输入转换为UTC（输出表示完全相同的日期时间，但从UTC时间偏移+00:00查看）。

pd.to_datetime(['2018-10-26 12:00 -0530', '2018-10-26 12:00 -0500'],
               utc=True)
'''
DatetimeIndex(['2018-10-26 17:30:00+00:00', '2018-10-26 17:00:00+00:00'],
              dtype='datetime64[ns, UTC]', freq=None)
'''

输入可以包含字符串或日期时间，上述规则仍然适用:

pd.to_datetime(['2018-10-26 12:00', datetime(2020, 1, 1, 18)], utc=True)
'''
DatetimeIndex(['2018-10-26 12:00:00+00:00', '2020-01-01 18:00:00+00:00'],
              dtype='datetime64[ns, UTC]', freq=None)
'''

使用场景与例子

场景 1：简单的日期字符串转换

import pandas as pd

# 示例数据
date_str = "2024-08-10"

# 转换为 Timestamp
result = pd.to_datetime(date_str)

print(result)

输出：

'''
2024-08-10 00:00:00
'''

场景 2：日期字符串列表转换

import pandas as pd

# 示例数据
date_list = ["2024-08-10", "2023-07-15", "2022-06-20"]

# 转换为 DatetimeIndex
result = pd.to_datetime(date_list)

print(result)

输出：

'''
DatetimeIndex(['2024-08-10', '2023-07-15', '2022-06-20'], 
	dtype='datetime64[ns]', freq=None)
'''

场景 3：解析包含格式的日期字符串

import pandas as pd

# 示例数据
date_str = "10/08/2024"

# 使用 format 参数指定日期格式
result = pd.to_datetime(date_str, format="%d/%m/%Y")

print(result)

输出：

'''
2024-08-10 00:00:00
'''

场景 4：处理 Unix 时间戳

import pandas as pd

# 示例数据
timestamp = 1691606400  # Unix 时间戳表示 2023-08-10 00:00:00

# 转换为 Timestamp
result = pd.to_datetime(timestamp, unit='s')

print(result)

输出：

'''
2023-08-10 00:00:00
'''

场景 5：处理 DataFrame 中的日期列

import pandas as pd

# 示例数据
data = {
    "year": [2024, 2023, 2022],
    "month": [8, 7, 6],
    "day": [10, 15, 20]
}
df = pd.DataFrame(data)

# 转换为 datetime
result = pd.to_datetime(df)

print(result)

输出：

'''
0   2024-08-10
1   2023-07-15
2   2022-06-20
dtype: datetime64[ns]
'''

通过以上场景和例子，我们可以看到 pandas.to_datetime 的灵活性和强大功能。它能够处理各种类型的输入，并支持多种参数来满足不同的需求。

参考

https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html