pyarrow.RunEndEncodedArray#

class pyarrow.RunEndEncodedArray#

基类：Array

用于 Arrow 游程编码（run-end encoded）数组的具体类。

__init__(*args, **kwargs)#

方法

`__init__`(args, *kwargs)
`buffers`(self)	返回指向此数组物理存储的 Buffer 对象列表。
`cast`(self[, target_type, safe, options, ...])	将数组值转换为另一种数据类型
`copy_to`(self, destination)	构造一个数组的副本，并将所有缓冲区放置在目标设备上。
`dictionary_encode`(self[, null_encoding])	计算数组的字典编码表示。
`diff`(self, Array other)	将此数组的内容与另一个数组进行比较。
`drop_null`(self)	从数组中移除缺失值。
`equals`(self, Array other)
`fill_null`(self, fill_value)	用法请参见 `pyarrow.compute.fill_null()`。
`filter`(self, mask, *[, null_selection_behavior])	从数组中选择值。
`find_physical_length`(self)	查找此 REE 数组的物理长度。
`find_physical_offset`(self)	查找此 REE 数组的物理偏移量。
`from_arrays`(run_ends, values[, type])	根据 run_ends（游程末尾）和 values（值）数组构造 RunEndEncodedArray。
`from_buffers`(DataType type, length, buffers)	根据构成数组的所有参数构造一个 RunEndEncodedArray。
`from_pandas`(obj[, mask, type])	将 pandas.Series 转换为 Arrow 数组。
`get_total_buffer_size`(self)	数组引用的每个缓冲区中字节数的总和。
`index`(self, value[, start, end, memory_pool])	查找值的第一个索引。
`is_nan`(self)	返回指示 NaN 值的 BooleanArray。
`is_null`(self, *[, nan_is_null])	返回指示 null 值的 BooleanArray。
`is_valid`(self)	返回指示非 null 值的 BooleanArray。
`slice`(self[, offset, length])	计算此数组的零拷贝切片。
`sort`(self[, order])	对数组进行排序
`sum`(self, **kwargs)	对数值数组中的值求和。
`take`(self, indices)	从数组中选择值。
`to_numpy`(self[, zero_copy_only, writable])	返回此数组的 NumPy 视图或副本。
`to_pandas`(self[, memory_pool, categories, ...])	根据需要转换为 pandas 兼容的 NumPy 数组或 DataFrame
`to_pylist`(self, *[, maps_as_pydicts])	转换为原生 Python 对象列表。
`to_string`(self, *, int indent=2, ...)	呈现数组的“美化打印”字符串表示形式。
`tolist`(self)	to_pylist 的别名，与 NumPy 保持兼容。
`unique`(self)	计算数组中的不同元素。
`validate`(self, *[, full])	执行验证检查。
`value_counts`(self)	计算数组中唯一元素的计数。
`view`(self, target_type)	将数组作为另一种数据类型返回零拷贝“视图”。

属性

`device_type`	数组所在的设备类型。
`is_cpu`	数组是否可被 CPU 访问。
`nbytes`	数组元素消耗的总字节数。
`null_count`
`offset`	指向另一个数组数据的相对位置。
`run_ends`	一个保存每个游程末尾逻辑索引的数组。
`statistics`	数组的统计信息。
`type`
`值`	一个保存每个游程值的数组。

buffers(self)#

返回指向此数组物理存储的 Buffer 对象列表。

为了正确解释这些缓冲区，您还需要应用偏移量乘以存储数据类型的大小。

cast(self, target_type=None, safe=None, options=None, memory_pool=None)#

将数组值转换为另一种数据类型

用法请参见 pyarrow.compute.cast()。

参数:

target_typeDataType, 默认 None: 要转换为的目标类型。
safebool, 默认 True: 是否检查转换错误（如溢出）。
optionsCastOptions, 默认 None: 通过 CastOptions 传递的额外检查
memory_poolMemoryPool, 可选: 函数执行期间用于分配的内存池。

返回：

castArray

copy_to(self, destination)#

构造一个数组的副本，并将所有缓冲区放置在目标设备上。

此方法递归地将数组及其子数组的缓冲区复制到目标 MemoryManager 设备，并返回新的数组。

参数:

destinationpyarrow.MemoryManager 或 pyarrow.Device: 要将数组复制到的目标设备。

返回：

数组

device_type#

数组所在的设备类型。

返回：

DeviceAllocationType

dictionary_encode(self, null_encoding='mask')#

计算数组的字典编码表示。

完整用法请参见 pyarrow.compute.dictionary_encode()。

参数:

null_encodingstr, 默认 “mask”: 如何处理 null 条目。

返回：

encodedDictionaryArray: 此数组的字典编码版本。

diff(self, Array other)#

将此数组的内容与另一个数组进行比较。

返回一个包含此数组（左侧）与另一个数组（右侧）差异结果的字符串。

参数:

otherArray: 要与此数组进行比较的另一个数组。

返回：

diffstr: 人类可读的差异打印输出。

示例

>>> import pyarrow as pa
>>> left = pa.array(["one", "two", "three"])
>>> right = pa.array(["two", None, "two-and-a-half", "three"])
>>> print(left.diff(right))

@@ -0, +0 @@ -“one” @@ -2, +1 @@ +null +”two-and-a-half”

drop_null(self)#: 从数组中移除缺失值。

equals(self, Array other)#

参数:

otherpyarrow.Array

返回：

bool

fill_null(self, fill_value)#

用法请参见 pyarrow.compute.fill_null()。

参数:

fill_valueany: null 条目的替代值。

返回：

resultArray: 一个新数组，其中 null 已被给定值替换。

filter(self, mask, *, null_selection_behavior='drop')#

从数组中选择值。

完整用法请参见 pyarrow.compute.filter()。

参数:

maskArray 或 array-like: 用于过滤数组的布尔掩码。
null_selection_behaviorstr, 默认 “drop”: 如何处理掩码中的 null 值。

返回：

filteredArray: 一个相同类型的数组，仅包含布尔掩码选择的元素。

find_physical_length(self)#

查找此 REE 数组的物理长度。

REE 的物理长度是表示从偏移量到长度的逻辑值范围所需的物理值（和游程末尾）的数量。

此函数使用二分搜索，因此其代价为 O(log N)。

find_physical_offset(self)#

查找此 REE 数组的物理偏移量。

这是包含数组第一个逻辑元素值的游程的偏移量（考虑了数组自身的偏移量）。

此函数使用二分搜索，因此其代价为 O(log N)。

static from_arrays(run_ends, values, type=None)#

根据 run_ends（游程末尾）和 values（值）数组构造 RunEndEncodedArray。

参数:

run_endsArray (int16, int32, 或 int64 type): run_ends 数组。
valuesArray (任意 type): values 数组。
typepyarrow.DataType, 可选: run_end_encoded(run_end_type, value_type) 数组类型。

返回：

RunEndEncodedArray

static from_buffers(DataType type, length, buffers, null_count=-1, offset=0, children=None)#

根据构成数组的所有参数构造一个 RunEndEncodedArray。

RunEndEncodedArray 没有缓冲区，只有子数组，但需要此实现以满足 Array 接口。

参数:

typeDataType: run_end_encoded(run_end_type, value_type) 类型。
lengthint: 游程编码数组的逻辑长度。预期与 run_ends 数组（children[0]）的最后一个值减去偏移量一致。
buffersList[Buffer]: 空列表或 [None]。
null_countint, 默认 -1: 数组中空条目的数量。游程编码数组被指定为没有有效位，null_count 始终等于 0。
offsetint, 默认 0: 数组从每个缓冲区起始处的逻辑偏移量（按值，而非按字节）。
childrenList[Array]: 包含 run_ends 和 values 数组的嵌套类型子项。

返回：

RunEndEncodedArray

static from_pandas(obj, mask=None, type=None, bool safe=True, MemoryPool memory_pool=None)#

将 pandas.Series 转换为 Arrow 数组。

此方法使用 Pandas 关于哪些值指示 null 的语义。有关从数组或序列到 Arrow 数组的更通用转换，请参阅 pyarrow.array。

参数:

objndarray, pandas.Series, array-like
maskarray (bool), 可选: 指示哪些值为空（True）或不为空（False）。
typepyarrow.DataType: 尝试强制转换到的显式类型，否则将根据数据进行推断。
safebool, 默认 True: 检查是否存在溢出或其他不安全的转换。
memory_poolpyarrow.MemoryPool, 可选: 如果未传递，将从当前设置的默认内存池分配内存。

返回：

arraypyarrow.Array 或 pyarrow.ChunkedArray: 如果对象数据溢出二进制缓冲区，则返回 ChunkedArray。

备注

本地化时间戳目前将作为 UTC 返回（pandas 的原生表示）。不带时区的数据将被隐式解释为 UTC。

get_total_buffer_size(self)#

数组引用的每个缓冲区中字节数的总和。

数组可能仅引用缓冲区的一部分。在这种情况下，此方法将高估并返回整个缓冲区的字节大小。

如果一个缓冲区被多次引用，则它只会被计数一次。

index(self, value, start=None, end=None, *, memory_pool=None)#

查找值的第一个索引。

完整用法请参见 pyarrow.compute.index()。

参数:

valueScalar 或对象: 要在数组中查找的值。
startint, 可选: 查找 value 的起始索引。
endint, 可选: 查找 value 的结束索引。
memory_poolMemoryPool, 可选: 用于潜在内存分配的内存池。

返回：

indexInt64Scalar: 该值在数组中的索引（如果未找到则为 -1）。

is_cpu#: 数组是否可被 CPU 访问。

is_nan(self)#

返回指示 NaN 值的 BooleanArray。

返回：

arraybool Array

is_null(self, *, nan_is_null=False)#

返回指示 null 值的 BooleanArray。

参数:

nan_is_nullbool (可选, 默认 False): 是否应将浮点 NaN 值也视为 null。

返回：

arraybool Array

is_valid(self)#: 返回指示非 null 值的 BooleanArray。

nbytes#

数组元素消耗的总字节数。

换句话说，是所有引用的缓冲区范围中字节的总和。

与 get_total_buffer_size 不同，此方法会考虑数组偏移量。

如果数组之间共享缓冲区，则共享部分将被多次计算。

字典数组的字典将始终被完整计算，即使数组仅引用了字典的一部分。

null_count#

offset#

指向另一个数组数据的相对位置。

其目的是实现零拷贝切片。此值默认为零，但必须应用于所有涉及物理存储缓冲区的操作中。

run_ends#

一个保存每个游程末尾逻辑索引的数组。

已应用数组的物理偏移量。

slice(self, offset=0, length=None)#

计算此数组的零拷贝切片。

参数:

offsetint, 默认 0: 从数组起始处偏移以进行切片。
lengthint, 默认 None: 切片长度（默认是从偏移量开始到数组末尾）。

返回：

slicedArray: 一个具有相同数据类型并包含切片值的数组。

sort(self, order='ascending', **kwargs)#

对数组进行排序

参数:

orderstr, 默认 “ascending”: 对值进行排序的顺序。接受的值为 “ascending”（升序）、“descending”（降序）。
**kwargsdict, 可选: 额外的排序选项。正如 SortOptions 所允许的那样。

返回：

resultArray

statistics#: 数组的统计信息。

sum(self, **kwargs)#

对数值数组中的值求和。

完整用法请参见 pyarrow.compute.sum()。

参数:

**kwargsdict, 可选: 传递给 pyarrow.compute.sum() 的选项。

返回：

sumScalar: 包含求和值的标量。

take(self, indices)#

从数组中选择值。

完整用法请参见 pyarrow.compute.take()。

参数:

indicesArray 或 array-like: 要返回其值的数组索引。

返回：

takenArray: 一个具有相同数据类型并包含提取值的数组。

to_numpy(self, zero_copy_only=True, writable=False)#

返回此数组的 NumPy 视图或副本。

默认情况下，尝试返回此数组的视图。这仅支持与 NumPy 具有相同内存布局（例如整数、浮点数...）且没有任何 null 值的原始数组。

对于扩展数组，此方法仅委托给底层的存储数组。

参数:

zero_copy_onlybool, 默认 True: 如果为 True，则如果转换为 numpy 数组需要复制底层数据（例如存在 null 或非原始类型），则会引发异常。
writablebool, 默认 False: 对于使用零拷贝（Arrow 数据视图）创建的 numpy 数组，结果数组不可写（Arrow 数据是不可变的）。通过将其设置为 True，将制作数组副本以确保其可写。

返回：

arraynumpy.ndarray

to_pandas(self, memory_pool=None, categories=None, bool strings_to_categorical=False, bool zero_copy_only=False, bool integer_object_nulls=False, bool date_as_object=True, bool timestamp_as_object=False, bool use_threads=True, bool deduplicate_objects=True, bool ignore_metadata=False, bool safe=True, bool split_blocks=False, bool self_destruct=False, str maps_as_pydicts=None, types_mapper=None, bool coerce_temporal_nanoseconds=False)#

根据需要转换为 pandas 兼容的 NumPy 数组或 DataFrame

参数:

memory_poolMemoryPool, 默认 None

用于分配的 Arrow MemoryPool。如果未传递，则使用默认内存池。

categorieslist, 默认 empty

应作为 pandas.Categorical 返回的字段列表。仅适用于表格类数据结构。

strings_to_categoricalbool, 默认 False

将字符串 (UTF8) 和二进制类型编码为 pandas.Categorical。

zero_copy_onlybool, 默认 False

如果此函数调用需要复制底层数据，则引发 ArrowException。

integer_object_nullsbool, 默认 False

将带有 null 的整数转换为对象

date_as_objectbool, 默认 True

将日期转换为对象。如果为 False，则转换为具有等效时间单位的 datetime64 dtype（如果支持）。注意：在 pandas 版本 < 2.0 中，仅支持 datetime64[ns] 转换。

timestamp_as_objectbool, 默认 False

将非纳秒时间戳 (np.datetime64) 转换为对象。这在 pandas 1.x 版本中很有用，如果您有不适合纳秒时间戳正常日期范围（公元 1678 年至 2262 年）的时间戳。pandas 2.0 版本支持非纳秒时间戳。如果为 False，则所有时间戳都将转换为 datetime64 dtype。

use_threadsbool, 默认 True

是否使用多个线程并行化转换。

deduplicate_objectsbool, 默认 True

创建时不要创建多个 Python 对象副本，以节省内存使用。转换速度会变慢。

ignore_metadatabool, 默认 False

如果为 True，则在存在时，不使用‘pandas’元数据来重建 DataFrame 索引

safebool, 默认 True

对于某些数据类型，需要进行转换才能将数据存储在 pandas DataFrame 或 Series 中（例如，时间戳在 pandas 中始终以纳秒存储）。此选项控制这是否为安全转换。

split_blocksbool, 默认 False

如果为 True，则从 RecordBatch 或 Table 创建 pandas.DataFrame 时，为每一列生成一个内部“块”。虽然这可以暂时减少内存，但请注意，各种 pandas 操作可能会触发“合并”，这可能会导致内存使用量激增。

self_destructbool, 默认 False

实验性：如果为 True，则尝试在将 Arrow 对象转换为 pandas 时释放原始 Arrow 内存。如果您在使用此选项调用 to_pandas 后使用该对象，程序将会崩溃。

请注意，您可能不会总是看到内存使用量的改善。例如，如果多个列共享底层分配，则在转换所有列之前，无法释放内存。

maps_as_pydictsstr, 可选, 默认 None

有效值为 None、‘lossy’ 或 ‘strict’。默认行为 (None) 是将 Arrow Map 数组转换为与 Arrow Map 顺序相同的原生 Python 关联列表（元组列表），如 [(key1, value1), (key2, value2), …]。

如果为 ‘lossy’ 或 ‘strict’，则将 Arrow Map 数组转换为原生 Python 字典。这可能会更改 (key, value) 对的排序，并会去除多个键的重复项，从而导致可能的数据丢失。

如果为 ‘lossy’，则此键去重会导致检测到时打印警告。如果为 ‘strict’，则会在检测到时引发异常。

types_mapper函数, 默认 None

将 pyarrow DataType 映射到 pandas ExtensionDtype 的函数。这可用于覆盖内置 pyarrow 类型转换的默认 pandas 类型，或者在 Table 架构中缺少 pandas_metadata 时使用。该函数接收一个 pyarrow DataType，并预期返回一个 pandas ExtensionDtype；如果应使用该类型的默认转换，则返回 None。如果您有一个字典映射，则可以传递 dict.get 作为函数。

coerce_temporal_nanosecondsbool, 默认 False

仅适用于 pandas 版本 >= 2.0。这是一个遗留选项，用于在转换为 pandas 时将 date32、date64、duration 和 timestamp 时间单位强制转换为纳秒。这是 pandas 1.x 版本中的默认行为。如果您想在 pandas 版本 >= 2.0 中使用此强制转换以保持向后兼容性（否则不建议这样做），请将此选项设置为 True。

返回：

pandas.Series 或 pandas.DataFrame，具体取决于对象的 type。

示例

>>> import pyarrow as pa
>>> import pandas as pd

将 Table 转换为 pandas DataFrame

>>> table = pa.table([
...    pa.array([2, 4, 5, 100]),
...    pa.array(["Flamingo", "Horse", "Brittle stars", "Centipede"])
...    ], names=['n_legs', 'animals'])
>>> table.to_pandas()
   n_legs        animals
0       2       Flamingo
1       4          Horse
2       5  Brittle stars
3     100      Centipede
>>> isinstance(table.to_pandas(), pd.DataFrame)
True

将 RecordBatch 转换为 pandas DataFrame

>>> import pyarrow as pa
>>> n_legs = pa.array([2, 4, 5, 100])
>>> animals = pa.array(["Flamingo", "Horse", "Brittle stars", "Centipede"])
>>> batch = pa.record_batch([n_legs, animals],
...                         names=["n_legs", "animals"])
>>> batch
pyarrow.RecordBatch
n_legs: int64
animals: string
----
n_legs: [2,4,5,100]
animals: ["Flamingo","Horse","Brittle stars","Centipede"]
>>> batch.to_pandas()
   n_legs        animals
0       2       Flamingo
1       4          Horse
2       5  Brittle stars
3     100      Centipede
>>> isinstance(batch.to_pandas(), pd.DataFrame)
True

将 Chunked Array 转换为 pandas Series

>>> import pyarrow as pa
>>> n_legs = pa.chunked_array([[2, 2, 4], [4, 5, 100]])
>>> n_legs.to_pandas()
0      2
1      2
2      4
3      4
4      5
5    100
dtype: int64
>>> isinstance(n_legs.to_pandas(), pd.Series)
True

to_pylist(self, *, maps_as_pydicts=None)#

转换为原生 Python 对象列表。

参数:

maps_as_pydictsstr, 可选, 默认 None

有效值为 None、‘lossy’ 或 ‘strict’。默认行为 (None) 是将 Arrow Map 数组转换为与 Arrow Map 顺序相同的原生 Python 关联列表（元组列表），如 [(key1, value1), (key2, value2), …]。

如果为 ‘lossy’ 或 ‘strict’，则将 Arrow Map 数组转换为原生 Python 字典。

如果为 ‘lossy’，则每当检测到重复键时，都会打印警告。重复键的最后看到的值将出现在 Python 字典中。如果为 ‘strict’，则会在检测到时引发异常。

返回：

lstlist

to_string(self, *, int indent=2, int top_level_indent=0, int window=10, int container_window=2, bool skip_new_lines=False, int element_size_limit=100)#

呈现数组的“美化打印”字符串表示形式。

注意：对于非 CPU 设备上的数据，完整的数组会被复制到 CPU 内存中。

参数:

indentint, 默认 2: 字符串中内部项目向右缩进多少，默认为 2。
top_level_indentint, 默认 0: 整个数组的内容向右缩进多少，默认为 0。
windowint: 当数组大于窗口时，在数组的开头和结尾预览多少个原始项目。其他项目将被省略。
container_windowint: 当数组大于窗口时，在数组的开头和结尾预览多少个容器项目（例如列表数组中的列表）。
skip_new_linesbool: 数组应呈现为单行文本，还是每个元素都应在单独的行上。
element_size_limitint, 默认 100: 单个元素在截断之前允许的最大字符数。

tolist(self)#: to_pylist 的别名，与 NumPy 保持兼容。

type#

unique(self)#

计算数组中的不同元素。

返回：

uniqueArray: 一个具有相同数据类型并包含去重元素的数组。

validate(self, *, full=False)#

执行验证检查。如果验证失败，则会引发异常。

默认情况下，仅运行低成本的验证检查。传递 full=True 进行彻底的验证检查（可能为 O(n)）。

参数:

fullbool, 默认 False: 如果为 True，则运行昂贵的检查，否则仅运行低成本检查。

引发:

ArrowInvalid

value_counts(self)#

计算数组中唯一元素的计数。

返回：

StructArray: 一个 <input 类型 “Values”, int64 “Counts”> 结构体的数组

values#

一个保存每个游程值的数组。

已应用数组的物理偏移量。

view(self, target_type)#

将数组作为另一种数据类型返回零拷贝“视图”。

数据类型必须具有兼容的列式缓冲区布局

参数:

target_typeDataType: 要将其构建为视图的类型。

返回：

viewArray