Pandas 集成#
为了与 pandas 接口，PyArrow 提供了各种转换例程，用于消费 pandas 结构并将其转换回来。
注意
虽然 pandas 使用 NumPy 作为后端，但它有足够的特殊性（例如不同的类型系统和对空值的支持），使其与 NumPy 集成 是一个单独的主题。
要遵循本文档中的示例，请确保运行
In [1]: import pandas as pd
In [2]: import pyarrow as pa
DataFrames#
Arrow 中与 pandas DataFrame 等效的是 Table。两者都由一组等长的命名列组成。虽然 pandas 只支持平面列，但 Table 还提供嵌套列，因此它可以表示比 DataFrame 更多的数据，因此并非总是能够进行完全转换。
从 Table 到 DataFrame 的转换通过调用 pyarrow.Table.to_pandas() 完成。反向转换则通过使用 pyarrow.Table.from_pandas() 实现。
import pyarrow as pa
import pandas as pd
df = pd.DataFrame({"a": [1, 2, 3]})
# Convert from pandas to Arrow
table = pa.Table.from_pandas(df)
# Convert back to pandas
df_new = table.to_pandas()
# Infer Arrow schema from pandas
schema = pa.Schema.from_pandas(df)
默认情况下，pyarrow 尝试尽可能准确地保留和恢复 .index 数据。有关此内容的更多信息以及如何禁用此逻辑，请参阅以下部分。
Series#
在 Arrow 中，与 pandas Series 最相似的结构是 Array。它是一个向量，包含与线性内存相同类型的数据。您可以使用 pyarrow.Array.from_pandas() 将 pandas Series 转换为 Arrow Array。由于 Arrow Arrays 总是可空的，因此您可以使用 mask 参数提供一个可选掩码来标记所有空条目。
处理 pandas 索引#
诸如 pyarrow.Table.from_pandas() 之类的方法有一个 preserve_index 选项，它定义了如何保留（存储）或不保留（不存储）相应 pandas 对象的 index 成员中的数据。此数据通过内部 arrow::Schema 对象中的模式级元数据进行跟踪。
preserve_index 的默认值为 None，其行为如下：
RangeIndex作为仅元数据存储，不需要额外存储。其他索引类型在生成的
Table中作为一列或多列物理数据存储。
要完全不存储索引，请传递 preserve_index=False。由于存储 RangeIndex 在某些有限情况下（例如在 Parquet 文件中存储多个 DataFrame 对象）可能导致问题，要强制将所有索引数据序列化到结果表中，请传递 preserve_index=True。
类型差异#
根据 pandas 和 Arrow 的当前设计，无法无修改地转换所有列类型。这里的主要问题之一是 pandas 不支持任意类型的可空列。此外，datetime64 目前固定为纳秒分辨率。另一方面，Arrow 可能仍缺少对某些类型的支持。
pandas -> Arrow 转换#
源类型 (pandas) |
目标类型 (Arrow) |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Arrow -> pandas 转换#
源类型 (Arrow) |
目标类型 (pandas) |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
分类类型#
Pandas 分类 列被转换为 Arrow 字典数组，这是一种特殊数组类型，经过优化以处理重复且有限数量的可能值。
In [3]: df = pd.DataFrame({"cat": pd.Categorical(["a", "b", "c", "a", "b", "c"])})
In [4]: df.cat.dtype.categories
Out[4]: Index(['a', 'b', 'c'], dtype='object')
In [5]: df
Out[5]:
cat
0 a
1 b
2 c
3 a
4 b
5 c
In [6]: table = pa.Table.from_pandas(df)
In [7]: table
Out[7]:
pyarrow.Table
cat: dictionary<values=string, indices=int8, ordered=0>
----
cat: [ -- dictionary:
["a","b","c"] -- indices:
[0,1,2,0,1,2]]
我们可以检查创建的表的 ChunkedArray，并查看与 Pandas DataFrame 相同的类别。
In [8]: column = table[0]
In [9]: chunk = column.chunk(0)
In [10]: chunk.dictionary
Out[10]:
<pyarrow.lib.StringArray object at 0x7fdffc8ff7c0>
[
"a",
"b",
"c"
]
In [11]: chunk.indices
Out[11]:
<pyarrow.lib.Int8Array object at 0x7fdffc8ff340>
[
0,
1,
2,
0,
1,
2
]
日期时间（时间戳）类型#
Pandas 时间戳 在 Pandas 中使用 datetime64[ns] 类型，并转换为 Arrow TimestampArray。
In [12]: df = pd.DataFrame({"datetime": pd.date_range("2020-01-01T00:00:00Z", freq="h", periods=3)})
In [13]: df.dtypes
Out[13]:
datetime datetime64[ns, UTC]
dtype: object
In [14]: df
Out[14]:
datetime
0 2020-01-01 00:00:00+00:00
1 2020-01-01 01:00:00+00:00
2 2020-01-01 02:00:00+00:00
In [15]: table = pa.Table.from_pandas(df)
In [16]: table
Out[16]:
pyarrow.Table
datetime: timestamp[ns, tz=UTC]
----
datetime: [[2020-01-01 00:00:00.000000000Z,2020-01-01 01:00:00.000000000Z,2020-01-01 02:00:00.000000000Z]]
在这个例子中，Pandas 时间戳是时区感知的（本例中为 UTC），并且此信息用于创建 Arrow TimestampArray。
日期类型#
虽然在 pandas 中可以使用 datetime64[ns] 类型处理日期，但有些系统使用 Python 内置 datetime.date 对象的对象数组。
In [17]: from datetime import date
In [18]: s = pd.Series([date(2018, 12, 31), None, date(2000, 1, 1)])
In [19]: s
Out[19]:
0 2018-12-31
1 None
2 2000-01-01
dtype: object
转换为 Arrow 数组时，默认将使用 date32 类型。
In [20]: arr = pa.array(s)
In [21]: arr.type
Out[21]: DataType(date32[day])
In [22]: arr[0]
Out[22]: <pyarrow.Date32Scalar: datetime.date(2018, 12, 31)>
要使用 64 位 date64，请明确指定：
In [23]: arr = pa.array(s, type='date64')
In [24]: arr.type
Out[24]: DataType(date64[ms])
当使用 to_pandas 转换回来时，返回的是 datetime.date 对象的对象数组。
In [25]: arr.to_pandas()
Out[25]:
0 2018-12-31
1 None
2 2000-01-01
dtype: object
如果您想使用 NumPy 的 datetime64 dtype，请传递 date_as_object=False。
In [26]: s2 = pd.Series(arr.to_pandas(date_as_object=False))
In [27]: s2.dtype
Out[27]: dtype('<M8[ms]')
警告
从 Arrow 0.13 开始，参数 date_as_object 默认为 True。旧版本必须传递 date_as_object=True 才能获得此行为。
时间类型#
Pandas 数据结构中内置的 datetime.time 对象将分别转换为 Arrow time64 和 Time64Array。
In [28]: from datetime import time
In [29]: s = pd.Series([time(1, 1, 1), time(2, 2, 2)])
In [30]: s
Out[30]:
0 01:01:01
1 02:02:02
dtype: object
In [31]: arr = pa.array(s)
In [32]: arr.type
Out[32]: Time64Type(time64[us])
In [33]: arr
Out[33]:
<pyarrow.lib.Time64Array object at 0x7fdfff0a7160>
[
01:01:01.000000,
02:02:02.000000
]
转换为 pandas 时，返回的是 datetime.time 对象的数组。
In [34]: arr.to_pandas()
Out[34]:
0 01:01:01
1 02:02:02
dtype: object
可空类型#
在 Arrow 中，所有数据类型都是可空的，这意味着它们支持存储缺失值。然而，在 pandas 中，并非所有数据类型都支持缺失数据。最值得注意的是，默认的整数数据类型不支持，并且在引入缺失值时将被转换为浮点数。因此，当 Arrow 数组或表转换为 pandas 时，存在缺失值的整数列将变为浮点数。
>>> arr = pa.array([1, 2, None])
>>> arr
<pyarrow.lib.Int64Array object at 0x7f07d467c640>
[
1,
2,
null
]
>>> arr.to_pandas()
0 1.0
1 2.0
2 NaN
dtype: float64
Pandas 具有实验性的可空数据类型 (https://pandas.ac.cn/docs/user_guide/integer_na.html)。Arrow 支持这些类型的往返转换。
>>> df = pd.DataFrame({'a': pd.Series([1, 2, None], dtype="Int64")})
>>> df
a
0 1
1 2
2 <NA>
>>> table = pa.table(df)
>>> table
Out[32]:
pyarrow.Table
a: int64
----
a: [[1,2,null]]
>>> table.to_pandas()
a
0 1
1 2
2 <NA>
>>> table.to_pandas().dtypes
a Int64
dtype: object
这种往返转换之所以有效，是因为原始 pandas DataFrame 的元数据存储在 Arrow 表中。但是，如果您拥有的 Arrow 数据（例如 Parquet 文件）并非源自具有可空数据类型的 pandas DataFrame，则默认转换为 pandas 将不会使用这些可空 dtype。
pyarrow.Table.to_pandas() 方法有一个 types_mapper 关键字，可用于覆盖结果 pandas DataFrame 使用的默认数据类型。这样，您可以指示 Arrow 使用可空 dtype 创建 pandas DataFrame。
>>> table = pa.table({"a": [1, 2, None]})
>>> table.to_pandas()
a
0 1.0
1 2.0
2 NaN
>>> table.to_pandas(types_mapper={pa.int64(): pd.Int64Dtype()}.get)
a
0 1
1 2
2 <NA>
types_mapper 关键字需要一个函数，该函数将根据给定的 pyarrow 数据类型返回要使用的 pandas 数据类型。通过使用 dict.get 方法，我们可以使用字典创建这样的函数。
如果要使用 pandas 目前支持的所有可空 dtypes，则此字典变为：
dtype_mapping = {
pa.int8(): pd.Int8Dtype(),
pa.int16(): pd.Int16Dtype(),
pa.int32(): pd.Int32Dtype(),
pa.int64(): pd.Int64Dtype(),
pa.uint8(): pd.UInt8Dtype(),
pa.uint16(): pd.UInt16Dtype(),
pa.uint32(): pd.UInt32Dtype(),
pa.uint64(): pd.UInt64Dtype(),
pa.bool_(): pd.BooleanDtype(),
pa.float32(): pd.Float32Dtype(),
pa.float64(): pd.Float64Dtype(),
pa.string(): pd.StringDtype(),
}
df = table.to_pandas(types_mapper=dtype_mapping.get)
使用 pandas API 读取 Parquet 文件 (pd.read_parquet(..)) 时，也可以通过传递 use_nullable_dtypes 实现这一点。
df = pd.read_parquet(path, use_nullable_dtypes=True)
内存使用和零拷贝#
当使用各种 to_pandas 方法从 Arrow 数据结构转换为 pandas 对象时，有时必须注意与性能和内存使用相关的问题。
由于 pandas 的内部数据表示通常与 Arrow 列式格式不同，因此零拷贝转换（不需要内存分配或计算）仅在某些有限情况下才可能实现。
在最坏的情况下，调用 to_pandas 将导致内存中存在两个版本的数据，一个用于 Arrow，一个用于 pandas，从而使内存占用大约增加一倍。我们已针对这种情况实施了一些缓解措施，特别是在创建大型 DataFrame 对象时，我们将在下面进行描述。
零拷贝 Series 转换#
在某些特定情况下，可以实现从 Array 或 ChunkedArray 到 NumPy 数组或 pandas Series 的零拷贝转换。
Arrow 数据以整数（有符号或无符号
int8到int64）或浮点类型（float16到float64）存储。这包括许多数字类型以及时间戳。Arrow 数据没有空值（因为这些值使用位图表示，而 pandas 不支持位图）。
对于
ChunkedArray，数据由单个块组成，即arr.num_chunks == 1。多个块总是需要复制，因为 pandas 有连续性要求。
在这些情况下，to_pandas 或 to_numpy 将实现零拷贝。在所有其他情况下，将需要进行复制。
减少 Table.to_pandas 中的内存使用#
截至本文撰写之时，pandas 应用了一种称为“合并”的数据管理策略，将同类型的 DataFrame 列收集到二维 NumPy 数组中，内部称为“块”。我们已付出巨大努力来构建精确的“合并”块，以便在我们把数据交给 pandas.DataFrame 后，pandas 不会执行任何进一步的分配或复制。这种合并策略的明显缺点是它强制“内存翻倍”。
为了尝试限制 Table.to_pandas 期间“内存翻倍”的潜在影响，我们提供了一些选项：
split_blocks=True，启用时Table.to_pandas为每个列生成一个内部 DataFrame“块”，跳过“合并”步骤。请注意，许多 pandas 操作仍会触发合并，但峰值内存使用可能低于完全内存翻倍的最坏情况。由于此选项，我们能够在与Array和ChunkedArray零拷贝相同的情况下对列进行零拷贝转换。self_destruct=True，这会在每个列Table对象转换为 pandas 兼容表示时销毁其内部 Arrow 内存缓冲区，从而在列转换完成后立即将内存释放给操作系统。请注意，这会使调用Table对象不安全，无法进一步使用，并且任何后续调用的方法都将导致您的 Python 进程崩溃。
结合使用，调用
df = table.to_pandas(split_blocks=True, self_destruct=True)
del table # not necessary, but a good practice
在某些情况下会显著降低内存使用。如果没有这些选项，to_pandas 将始终使内存翻倍。
请注意，self_destruct=True 不保证节省内存。由于转换是逐列进行的，内存也是逐列释放的。但是，如果多个列共享底层缓冲区，则在所有这些列转换完成之前不会释放内存。特别是，由于实现细节，来自 IPC 或 Flight 的数据容易出现这种情况，因为内存将按以下方式布局：
Record Batch 0: Allocation 0: array 0 chunk 0, array 1 chunk 0, ...
Record Batch 1: Allocation 1: array 0 chunk 1, array 1 chunk 1, ...
...
在这种情况下，即使使用 self_destruct=True，在整个表转换完成之前也无法释放内存。