Pandas 0.15.2 版本全解析MultiIndex 擴(kuò)展索引、Categorical 互操作與關(guān)鍵 API 變更【免費(fèi)下載鏈接】pandasFlexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more項(xiàng)目地址: https://gitcode.com/gh_mirrors/pa/pandas導(dǎo)讀本文基于 doc/source/whatsnew/v0.15.2.rst發(fā)布于 2014 年 12 月 12 日系統(tǒng)梳理 pandas 0.15.2 這一從 0.15.1 出發(fā)的小版本更新它包含大量 Bug 修復(fù)、若干新特性與增強(qiáng)、以及為修復(fù)既有問題而必須引入的一小部分 API 變更。讀完本文你將掌握 MultiIndex 超出字典序深度的索引行為、Categorical 與 Stata/HDF5 的互操作能力、all/any聚合的新參數(shù)語義、to_datetime的exact匹配控制以及一批直接影響日常數(shù)據(jù)清洗與 I/O 的細(xì)節(jié)變更并了解這些特性在當(dāng)前倉庫源碼中的實(shí)現(xiàn)落點(diǎn)。版本背景與升級(jí)建議pandas 0.15.2 是一個(gè)從 0.15.1 出發(fā)的小版本發(fā)布官方建議所有用戶升級(jí)到該版本。該版本的主要特點(diǎn)包括大量 Bug 修復(fù)涉及索引、時(shí)間序列、I/O、繪圖、分組聚合等幾乎所有核心模塊若干新特性與增強(qiáng)以Categorical類型為中心的外部存儲(chǔ)互操作以及all/any、to_datetime、Timedelta等 API 的擴(kuò)充少量 API 變更這些變更并非為了引入新功能而是為了修復(fù)既有 Bug 而必須做出的行為調(diào)整使用舊行為編寫的代碼需要關(guān)注遷移。版本公告按 4 個(gè)板塊組織本文依此展開Enhancements增強(qiáng)API ChangesAPI 變更Performance Improvements性能改進(jìn)Bug FixesBug 修復(fù)API changes本節(jié)收錄的是會(huì)改變既有行為、需要使用者留意遷移的變更其中大多數(shù)是為了消除不一致行為而做的修正。MultiIndex支持超出字典序深度的索引這是本版本最重要的 API 變更之一。此前當(dāng)MultiIndex未按字典序lexicographic order排序時(shí)通過.loc對(duì)多級(jí)索引做部分鍵查找會(huì)直接拋出KeyError0.15.2 起這一限制被解除——只要鍵位于已排序的前若干級(jí)即lexsort_depth之內(nèi)即可工作但字典序排序的索引在性能上更優(yōu)因此未排序索引上做此類查找會(huì)給出PerformanceWarning。來看官方文檔給出的完整示例import numpy as np import pandas as pd df pd.DataFrame( { jim: [0, 0, 1, 1], joe: [x, x, z, y], jolie: np.random.rand(4), } ).set_index([jim, joe]) df # jolie # jim joe # 0 x 0.126970 # x 0.966718 # 1 z 0.260476 # y 0.897237此時(shí)索引的字典序深度只有 1第一級(jí)jim有序第二級(jí)joe在jim 1分組內(nèi)不是有序的df.index.lexsort_depth # 1 # 在 0.15.2 之前的版本中這會(huì)拋 KeyError # 現(xiàn)在會(huì)給出 PerformanceWarning df.loc[(1, z)] # jolie # jim joe # 1 z 0.260476而對(duì)索引做字典序排序之后lexsort_depth變?yōu)?2查找同樣成立且性能更優(yōu)df2 df.sort_index() df2 # jolie # jim joe # 0 x 0.126970 # x 0.966718 # 1 y 0.897237 # z 0.260476 df2.index.lexsort_depth # 2 df2.loc[(1, z)] # jolie # jim joe # 1 z 0.260476源碼實(shí)現(xiàn)落點(diǎn)當(dāng)前倉庫中l(wèi)exsort_depth的語義被完整保留。MultiIndex._lexsort_depth屬性緩存了該值若sortorder已記錄則直接復(fù)用否則調(diào)用模塊級(jí)函數(shù)_lexsort_depth(codes, nlevels)計(jì)算見 pandas/core/indexes/multi.py。底層實(shí)現(xiàn)從最高層向低層逐級(jí)調(diào)用 Cython 的libalgos.is_lexsorted判斷前 k 層是否已字典序有序見 pandas/core/indexes/multi.py。在部分鍵查找路徑_partial_tup_index中如果鍵的長(zhǎng)度超過_lexsort_depth會(huì)拋出UnsortedIndexError見 pandas/core/indexes/multi.py而在非字典序索引上做drop且未指定level時(shí)會(huì)按mode.performance_warnings配置發(fā)出PerformanceWarning見 pandas/core/indexes/multi.py。相關(guān)行為在 pandas/tests/indexes/multi/test_lexsort.py、pandas/tests/indexes/multi/test_sorting.py 與 pandas/tests/indexing/multiindex/test_slice.py 中有大量覆蓋。Categorical.unique只返回實(shí)際出現(xiàn)的類別此前對(duì)Categorical調(diào)用unique()會(huì)返回全部聲明的 categories無論這些類別是否真的出現(xiàn)在數(shù)據(jù)中例如cat pd.Categorical([a, b, a], categories[a, b, c]) cat # [a, b, a] # Categories (3, object): [a b c] cat.unique() # 舊行為array([a, b, c], dtypeobject) - 錯(cuò)誤包含了未使用的 c0.15.2 起unique()只返回?cái)?shù)據(jù)中實(shí)際出現(xiàn)的類別同時(shí)保留聲明的類別全集信息 cat pd.Categorical([a, b, a], categories[a, b, c]) cat.unique() [a, b] Categories (3, str): [a, b, c]當(dāng)前實(shí)現(xiàn)中Categorical.unique()委托父類返回“categories 與 codes 均去重”的Categorical見 pandas/core/arrays/categorical.py其 docstring 示例明確展示了未使用類別不會(huì)出現(xiàn)在結(jié)果中。Series/Index 的 all 與 any參數(shù)語義調(diào)整Series.all與Series.any新增支持level與skipna參數(shù)同時(shí)為 ndarray 兼容而存在的out與keepdims參數(shù)被移除。此外各類Index不再支持all/any聚合函數(shù)調(diào)用將拋出TypeError。這一變更由 pandas/tests/series/test_reductions.py 等測(cè)試驗(yàn)證。源碼實(shí)現(xiàn)落點(diǎn)當(dāng)前倉庫中NDFrame.all/any的簽名只有axis、bool_only、skipna和**kwargs統(tǒng)一經(jīng)由_logical_func分發(fā)到nanops.nanall/nanops.nanany見 pandas/core/generic.py任何多余的命名參數(shù)都會(huì)在_logical_func中被nv.validate_logical_func拒絕。Categorical 與 object 的相等比較允許帶categorydtype 的Series與objectdtype 的Series做相等性比較此前這種比較會(huì)拋出TypeError。NDFrame屬性與列名沖突行為一致化當(dāng) DataFrame 同時(shí)存在名為y的屬性與列時(shí)讀寫行為此前是不一致的data.y返回屬性而data.y z卻更新列。0.15.2 起兩者統(tǒng)一為操作列 data pd.DataFrame({x: [1, 2, 3]}) data.y 2 data[y] [2, 4, 6] data x y 0 1 2 1 2 4 2 3 6 data.y 5 # 此前這一賦值行為不一致舊行為讀返回屬性、寫更新列In [6]: data.y Out[6]: 2 In [7]: data[y].values Out[7]: array([5, 5, 5])新行為讀與寫都作用于列 data.y 5 data[y].values array([2, 4, 6])Timestamp(now) / Timestamp(today) 語義修正Timestamp(now)現(xiàn)在等價(jià)于Timestamp.now()返回本地時(shí)間而非 UTCTimestamp(today)現(xiàn)在等價(jià)于Timestamp.today()且兩者都接受可選的tz參數(shù)。標(biāo)簽切片支持負(fù)步長(zhǎng)此前s.loc[c:a:-1]這類基于標(biāo)簽的負(fù)步長(zhǎng)切片無法正確工作只返回單個(gè)元素。0.15.2 起行為修正# 舊行為 In [1]: s pd.Series(np.arange(3), [a, b, c]) In [2]: s.loc[c:a:-1] Out[2]: c 2 dtype: int64 # 新行為 s pd.Series(np.arange(3), [a, b, c]) s.loc[c:a:-1] c 2 b 1 a 0 dtype: int64相關(guān)切片邏輯在當(dāng)前倉庫的 pandas/core/indexes/multi.py 等實(shí)現(xiàn)中均對(duì)step is not None的情況做了分支處理。增強(qiáng)Enhancements本版本以Categorical為核心展開了多項(xiàng) I/O 互操作能力并對(duì)時(shí)間類型、SQL 寫出、字符串解析等做了增強(qiáng)。Categorical 增強(qiáng)導(dǎo)出到 Stata 數(shù)據(jù)文件新增將Categorical數(shù)據(jù)導(dǎo)出到 Stata 文件的能力。導(dǎo)出時(shí)類別編碼作為整型數(shù)據(jù)值寫入、類別本身作為 value labels 寫入。需要注意的限制詳見 doc/source/user_guide/io.rstStata 沒有與Categorical完全對(duì)應(yīng)的類型導(dǎo)出時(shí)會(huì)丟失變量是否為有序ordered的信息Stata 僅支持字符串型 value labels因此導(dǎo)出時(shí)會(huì)對(duì)類別調(diào)用str()若類別為非字符串類型會(huì)給出警告且當(dāng)str()表示不唯一時(shí)可能造成信息丟失。從 Stata 導(dǎo)入order_categoricals 參數(shù)StataReader與read_stata新增布爾參數(shù)order_categoricals默認(rèn)True用于控制導(dǎo)入的 Categorical 變量是否保序。官方用戶指南doc/source/user_guide/io.rst對(duì)導(dǎo)入細(xì)節(jié)說明如下帶標(biāo)簽數(shù)據(jù)默認(rèn)通過convert_categoricalsTrue導(dǎo)入為Categorical導(dǎo)入時(shí) Stata 文件中的原始值并不保留Categorical一律使用-1到n-1的整型編碼缺失值編碼為-1原始值按升序依次映射到0, 1, ..., n-1如需原始數(shù)值可設(shè)convert_categoricalsFalse此時(shí)不再導(dǎo)入變量標(biāo)簽若原始 Stata 值是帶標(biāo)簽的整型且確實(shí)是有序的導(dǎo)入后order_categoricalsTrue會(huì)保留序數(shù)信息。源碼實(shí)現(xiàn)落點(diǎn)order_categoricals貫穿整個(gè) Stata 讀取鏈路——StataReader構(gòu)造參數(shù)見 pandas/io/stata.py、read_stata頂層參數(shù)見 pandas/io/stata.py最終在_convert_categoricals中決定Categorical(..., orderedorder_categoricals)見 pandas/io/stata.py。相關(guān)行為由 pandas/tests/io/test_stata.py 覆蓋。導(dǎo)出到/從 HDF5新增categorydtype 數(shù)據(jù)寫入HDFStore的能力見 doc/source/user_guide/io.rst查詢方式與 object 數(shù)組一致但與普通 object 列不同、、、這類排序比較要求列以orderedTrue寫出且比較依據(jù)的是類別順序而非值本身categorydtype 數(shù)據(jù)的存儲(chǔ)方式更高效。官方示例dfcat pd.DataFrame( {A: pd.Series(list(aabbcdba)).astype(category), B: np.random.randn(8)} ) cstore pd.HDFStore(cats.h5, modew) cstore.append(dfcat, dfcat, formattable, data_columns[A]) result cstore.select(dfcat, whereA in [b, c]) cstore.close()Categorical.searchsorted()Categorical類新增searchsorted()支持可在類別編碼上執(zhí)行二分查找定位插入位置。其他增強(qiáng)to_sql 支持自定義 SQL 列類型寫 DataFrame 到數(shù)據(jù)庫時(shí)新增指定各列 SQL 類型的能力默認(rèn)字符串列使用Text類型。例如使用 SQLAlchemy 的String類型from sqlalchemy.types import String data.to_sql(data_dtype, engine, dtype{Col_1: String})同時(shí)to_sql現(xiàn)在會(huì)為含有 NA 值且 dtype 為object的列依據(jù)非 NA 值推斷數(shù)據(jù)類型。sql_schema也改為生成方言適配的CREATE TABLE語句。Series.all / Series.any 的 level 與 skipnaSeries.all/Series.any支持按索引層級(jí)分組聚合 s pd.Series([False, True, False], index[0, 0, 1]) s.any(level0) 0 True 1 False dtype: boolPanel 支持 all / anyPanel新增all()/any()聚合函數(shù)基于隨機(jī)布爾數(shù)組的示例輸出 p pd.Panel(np.random.rand(2, 5, 4) 0.1) p.all() 0 1 2 3 0 True True True True 1 True False True True 2 True True True True 3 False True False True 4 True True True TrueTimestamp 類增強(qiáng)Timestamp新增utcfromtimestamp()、fromtimestamp()、combine()方法。Timedelta 算術(shù)與 API 增強(qiáng)Timedelta在未知情況下參與算術(shù)運(yùn)算時(shí)返回NotImplemented從而允許自定義類擴(kuò)展其行為Timedelta支持與合適 dtype 的numpy.ndarray對(duì)象做算術(shù)運(yùn)算僅限 numpy 1.8 及以上新增Timedelta.to_timedelta64()公開方法。to_datetime 的 exact 參數(shù)to_datetime新增exact關(guān)鍵字當(dāng)exactFalse時(shí)傳入的format字符串不必與輸入完全匹配exact默認(rèn)值為True即默認(rèn)仍要求精確匹配。這在需要部分匹配格式字符串的寬松解析場(chǎng)景下非常實(shí)用同時(shí)官方明確該路徑有獨(dú)立的性能優(yōu)化見下文性能章節(jié)。源碼實(shí)現(xiàn)落點(diǎn)當(dāng)前倉庫中to_datetime簽名包含exact: bool True并說明“exact format matching behavior from to_datetime”見 pandas/core/tools/datetimes.py。解析時(shí)由array_strptime(arg, fmt, exactexact, ...)接手若使用exactFalse會(huì)對(duì)格式做截?cái)嗵幚?。其他小增?qiáng)pandas.io.gaGoogle Analytics 數(shù)據(jù)讀取補(bǔ)充了基礎(chǔ)文檔gbq模塊新增gbq.generate_bq_schema()函數(shù)用于生成 BigQuery schemaSeries現(xiàn)在可以像接受生成器一樣接受 map 對(duì)象HDFStore新增上下文管理器支持可自動(dòng)關(guān)閉存儲(chǔ)with pd.HDFStore(store.h5) as store: ...parallel_coordinates繪圖函數(shù)新增axvlines布爾選項(xiàng)控制是否繪制縱向參考線默認(rèn)Trueread_html新增讀取表格 footer表腳注的能力。性能改進(jìn)Performance本版本的兩項(xiàng)性能優(yōu)化都與解析和轉(zhuǎn)換熱路徑相關(guān)read_csv的skiprows為整數(shù)時(shí)減少內(nèi)存占用。此前以整數(shù)形式跳過行時(shí)會(huì)在內(nèi)存中保留不必要的中間數(shù)據(jù)現(xiàn)在改為更節(jié)約的內(nèi)存路徑。to_datetime轉(zhuǎn)換提速在傳入format且exactFalse的場(chǎng)景下轉(zhuǎn)換性能得到提升。exactFalse允許格式字符串部分匹配輸入實(shí)現(xiàn)上可以對(duì)已知格式做更快的字符串切分解析避免逐字符兜底匹配。Bug Fixes0.15.2 修復(fù)了大量 Bug按模塊歸納如下便于定位與回歸驗(yàn)證Categorical 與類型系統(tǒng)concat拼接categorydtype 的Series時(shí)被錯(cuò)誤強(qiáng)制為object此前 bugcummin/cummax在含NaT的datetime64Series 上拋出ValueErrorget_data_google返回 object dtype、DataReader在含缺失值時(shí)返回 object dtypeto_datetime解析%f納秒格式錯(cuò)誤、Timestamp無法解析 UTC 的Z時(shí)區(qū)設(shè)計(jì)符TimedeltaIndex構(gòu)造時(shí)傳入單位被重復(fù)應(yīng)用納秒換算單位被應(yīng)用兩次Timedelta關(guān)鍵字參數(shù)現(xiàn)在支持 numpy 整型與浮點(diǎn)型修復(fù)了Timedelta算術(shù)與比較的多處問題日期類操作Timestamp - Timestamp未返回Timedelta、帶時(shí)區(qū)的 datelike-datelike 操作時(shí)區(qū)不匹配異常統(tǒng)一為TypeError此前個(gè)別場(chǎng)景為ValueError。MultiIndex 與索引用空列表 至少一個(gè)布爾索引器切片 MultiIndex 出錯(cuò)MultiIndex.reindex在 level 上重排時(shí)標(biāo)簽未正確重排MultiIndex.__contains__在索引非字典序或非唯一時(shí)返回錯(cuò)誤結(jié)果DataFrame.stack(..., dropnaFalse)在列 MultiIndex 的 labels 未引用全部 levels 時(shí)出錯(cuò)多列 stack 時(shí) level 名為數(shù)字部分或全部導(dǎo)致出錯(cuò)DatetimeIndex使用time對(duì)象作為鍵出錯(cuò)。合并 / 分組 / 重采樣merge(howleft, sortFalse)未保持左表順序pd.Grouper(key...)無 level/axis 或僅 level 時(shí)出錯(cuò)groupby 傳入非法/無參數(shù)時(shí)改為拋TypeErrorgroupby簽名缺失*args/**kwargsresample跨多天重采樣且最后偏移量不是從范圍起點(diǎn)計(jì)算時(shí)拋ValueError。I/OStataWriter寫入的字符串固定為 244 字符與真實(shí)大小不符to_html(indexFalse)輸出 MultiIndex 時(shí)多出一列read_csv跳過行中行尾空白處理錯(cuò)誤Python 3 下讀取大 CSV 文件時(shí)除以 0CSV 解析中 dtype 與 names 不匹配時(shí)錯(cuò)誤信息不清晰sql_schema現(xiàn)在生成方言適配的CREATE TABLEio.data.Options在 Yahoo 無到期日或收不到數(shù)據(jù)時(shí)拋RemoteDataError。時(shí)間序列 / 時(shí)區(qū)pd.infer_freq/DataFrame.inferred_freq在索引包含 DST 日時(shí)無法推斷亞日頻率DatetimeIndex迭代在 Fixed/Local offset 時(shí)區(qū)下出現(xiàn)回歸dateutil 2.3 下的若干操作問題。繪圖 / 其他字體大小只在垂直時(shí)設(shè)置 x 軸、水平時(shí)設(shè)置 y 軸相反方向未設(shè)置DataFrame.plot(kindscatter)檢查 np.array 是否在 DataFrame 中時(shí)失敗繪圖時(shí)use_indexFalse仍使用索引名sharex開啟且索引為時(shí)間序列時(shí)多軸重復(fù)顯示標(biāo)簽period 類數(shù)組繪圖出錯(cuò)matplotlib 1.2 時(shí)跳過直方圖測(cè)試BlockManager中設(shè)置不同類型值會(huì)破壞 block 完整性NDFrame.size屬性補(bǔ)齊以兼容 numpy 1.9.1此前與np.array_split配合出錯(cuò)選項(xiàng)上下文管理器在__enter__上就生效slice字符串方法現(xiàn)在考慮步長(zhǎng)str.slice步長(zhǎng)支持、Timedelta相關(guān)修復(fù)等修復(fù)了用py2app/cx_Freeze打包 pandas 的問題。這些修復(fù)大多對(duì)應(yīng)公開 issue 編號(hào)如 8559、2646、8302、8994、9000、8753、8633、8836、7621、8420、8778、8904、8681 等可在 pandas 的 issue 追蹤系統(tǒng)中回溯討論與復(fù)現(xiàn)細(xì)節(jié)。小結(jié)pandas 0.15.2 雖然在版本號(hào)上只是一個(gè)小版本卻橫跨了索引語義MultiIndex 非字典序查找、類型系統(tǒng)Categorical 的unique語義與 Stata/HDF5 互操作、聚合 APIall/any參數(shù)重構(gòu)、時(shí)間類型Timestamp/Timedelta語義修正以及數(shù)十處細(xì)節(jié) Bug 修復(fù)。其中許多行為如lexsort_depth、order_categoricals、to_datetime(exact...)至今仍保留在當(dāng)前倉庫的實(shí)現(xiàn)中是理解 pandas 索引優(yōu)化策略與類型互操作設(shè)計(jì)的重要?dú)v史節(jié)點(diǎn)。如果你正在維護(hù)基于 pandas 的存量代碼建議重點(diǎn)核對(duì)本文“API changes”一節(jié)涉及的四類行為變更它們會(huì)直接影響索引查找、聚合結(jié)果與 I/O 讀取的返回值其余增強(qiáng)與性能項(xiàng)則可按需升級(jí)使用。【免費(fèi)下載鏈接】pandasFlexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more項(xiàng)目地址: https://gitcode.com/gh_mirrors/pa/pandas創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考