扩展 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 1.5 之前，pandas.api.extensions.ExtensionDtype 和 pandas.api.extensions.ExtensionArray API 处于实验阶段。从 1.5 版本开始，未来的更改将遵循 pandas 弃用策略.

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

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

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

该接口包含两个类。

ExtensionDtype

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

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

请参阅 扩展 dtype 源代码 以了解接口定义。

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

请参阅 扩展 dtype 类型 以了解有关如何注册类型的更多信息。

ExtensionArray

此类提供所有类似数组的功能。扩展数组限于一维。扩展数组通过 dtype 属性链接到扩展 dtype。

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

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

请参阅 扩展数组源代码 以了解接口定义。文档字符串和注释包含有关如何正确实现接口的指南。

ExtensionArray 运算符支持

默认情况下，ExtensionArray 类没有定义任何运算符。为您的 ExtensionArray 提供运算符支持有两种方法。

1. 在您的 ExtensionArray 子类中定义每个运算符。

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

注意

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

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

第二种方法假设 ExtensionArray 的基础元素（即标量类型）已经定义了各个运算符。换句话说，如果您的 ExtensionArray 命名为 MyExtensionArray，并且每个元素都是 MyExtensionElement 类的实例，那么如果为 MyExtensionElement 定义了运算符，第二种方法将自动为 MyExtensionArray 定义运算符。

一个混合类，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 ndarray 之间的运算保持一致，我们建议不要在你的二元运算中处理 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 可以通过实现两种方法来支持转换为/从 pyarrow 数组（从而支持例如序列化到 Parquet 文件格式）：ExtensionArray.__arrow_array__ 和 ExtensionDtype.__from_arrow__。

The 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 中包含的可空整数和字符串扩展 dtype 实现，并确保与 pyarrow 和 Parquet 文件格式的往返。

子类化 pandas 数据结构

警告

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

1. 使用可扩展方法链与 pipe

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 对象的优先级来实现这一点。

DataFrame、Series 和 Index 的 __pandas_priority__ 分别为 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