Pandas 集成#
为了与 pandas 进行交互,PyArrow 提供了各种转换例程,用于消费 pandas 结构并将其转换回 pandas 结构。
注意
虽然 pandas 使用 NumPy 作为后端,但它有足够的特殊性(例如不同的类型系统和对空值的支持),这与 NumPy 集成 是一个单独的主题。
要遵循本文档中的示例,请确保运行
In [1]: import pandas as pd
In [2]: import pyarrow as pa
数据帧#
在 Arrow 中,等效于 pandas DataFrame 的是 Table。两者都由一组长度相等的命名列组成。虽然 pandas 仅支持扁平列,但 Table 还提供嵌套列,因此它可以表示比 DataFrame 更多的数据,因此并非总是可以进行完整转换。
通过调用 pyarrow.Table.to_pandas()
完成从 Table 到 DataFrame 的转换。反之,则通过使用 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
数据。有关此方面的更多信息以及如何禁用此逻辑,请参阅下面的部分。
序列#
在 Arrow 中,与 pandas Series 最相似的结构是 Array。它是一个向量,其中包含与线性内存相同类型的数据。可以使用 pyarrow.Array.from_pandas()
将 pandas Series 转换为 Arrow Array。由于 Arrow Array 始终是可空的,因此您可以使用可选的 mask
参数来标记所有空条目。
处理 pandas 索引#
诸如 pyarrow.Table.from_pandas()
之类的方法具有一个 preserve_index
选项,该选项定义如何保留(存储)或不保留(不存储)相应 pandas 对象的 index
成员中的数据。此数据使用内部 arrow::Schema
对象中的架构级元数据进行跟踪。
preserve_index
的默认值为 None
,其行为如下
RangeIndex
仅作为元数据存储,不需要额外的存储。其他索引类型在生成的
Table
中存储为一个或多个物理数据列
要完全不存储索引,请传递 preserve_index=False
。由于在某些有限的场景中(例如在 Parquet 文件中存储多个 DataFrame 对象),存储 RangeIndex
可能会导致问题,要强制将所有索引数据序列化到生成的表中,请传递 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 0x7fe3e1705540>
[
"a",
"b",
"c"
]
In [11]: chunk.indices
Out[11]:
<pyarrow.lib.Int8Array object at 0x7fe3e1705900>
[
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 0x7fe3e1705f00>
[
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)。Arrows 支持这些类型的往返转换
>>> 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 将不会使用这些可空 dtypes。
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 当前支持的所有可为空的 dtype,则此字典变为
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
,在整个表转换完成之前也无法释放任何内存。