扩展 pandas#

虽然 pandas 提供了丰富的方法、容器和数据类型，但您的需求可能无法完全满足。pandas 提供了一些扩展 pandas 的选项。

注册自定义访问器#

库可以使用装饰器 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

现在用户可以使用 geo 命名空间访问你的方法：

>>> 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 对象的便捷方法。如果你编写了一个自定义访问器，请提交一个拉取请求，将其添加到我们的 生态系统 页面。

我们强烈建议在访问器的 __init__ 中验证数据。在我们的 GeoAccessor 中，我们验证数据是否包含预期的列，如果验证失败则引发 AttributeError 。对于 Series 访问器，如果访问器仅适用于某些数据类型，则应验证 dtype 。

扩展类型#

备注

pandas.api.extensions.ExtensionDtype 和 pandas.api.extensions.ExtensionArray API 在 pandas 1.5 之前是实验性的。从 1.5 版本开始，未来的更改将遵循 pandas 弃用政策。

pandas 定义了一个接口，用于实现 扩展 NumPy 类型系统的数据类型和数组。pandas 本身使用扩展系统来处理一些 NumPy 中没有的内置类型（分类、周期、区间、带时区的时间）。

库可以定义一个自定义数组和数据类型。当 pandas 遇到这些对象时，它们将被正确处理（即不会转换为对象的 ndarray）。许多方法，如 pandas.isna() 将分派到扩展类型的实现。

如果你正在构建一个实现该接口的库，请在 生态系统页面 上公开它。

该接口由两个类组成。

ExtensionDtype#

pandas.api.extensions.ExtensionDtype 类似于 numpy.dtype 对象。它描述了数据类型。实现者需要负责一些独特的项目，比如名称。

一个特别重要的项目是 type 属性。这应该是作为数据标量类型的类。例如，如果你正在为一个IP地址数据编写扩展数组，这可能是 ipaddress.IPv4Address。

请参阅 extension dtype source 以了解接口定义。

pandas.api.extensions.ExtensionDtype 可以注册到 pandas 中，以允许通过字符串 dtype 名称创建。这允许使用注册的字符串名称实例化 Series 和 .astype()，例如 'category' 是 CategoricalDtype 的注册字符串访问器。

有关如何注册数据类型的更多信息，请参见 extension dtype dtypes。

ExtensionArray#

这个类提供了所有类似数组的功能。ExtensionArrays 被限制为 1 维。一个 ExtensionArray 通过 dtype 属性与一个 ExtensionDtype 相关联。

pandas 对其扩展数组如何通过 __new__ 或 __init__ 创建没有任何限制，并且对您如何存储数据没有任何限制。我们确实要求您的数组能够转换为 NumPy 数组，即使这种转换相对昂贵（如 Categorical 的情况）。

它们可能由零个、一个或多个 NumPy 数组支持。例如，pandas.Categorical 是一个由两个数组支持的扩展数组，一个用于代码，一个用于类别。一个 IPv6 地址数组可能由一个包含两个字段的 NumPy 结构化数组支持，一个用于较低的 64 位，一个用于较高的 64 位。或者它们可能由其他存储类型支持，如 Python 列表。

请参阅 extension array source 以获取接口定义。文档字符串和注释中包含了正确实现接口的指导。

ExtensionArray 操作符支持#

默认情况下，ExtensionArray 类没有定义操作符。为您的 ExtensionArray 提供操作符支持有两种方法：

  1. 定义 ExtensionArray 子类上的每个运算符。

  2. 使用来自 pandas 的运算符实现，该实现依赖于已经在 ExtensionArray 的基础元素（标量）上定义的运算符。

备注

无论采用哪种方法，如果您希望在涉及与NumPy数组的二元运算时调用您的实现，您可能需要设置 __array_priority__。

对于第一种方法，您定义选定的操作符，例如 __add__ 、 __le__ 等，这些是您希望 ExtensionArray 子类支持的操作符。

第二种方法假设 ExtensionArray 的基础元素（即标量类型）已经定义了各个运算符。换句话说，如果你的 ExtensionArray 命名为 MyExtensionArray ，并且每个元素都是 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 之间的操作保持一致，我们建议 不要 在二元操作中处理 Series 和 Indexes。相反，您应该检测这些情况并返回 NotImplemented。当 pandas 遇到类似 op(Series, ExtensionArray) 的操作时，pandas 将

  1. 从 Series 中解包数组（Series.array）

  2. 调用 result = op(values, ExtensionArray)

  3. 将结果重新包装在一个 Series 中

NumPy 通用函数#

Series 实现了 __array_ufunc__。作为实现的一部分，pandas 从 Series 中解包 ExtensionArray，应用 ufunc，并在必要时重新打包。

如果适用，我们强烈建议您在扩展数组中实现 __array_ufunc__ 以避免强制转换为 ndarray。有关示例，请参见 NumPy 文档。

作为您实现的一部分，我们要求在 inputs 中检测到 pandas 容器（Series、DataFrame、Index）时，您应依赖 pandas。如果存在这些容器中的任何一个，您应返回 NotImplemented。pandas 将负责从容器中解包数组，并使用解包后的输入重新调用 ufunc。

测试扩展数组#

我们提供了一个测试套件，以确保您的扩展数组满足预期的行为。要使用测试套件，您必须提供几个 pytest 固件并继承自基础测试类。所需的固件可以在 pandas-dev/pandas 中找到。

要使用测试，请对其进行子类化：

from pandas.tests.extension import base


class TestConstructors(base.BaseConstructorsTests):
    pass

请参阅 pandas-dev/pandas 以获取所有可用测试的列表。

与 Apache Arrow 的兼容性#

一个 ExtensionArray 可以通过实现两个方法 ExtensionArray.__arrow_array__ 和 ExtensionDtype.__from_arrow__ 来支持转换为 / 从 pyarrow 数组（从而例如支持序列化为 Parquet 文件格式）。

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__ 方法控制从 pyarrow 转换回 pandas ExtensionArray。此方法接收一个 pyarrow Array 或 ChunkedArray 作为唯一参数，并预期返回适用于此 dtype 和传递值的适当 pandas ExtensionArray：

class ExtensionDtype:
    ...

    def __from_arrow__(self, array: pyarrow.Array/ChunkedArray) -> ExtensionArray:
        ...

更多信息请参见 Arrow 文档。

这些方法已经为 pandas 中包含的可空整数和字符串扩展数据类型实现，并确保往返于 pyarrow 和 Parquet 文件格式。

子类化 pandas 数据结构#

警告

在考虑子类化 pandas 数据结构之前，有一些更简单的替代方案。

  1. 带有 管道 的可扩展方法链

  2. 使用 组合 。参见 这里。

  3. 通过 注册一个访问器 进行扩展

  4. 通过 扩展类型 进行扩展

本节描述如何对 pandas 数据结构进行子类化以满足更具体的需求。有两个需要注意的点：

  1. 覆盖构造函数属性。

  2. 定义原始属性

备注

你可以在 geopandas 项目中找到一个很好的例子。

覆盖构造函数属性#

每个数据结构都有几个 构造函数属性 用于返回作为操作结果的新数据结构。通过重写这些属性，您可以在 pandas 数据操作中保留子类。

在子类上可以定义3个可能的构造函数属性：

  • DataFrame/Series._constructor: 当操作结果与原始数据具有相同维度时使用。

  • DataFrame._constructor_sliced: 当 DataFrame (子-)类的操作结果应该是 Series (子-)类时使用。

  • Series._constructor_expanddim: 当一个 Series (子)类操作结果应该是一个 DataFrame (子)类时使用，例如 Series.to_frame()。

下面的例子展示了如何定义 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__。定义原始属性可以通过以下两种方式之一完成：

  1. 为不会传递给操作结果的临时属性定义 _internal_names 和 _internal_names_set。

  2. 为将被传递到操作结果的普通属性定义 _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

绘图后端#

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"。例如，pandas 注册默认的 “matplotlib” 后端如下。

# in setup.py
setup(  # noqa: F821
    ...,
    entry_points={
        "pandas_plotting_backends": [
            "matplotlib = pandas:plotting._matplotlib",
        ],
    },
)

更多关于如何实现第三方绘图后端的信息可以在 pandas-dev/pandas 找到。

与第三方类型的算术运算#

为了控制自定义类型和 pandas 类型之间的算术运算方式，请实现 __pandas_priority__。类似于 numpy 的 __array_priority__ 语义，DataFrame、Series 和 Index 对象的算术方法将委托给 other，如果它有一个值更高的 __pandas_priority__ 属性。

默认情况下，pandas 对象尝试与其他对象进行操作，即使它们不是 pandas 已知的类型：

>>> pd.Series([1, 2]) + [10, 20]
0    11
1    22
dtype: int64

在上面的例子中，如果 [10, 20] 是一个可以理解为列表的自定义类型，pandas 对象仍将以相同的方式对其进行操作。

在某些情况下，将操作委托给其他类型是有用的。例如，假设我实现了一个自定义列表对象，并且我希望将我的自定义列表与 pandas Series 相加的结果是我的列表实例，而不是像前一个示例中那样的 Series。现在可以通过定义我的自定义列表的 __pandas_priority__ 属性，并将其设置为比我希望操作的 pandas 对象的优先级更高的值来实现这一点。

__pandas_priority__ 的 DataFrame、Series 和 Index 分别是 4000、3000 和 2000。基础 ExtensionArray.__pandas_priority__ 是 1000。

class CustomList(list):
    __pandas_priority__ = 5000

    def __radd__(self, other):
        # return `self` and not the addition for simplicity
        return self

custom = CustomList()
series = pd.Series([1, 2, 3])

# Series refuses to add custom, since it's an unknown type with higher priority
assert series.__add__(custom) is NotImplemented

# This will cause the custom class `__radd__` being used instead
assert series + custom is custom