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