pandas 0.8.0 版本深度解析datetime64 时间序列架构革命与迁移指南【免费下载链接】pandasFlexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more项目地址: https://gitcode.com/gh_mirrors/pa/pandas导读pandas 0.8.02012 年 6 月 29 日发布是该库发展史上的一个里程碑式版本它把时间序列数据从 Python 内建datetime.datetime对象数组全面迁移到 NumPy 的datetime64dtype并据此重建了整套时间序列处理与加工基础设施同时引入了DatetimeIndex、PeriodIndex、Timestamp、灵活的resample重采样、时区处理等核心 API。本文以发布说明 doc/source/whatsnew/v0.8.0.rst 为主体结合当前仓库中对应源码实现系统梳理该版本的架构变化、新功能清单、绘图能力升级以及面向 0.7.3 及更早版本用户的完整移植指南帮助你理解 pandas 时间序列 API 的演化脉络与底层设计逻辑。版本概览一次“大版本”跃迁0.8.0 是从 0.7.3 升级而来的 major release发布说明明确指出本次发布包含超过 700 个 commit来自 20 余位作者时间序列处理与加工基础设施被大规模重写全库范围内新增了大量功能。升级兼容性方面发布说明给出了谨慎的预期大多数 0.7.3 及更早版本的用户不应遇到升级问题但由于数据表示迁移到了 NumPy 的datetime64dtype仍可能潜伏着一些 bug 和不兼容点。官方承诺这些遗留问题会在 0.8.1 中尽快修复同时面向仍在使用旧版 NumPy 1.6的用户0.7.x 系列会继续提供 bug 修复但不再进行任何新功能开发。完整的问题清单可参见仓库中的 doc/source/whatsnew/index.rst。值得注意的是文档中还预告了 0.8.0 章节末尾附有一份面向 0.7 及更早用户“移植指南”Porting Guide这是本次升级最重要的实操文档下文会专门展开。两大架构级变更支持非唯一索引Non-unique Indexes0.8.0 起所有对象都可以使用非唯一索引。数据对齐alignment与 join 操作遵循 SQL join 语义在多对多many-to-manyjoin 时允许索引重复。这一特性在今天的仓库中体现为索引基础属性is_unique其底层实现在 pandas/_libs/index.pyx对应的类型声明见 pandas/_libs/index.pyi。正如发布说明在移植指南中所提醒的如果旧代码曾用try...except包裹“索引不唯一时报错”的逻辑升级后这类异常在多数情况下不会再触发append等个别方法仍会校验唯一性除非显式禁用。此时应检查index.is_unique在返回False时显式抛异常或转入不同代码分支。NumPy datetime64 dtype 与 NumPy 1.6 依赖0.8.0 是 pandas 数据表示的分水岭时间序列数据改用NumPy 的datetime64dtype表示pandas 0.8.0要求至少 NumPy 1.6同时已针对 NumPy 1.7当时的开发版本做了测试验证该版本包含一些显著的 API 变更文档明确提示NumPy 1.6 在纳秒分辨率数据上存在若干 bug建议尽量避开其datetime64API 函数虽然功能有限只通过 pandas 提供的接口与该类型数据交互。该迁移带来了三个直接收益显著加速 join 操作与数据对齐、降低内存占用、大幅提升序列化/反序列化性能对比旧的datetime.datetime表示。时间序列功能与底层实现全面升级高性能、灵活的 resample 重采样0.8.0 新增了高灵活度的resample方法支持从高频到低频、从低频到高频的双向转换并具备插值interpolation支持用户自定义聚合函数对区间划分方式interval与结果标签result labeling的显式控制一套高性能的 Cython/C 重采样函数包含 Open-High-Low-CloseOHLC。在今天的仓库中重采样核心由 pandas/core/resample.py 承载Resampler基类pandas/core/resample.py之上派生DatetimeIndexResamplerL2114与PeriodIndexResamplerL2237分别针对DatetimeIndex与PeriodIndex索引aggregateL346、interpolateL851、ohlcL1743等方法正是发布说明所述能力的当代实现。频率别名重构与频率快捷方式frequencies模块被重构并支持频率快捷方式例如15min、1h30min这类组合写法。当代实现中频率推断与解析的核心位于 pandas/tseries/frequencies.pyinfer_freq_strL120与公开 APIinfer_freqL176负责从索引推断频率DatetimeIndex上也提供inferred_freq属性并支持在构造DatetimeIndex时选择是否自动推断频率。频率别名文档可参见 doc/source/user_guide/timeseries.rst 中的 offset aliases 一节。新 DatetimeIndex 类取代 DateRange新增的DatetimeIndex类同时支持固定频率与不规则时间序列取代了现已弃用的DateRange类。当前仓库中DatetimeIndex定义于 pandas/core/indexes/datetimes.py继承了DatetimeTimedeltaMixin的完整 datetime 能力。新 PeriodIndex 与 Period时间跨度与日历逻辑PeriodIndex与Period类用于表示时间跨度time spans并执行日历逻辑calendar logic支持12 个财政季度频率fiscal quarterly frequencies该实现是 scikits.timeseries 代码库元素的部分移植并做了实质性增强支持PeriodIndex与DatetimeIndex之间的相互转换。当代实现PeriodIndex位于 pandas/core/indexes/period.py底层存储PeriodArray定义于 pandas/core/arrays/period.pydtype 体系见 pandas/core/dtypes/dtypes.py 的PeriodDtype。新 Timestampdatetime.datetime 的子类Timestamp数据类型继承自datetime.datetime提供与后者一致的接口同时支持纳秒分辨率数据并内置时区转换能力。发布说明指出Timestamp是datetime.datetime的子类其nanosecond字段保存 0–999 之间的纳秒余数可直接替换任何原本使用datetime.datetime值的代码。其当代实现位于 pandas/_libs/tslibs/timestamps.pyx。时区支持增强tz_convert 与 tz_localize0.8.0 大幅增强了时区处理为 TimeSeriesSeries与 DataFrame 新增tz_convert与tz_localize方法所有时间戳统一按 UTC 存储带时区的DatetimeIndex中的时间戳在取出时会本地化为本地时区因此时区转换几乎零成本用户几乎不需要了解 pytz 库的细节只需提供时区名字符串时区感知time zone-aware时间戳当且仅当其 UTC 时间戳相等时才相等不同时区的时区感知序列做运算结果是UTC 索引的时间序列。当代实现可追溯至Series/DataFrame的tz_convertpandas/core/generic.py与tz_localizeL11166DatetimeIndex上的tz_convertpandas/core/indexes/datetimes.py与tz_localizeL595底层Timestamp.tz_localize/tz_convert位于 pandas/_libs/tslibs/timestamps.pyx 与 pandas/_libs/tslibs/timestamps.pyx。时区文档见 doc/source/user_guide/timeseries.rst。字符串索引快捷方式时间序列支持字符串索引的便捷写法可以按年、年月切片也可以用字符串直接索引取值。时间序列绘图增强绘图能力被增强直接吸收了scikits.timeseries 基于 matplotlib 的绘图代码。0.8.0 还引入了下文将详述的secondary_y与kde等新绘图能力。新的工厂函数date_range、bdate_range、period_range新增三个索引工厂函数date_range按日历年/月/日等生成DatetimeIndexbdate_range生成**工作日business day**索引period_range生成PeriodIndex。当代实现分别位于 pandas/core/indexes/datetimes.pydate_range、pandas/core/indexes/datetimes.pybdate_range、pandas/core/indexes/period.pyperiod_range。频率推断infer_freq 与 inferred_freq新增健壮的频率推断函数infer_freq以及DatetimeIndex的inferred_freq属性构造DatetimeIndex时可选择自动推断频率。to_datetime批量解析字符串数组to_datetime函数可高效地将字符串数组解析为DatetimeIndexDatetimeIndex本身也可直接解析字符串数组/列表为datetime64。当代实现位于 pandas/core/tools/datetimes.py 的多重签名to_datetime。其他时间序列改进Series/DataFrame 列中对 datetime64 dtype 数据的优化支持新增NaTNot-a-Time类型表示时间戳数组中的 NA 值其当代实现见 pandas/_libs/tslibs/nattype.pyx 与类型声明 pandas/_libs/tslibs/nattype.pyi优化Series.asof用于按时间戳数组查找“截至某时刻as of的值”当代实现见 pandas/core/generic.py新增Milli毫秒、Micro微秒、Nano纳秒的 DateOffset 对象可用datetime.time对象索引时间序列选取特定时刻TimeSeries.at_time见 pandas/core/generic.py或两个时刻之间的数据TimeSeries.between_time见 L9116新增tshift方法按照索引的频率如有进行前移/后移lead/lag区别于朴素的shift。其他新特性一览0.8.0 在时间序列之外也引入了一批影响深远的通用功能cut与qcut类似 R 语言的cut把连续变量按基于数值的区间cut或基于分位数的区间qcut分箱得到类别型变量。当代实现在 pandas/core/reshape/tile.pycut与 pandas/core/reshape/tile.pyqcut文档见 doc/source/user_guide/reshaping.rstFactor更名为Categorical并增加多项易用性功能fillna/reindex新增limit参数见 doc/source/user_guide/missing_data.rst当代fillna实现含limit参数可见 pandas/core/arrays/_mixins.pyGroupBy 支持更灵活的多函数应用可传入(name, function)元组列表按给定名称与顺序得到结果新增灵活的replace方法用于高效替换值见 doc/source/user_guide/missing_data.rst增强read_csv/read_table读取时间序列数据可将多列转换为日期见 doc/source/user_guide/io.rst 的 parse_dates 说明解析函数read_csv等新增comments、dayfirst解析国际 DD/MM/YYYY 日期、dialect控制 CSV 引号等行为、thousands千位分隔符改进整数解析选项支持一次性 unstack 多个层级并缓解了pivot_table的 bug不再引入空列索引哈希表迁移至klib 实现性能更好、内存占用低于 Python dictGroupBy 新增first、last、min、max、prod优化函数新增ordered_merge函数见 doc/source/user_guide/merging.rstDataFrame、Series 新增灵活的比较实例方法eq、ne、lt、gt等见 doc/source/user_guide/basics.rst 的 binop 说明改进scatter_matrix绘图函数对角线可显示直方图或核密度估计见 doc/source/user_guide/visualization.rst新增kde密度图选项同上支持通过rpy2 将 DataFrame 转换为 R 的 data.frame改进 Series 与 DataFrame 中复数的支持所有数据结构新增pct_change方法新增max_colwidth配置选项控制 DataFrame 控制台输出列宽支持按索引值插值 Seriesinterpolate见 doc/source/user_guide/missing_data.rst支持从 GroupBy 中选择多列Series/DataFrame 新增update方法用于原地更新值见 doc/source/user_guide/merging.rstDataFrame 新增any与all方法。新绘图方法secondary_y 与 kde发布说明给出了两个可直接运行的示例。secondary_y双轴绘图把法兰西法郎与意大利里拉画在双 y 轴上import pandas as pd import matplotlib.pyplot as plt fx pd.read_pickle(data/fx_prices) plt.figure() fx[FR].plot(styleg) fx[IT].plot(stylek--, secondary_yTrue)kde核密度图由 2012 年 GSOC 参与者 Vytautas Jancauskas 贡献的多种新图型之一import numpy as np s pd.Series( np.concatenate((np.random.randn(1000), np.random.randn(1000) * 0.5 3)) ) plt.figure() s.hist(densityTrue, alpha0.2) s.plot(kindkde)更全面的绘图说明见 doc/source/user_guide/visualization.rst 的绘图章节。其他 API 变更时间序列函数中的offset、time_rule、timeRule参数名被弃用。从 0.8.0 起调用这些旧参数会打印警告弃用警告将持续到 pandas 0.9 或 1.0。面向 pandas ≤ 0.7.3 用户的移植指南发布说明的结尾部分专门为旧用户整理了移植要点这是升级过程中最容易踩坑的地方。最大变化索引的底层数据类型0.8.0 的最大变化是时间序列索引使用 NumPy 的datetime64dtype而不再是dtypeobject的 Pythondatetime.datetime对象数组。DateRange已被DatetimeIndex取代行为上保持一致。如果你有代码把DateRange或曾经存放datetime.datetime的Index对象转换为纯 NumPy 数组可能潜伏着标量处理相关的 bug因为此时控制权交还给了 NumPy import datetime rng pd.date_range(1/1/2000, periods10) rng[5] Timestamp(2000-01-06 00:00:00) isinstance(rng[5], datetime.datetime) True rng_asarray np.asarray(rng) scalar_val rng_asarray[5] type(scalar_val) class numpy.datetime64如你所见通过DatetimeIndex取出的标量是Timestamp仍可视为datetime.datetime子类而np.asarray后取出的则是numpy.datetime64。发布说明明确建议不要把DatetimeIndex强制转换为普通 NumPy 数组。需要 datetime.datetime 数组时的两种解法如果你的代码确实需要datetime.datetime对象数组有两种方案方案一astype(object)产生Timestamp对象数组 stamp_array rng.astype(object) stamp_array Index([2000-01-01 00:00:00, 2000-01-02 00:00:00, 2000-01-03 00:00:00, 2000-01-04 00:00:00, 2000-01-05 00:00:00, 2000-01-06 00:00:00, 2000-01-07 00:00:00, 2000-01-08 00:00:00, 2000-01-09 00:00:00, 2000-01-10 00:00:00], dtypeobject) stamp_array[5] Timestamp(2000-01-06 00:00:00)方案二to_pydatetime()得到真正的datetime.datetime对象数组 dt_array rng.to_pydatetime() dt_array array([datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2000, 1, 2, 0, 0), datetime.datetime(2000, 1, 3, 0, 0), datetime.datetime(2000, 1, 4, 0, 0), datetime.datetime(2000, 1, 5, 0, 0), datetime.datetime(2000, 1, 6, 0, 0), datetime.datetime(2000, 1, 7, 0, 0), datetime.datetime(2000, 1, 8, 0, 0), datetime.datetime(2000, 1, 9, 0, 0), datetime.datetime(2000, 1, 10, 0, 0)], dtypeobject) dt_array[5] datetime.datetime(2000, 1, 6, 0, 0)matplotlib 与 Timestamp 的兼容matplotlib 认识datetime.datetime但不认识Timestamp。官方推荐用TimeSeries.plot直接绘图若必须手绘可改用to_pydatetime()转换或为Timestamp类型注册 converter。关于 NumPy 1.6 的纳秒 bug重要警告发布说明给出明确警告NumPy 1.6 的 datetime64 用户可见 API 存在 bug——特别是数组的字符串显示会出现乱码garbage values且到dtypeobject的转换同样有问题 rng pd.date_range(1/1/2000, periods10) rng DatetimeIndex([2000-01-01, 2000-01-02, 2000-01-03, 2000-01-04, 2000-01-05, 2000-01-06, 2000-01-07, 2000-01-08, 2000-01-09, 2000-01-10], dtypedatetime64[us], freqD) np.asarray(rng) array([2000-01-01T00:00:00.000000, 2000-01-02T00:00:00.000000, 2000-01-03T00:00:00.000000, 2000-01-04T00:00:00.000000, 2000-01-05T00:00:00.000000, 2000-01-06T00:00:00.000000, 2000-01-07T00:00:00.000000, 2000-01-08T00:00:00.000000, 2000-01-09T00:00:00.000000, 2000-01-10T00:00:00.000000], dtypedatetime64[us]) converted np.asarray(rng, dtypeobject) converted[5] Timestamp(2000-01-06 00:00:00)发布说明的结论非常直白——“相信我别慌”只要你在 NumPy 1.6 下把datetime64的交互限制在 pandas 的 API 内就完全没问题。该 dtype 本质上只是内部 64 位整数所有重要的数据处理都发生在 pandas 层且经过充分测试官方强烈建议不要在 NumPy 1.6 中直接操作 datetime64 数组只使用 pandas API。非唯一索引的兼容处理移植指南最后回到非唯一索引如果你的代码在try...catch中捕获了“索引不唯一”导致的失败升级后大多数场景下不再触发append等方法仍会校验唯一性除非显式禁用。处理方式是显式检查if not index.is_unique: raise ValueError(index must be unique)或根据index.is_unique的结果走不同的代码分支。is_unique的底层实现位于 pandas/_libs/index.pyx。小结pandas 0.8.0 的意义远超一个普通大版本它以 NumPydatetime64为地基重构了时间序列数据模型确立了此后十余年 pandas 时间序列 API 的基本形态——DatetimeIndex、PeriodIndex、Timestamp、resample、date_range、infer_freq、tz_convert/tz_localize这些今天仍在使用的核心构件都在本版本成型或定型。配合cut/qcut、GroupBy 增强、解析器选项与绘图新能力0.8.0 既是对 scikits.timeseries 遗产的继承与超越也是 pandas 走向成熟数据科学基础设施的关键一跃。对仍在维护 0.7.x 时代代码的开发者而言上述移植指南中的Timestamp子类关系、astype(object)/to_pydatetime()转换路径以及非唯一索引的显式检查是平滑过渡到新模型的三把钥匙。【免费下载链接】pandasFlexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more项目地址: https://gitcode.com/gh_mirrors/pa/pandas创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
