本博客是对Pandas Extending中文翻译。原文地址如下link。主要介绍如何自定义扩展Pandas库,包括如何对Pandas主要类DataFrame
, Series
自义定接口;如何自定义扩展DataFrame
, Series
基本数据类型;在用户需要继承DataFrame
, Series
类时官方提出的建议。本博客除了翻译官方文本之外,还结合笔者正在进行扩展pandas的相关工作给出了粗浅的点评。
Pandas库提供了丰富的方法、容器和数据类型,但您的需求可能无法完全满足。Pandas提供了一些自定义扩展pandas的方法。
这些场景例如但不仅限于:
myfunction(pands_obj)
为类方法调用方式pandas_obj.myfunction
(Series.myfunction
)时;pandas_obj
中需要自定义储存数据类型为IP地址类型ipaddress.IPv4Address
,用户可以自定义这种基本类型格式,并且定义其操作方法;pandas_obj
,继承往往不是最佳的选择。但用户决定有必要这么做时,pandas提供了继承pandas_obj
类的建议;可以使用的装饰类库pandas.api.extensions.register_dataframe_accessor()
, pandas.api.extensions.register_series_accessor()
和pandas.api.extensions.register_index_accessor()
将其他“命名空间”添加到pandas对象。这些方法思路为:使用装饰器对类进行装饰,在装饰器添加的属性的名称。具体为,装饰类的__init__
方法获取要修饰的对象,例如如下例子给出自定义的经纬度类接口:
@pd.api.extensions.register_dataframe_accessor("geo")
class GeoAccessor:
def __init__(self, pandas_obj):
self._validate(pandas_obj)
self._obj = pandas_obj
@staticmethod
def _validate(obj):
# verify there is a column latitude and a column longitude
if 'latitude' not in obj.columns or 'longitude' not in obj.columns:
raise AttributeError("Must have 'latitude' and 'longitude'.")
@property
def center(self):
# return the geographic center point of this DataFrame
lat = self._obj.latitude
lon = self._obj.longitude
return (float(lon.mean()), float(lat.mean()))
def plot(self):
# plot this array's data on a map, e.g., using Cartopy
pass
用户调用自定义的命名空间:
ds = pd.DataFrame({'longitude': np.linspace(0, 10),
... 'latitude': np.linspace(0, 20)})
>>> ds.geo.center
(5.0, 10.0)
>>> ds.geo.plot()
# plots data on a map
非常出色的实现方式。以pandas提供的原生接口方式实现:@pd.api.extensions.register_dataframe_accessor("自定义")
。调用方式为实例.自定义.属性/方法
。这种非侵入式的实现方式有效的分离了原pandas_obj
和自定义接口自定义
的作用域。本质上采用了组合的思想,核心实现方式为accessor
系列函数,笔者会在后面的博客中进行介绍。
但是不得不说这种实现方式的遗憾是,当采用这种方式进行接口的扩展,在某些IDE上(例如在笔者所用的IDE Spyder)调用自定义
接口时不会给出提示和自动代码补全。
Pandas定义了一个接口用于实现扩展Numpy生态中的数据类型和数组类型。而Pandas自身生态包含了扩展对一些没有内置到Numpy中的类型进行处理(categorical、period、interval、datetime和timezone)。
库允许用户自定义数组和数据类型。并且pandas可以正确处理(例如,不会被转换成ndarray实例)用户定义的类或实例,因为很多方法例如pandas.isna()
考虑了扩展类型的实现。
如果您正在构建实现接口的库,pandas希望您在扩展数据类型上公开它。
接口由两个类组成,ExtensionDtype
和ExtensionArray
。
pandas.api.extensions.ExtensionDtype
类似于numpy.dtype
类。它用于描述数据类型。在调用过程中,用户需专注于一些特定的唯一属性,比如名称。
type
是一个特别重要的属性。表示用户自定义数据所属的类型。例如,如果您正在为IP地址编写扩展类型,应当是ipaddress.IPv4Address
类型。
有关接口定义,请参见extension dtype source。
版本0.24.0中的新功能。
pandas.api.extension.ExtensionDtype
用于创建数据类型字符名称。通过字符串名实例化Series
和.astype()
进行实现,例如 'category'
是一个已被使用的CategoricalDtype
的访问字符。
有关如何自定义数据类型的详细信息,请参阅extension dtype dtypes。
这个类提供了类数组(array-like)类的全部功能。ExtensionArrays
类仅限于1维。ExtensionArray
类通过dtype
属性链接到ExtensionDtype
。
Pandas不限制如何通过new
或init
方法创建扩展数组,也不限制如何存储数据。但是非常重要的一点是,Pandas要求用户自定义的数组可以转换为Numpy数组,即使它非常复杂(因为它会被用于Categorical
类)。
它们可能由空、一个或多个Numpy数组支持。例如, pandas.Categorical
的是由两个数组支持的扩展数组,一个用于编码,一个用于分类;IPv6地址数组可以由具有两个字段的Numpy结构数组支持,一个用于低位64位,另一个用于高位64位;或者它们可能有其他存储类型的支持,比如Python的列表类。
有关接口定义,请参见extension array source。文档和注释将指导用户正确实现接口。
扩展数组中存放的数据类型可以是基本类型,也可以是用户自定义的,扩展数组支持自定义的结构和操作方法。例如在IPv6例子中,扩展数组由低位64位,和高位64位两个自定义数据类型元素ipaddress.IPv6Address
组合而成。这个自定义数组应包含特定的属性和方法用于解释IPv6的低位和高位特性,并给出常规的操作方法。
但是要注意的是,自定义的数组不管怎么变来变去,应该始终是Numpy所支持的数组。(始终不离核心,即Pandas本质的数据结构是矩阵和数组)。
版本0.24.0中的新功能。
默认情况下,没有为类ExtensionArray
定义运算。有两种方法可以为类 ExtensionArray
提供操作:
ExtensionArray
子类的类方法。ExtensionArray
的底层定义的运算方法。无论采用何种方法,如果希望在使用NumPy数组进行二进制操作时调用实现,则可能需要设置__array_priority__
。
对于第一种方法,用户需定义操作符例如 __add__
,__le__
等,以提供自定义类对这些操作的支持。
第二种方法基于 ExtensionArray的底层元素(即标量类型)已经定义了各个运算符。换言之,如果定义为MyExtensionArray
的ExtensionArray
被实现为每个元素都是MyExtensionElement
类的实例,则在第二种方法中如果为MyExtensionElement
定义运算符,也将自动为MyExtensionArray
定义运算符。
作为mixin类,ExtensionScalarOpsMixin
支持第二种方法。如果开发一个ExtensionArray
子类,例如MyExtensionArray
,可以简单地将 ExtensionScalarOpsMixin
包含为MyExtensionArray
的父类,然后调用方法_add_arithmetic_ops()
和/或_add_comparison_ops()
将运算符挂接到MyExtensionArray
类中,如下所示:
from pandas.api.extensions import ExtensionArray, ExtensionScalarOpsMixin
class MyExtensionArray(ExtensionArray,
ExtensionScalarOpsMixin):
pass
MyExtensionArray._add_arithmetic_ops()
MyExtensionArray._add_comparison_ops()
由于Pandas自动逐个调用每个元素上的底层运算符,因此这可能不如直接在ExtensionArray
上实现自定义版本的关联运算符更有效。
对于算术操作,此实现将尝试使用元素操作的结果重建新的ExtensionArray
。是否成功取决于操作是否返回对ExtensionArray
合法的结果。如果无法重建ExtensionArray
,则返回包含标量的ndarray。
为了实现并协同pandas和numPy ndarrays之间的操作保持一致,Pandas建议不要在二进制操作中处理序列和索引。相反,您应该检测这些情况并返回NotImplemented。当pandas遇到类似 op(Series, ExtensionArray)
的操作时,pandas 将
Series
(Series.array
)result = op(values, ExtensionArray)
Series
直白的来说,如果要实现自定义数组的操作方式,要么是自己写,要么就从已有的方式进行继承。一种mixin方法(以Mixin方式命名的类实质上实现接口的功能)ExtensionScalarOpsMixin
包含了一些定义的操作,如果需要请从父类继承。
Pandas说明在底层实现是逐个调用每个元素上的底层运算符,换句话来说,继承的方式只能保证代码是可以工作的,但是无法保证运行效率。如果需要用户保持一定的运行效率,还是要自己写。
Series
实现了__array_ufunc__
方法。作为执行的一部分,Pandas从Series
中解绑ExtensionArray
,执行自定义方法,并在必要时重新装箱。
如果适用,我们强烈建议用户在自定义数组中实现 __array_ufunc__
,以避免强制转为多维数组(ndarray)类型。有关示例,请参见 the numpy documentation。
作为实现的一部分,要求在自定义的输入inputs中检测到pandas容器(Series
, DataFrame
, Index
)时委托给pandas。如果其中任何一个存在,则应返回NotImplemented。Pandas将负责从容器中解除数组的绑定,并使用解绑的输入重新调用自定义的函数。
这部分的功能笔者并不是很熟悉简单理解到为元素级运算,希望有高人不吝赐教。科普一下numpy提供了一些诸如三角函数这样的常用函数,在numpy中,将其称为“universal functions(ufunc)”
。
在numpy内部,这些函数在array中执行elementwise(元素级)的运算,生成一个新的array作为输出。
pandas提供了一个测试套件来确保用户的自定义数组满足预期的行为。要使用测试套件,您必须提供几个Python测试用例(pytest fixture)并继承基本测试类。所需见fixture。通过子类化使用
from pandas.tests.extension import base
class TestConstructors(base.BaseConstructorsTests):
pass
所有可用测试的列表见link。
通过实现两个方法,ExtensionArray
可以支持向/从pyarrow
数组的转换(从而支持例序列化到Parquet文件格式):ExtensionArray.__arrow_array__
和ExtensionDtype.__from_arrow__
ExtensionArray.__arrow_array__
数组确保pyarrow
定义如何将特定的扩展数组转换为pyarrow.Array
(当作为列包含在pandas的DataFrame
时):
class MyExtensionArray(ExtensionArray):
...
def __arrow_array__(self, type=None):
# convert the underlying array values to a pyarrow Array
import pyarrow
return pyarrow.array(..., type=type)
ExtensionDtype.__from_arrow__
方法将控制从Python参数到pandas定义的扩展数组的转换。此方法仅接收Python数组Array
或ChunkedArray
作为参数,并将此数据类型和传递的值返回给相应ExtensionArray
:
class ExtensionDtype:
...
def __from_arrow__(self, array: pyarrow.Array/ChunkedArray) -> ExtensionArray:
更多见Arrow documentation
这些方法已经为pandas中包含的可为空的整数和字符串扩展类型实现,并确保到Python数组和Parquet文件格式的相互转换。
简单来说ExtensionArray
中的__from_arrow__
和__arrow_array__
方法用于与Parquet文件格式兼容。如果需要,请实现它们。
来自官方的凝视(Warning):在考虑对pandas数据结构进行子类化之前,有一些更简单的选择。
pipe
可扩展方法链registering an accessor
进行扩展extension type
扩展本节描述如何对pandas数据结构进行子类化以满足更具体的需求。有两点需要注意:
每个数据结构都有几个构造函数属性,用于作为操作的结果返回新的数据结构。通过重写这些属性,可以通过pandas数据操作保留子类。
要定义3个构造函数属性:
_constructor
:当操作结果具有与原始结果相同的维度时使用。
_constructor_sliced
:当操作结果比原始维度低时使用,例如DataFrame 单列切片。
_constructor_expanddim
:当操作结果与原始结果有一个更高的维度时使用,例如Series.to_frame()
.
下表列出了pandas数据结构默认的构造属性
属性 | Series |
DataFrame |
---|---|---|
_constructor |
Series |
DataFrame |
_constructor_sliced |
NotImplementedError |
Series |
_constructor_expanddim |
DataFrame |
NotImplementedError |
下列例子示例如何复写SubclassedSeries
和SubclassedDataFrame
的构造属性
class SubclassedSeries(pd.Series):
@property
def _constructor(self):
return SubclassedSeries
@property
def _constructor_expanddim(self):
return SubclassedDataFrame
class SubclassedDataFrame(pd.DataFrame):
@property
def _constructor(self):
return SubclassedDataFrame
@property
def _constructor_sliced(self):
return SubclassedSeries
>>> s = SubclassedSeries([1, 2, 3])
>>> type(s)
<class '__main__.SubclassedSeries'>
>>> to_framed = s.to_frame()
>>> type(to_framed)
<class '__main__.SubclassedDataFrame'>
>>> df = SubclassedDataFrame({'A': [1, 2, 3], 'B': [4, 5, 6], 'C': [7, 8, 9]})
>>> df
A B C
0 1 4 7
1 2 5 8
2 3 6 9
>>> type(df)
<class '__main__.SubclassedDataFrame'>
>>> sliced1 = df[['A', 'B']]
>>> sliced1
A B
0 1 4
1 2 5
2 3 6
>>> type(sliced1)
<class '__main__.SubclassedDataFrame'>
>>> sliced2 = df['A']
>>> sliced2
0 1
1 2
2 3
Name: A, dtype: int64
>>> type(sliced2)
<class '__main__.SubclassedSeries'>
要让原始数据结构具有其他属性,您应该让pandas知道添加了哪些属性。pandas将未知属性映射到覆写__getattribute__
的数据名。可以通过以下两种方法之一定义原始属性:
为不会传递给操作结果的临时属性定义_internal_names
和_internal_names_set
。
为将传递给操作结果的常规属性定义_metadata
。
下面是定义两个原始属性的示例,“internal_cache”作为临时属性,“added_property”作为普通属性。
class SubclassedDataFrame2(pd.DataFrame):
# temporary properties
_internal_names = pd.DataFrame._internal_names + ['internal_cache']
_internal_names_set = set(_internal_names)
# normal properties
_metadata = ['added_property']
@property
def _constructor(self):
return SubclassedDataFrame2
>>> df = SubclassedDataFrame2({'A': [1, 2, 3], 'B': [4, 5, 6], 'C': [7, 8, 9]})
>>> df
A B C
0 1 4 7
1 2 5 8
2 3 6 9
>>> df.internal_cache = 'cached'
>>> df.added_property = 'property'
>>> df.internal_cache
cached
>>> df.added_property
property
# properties defined in _internal_names is reset after manipulation
>>> df[['A', 'B']].internal_cache
AttributeError: 'SubclassedDataFrame2' object has no attribute 'internal_cache'
# properties defined in _metadata are retained
>>> df[['A', 'B']].added_property
property
子类化Series
和DataFrame
有以下注意点:
Series子类
和DataFrame子类
的相互转换——无需手动编写代码。# -*- coding: utf-8 -*-
"""
Created on Thu Jun 18 11:31:36 2020
@author: sixing liu, yaru chen
"""
import pandas as pd
class SubSeries(pd.Series):
@property
def _constructor(self):
return SubSeries
@property
def _constructor_expanddim(self):
return SubDataFrame
class SubDataFrame(pd.DataFrame):
_metadata = ['freq']
@property
def _constructor(self):
return SubDataFrame
@property
def _constructor_sliced(self):
return SubSeries
@pd.api.extensions.register_dataframe_accessor("myclass")
class MyAccessor:
def __init__(self, pandas_obj):
self._validate(pandas_obj)
self._obj = pandas_obj
@staticmethod
def _validate(obj):
pass
def myfunction(self):
# plot this array's data on a map, e.g., using Cartopy
print('this is Accessor function')
>>>mydf = SubDataFrame({'A': [1, 2, 3], 'B': [4, 5, 6], 'C': [7, 8, 9]})
>>>type(mydf)
Out: __main__.SubDataFrame
>>>mydf.myclass.myfunction()
Out: this is Accessor function
完整测试:
>>> myseries = SubSeries([1, 2, 3])
>>> type(myseries)
Out: __main__.SubSeries
>>>mydf = SubDataFrame({'A': [1, 2, 3], 'B': [4, 5, 6], 'C': [7, 8, 9]})
>>>type(mydf)
Out: __main__.SubDataFrame
>>>sliced = mydf['A']
>>>type(sliced)
Out: __main__.SubSeries
>>>mydf.myclass.myfunction()
Out: this is Accessor function
>>>sliced.myclass.myfunction()
Out: AttributeError: 'SubSeries' object has no attribute 'myclass'
从0.25版本开始,pandas可以通过第三方绘制后端来扩展。其主要思想是让用户选择一个不同于基于Matplotlib提供的绘图后端。例如:
>>> pd.set_option('plotting.backend', 'backend.module')
>>> pd.Series([1, 2, 3]).plot()
这或多或少相当于:
>>> import backend.module
>>> backend.module.plot(pd.Series([1, 2, 3]))
然后,后端模块可以使用其他可视化工具(Bokeh、Altair等)生成绘图。
实现绘图后端的库应使用入口点,使其后端对pandas可见。主键是 "pandas_plotting_backends"
。例如,以下默认方式为“matplotlib”后端。
# in setup.py
setup( # noqa: F821
...,
entry_points={
"pandas_plotting_backends": [
"matplotlib = pandas:plotting._matplotlib",
],
},
)
更多第三方绘图工具后台见
plot方法作为pandas的第三方接入接口,核心实现方式为CachedAccessor
类,笔者会在后面的博客中进行介绍。