扩展类型

扩展数组是对常规 Arrow Array 对象的封装，提供一些定制行为和/或存储。扩展类型的一个常见用例是定义 Arrow Array 与 R 对象之间的定制转换，当默认转换很慢或丢失对数组中值解释很重要的元数据时。对于大多数类型，内置的 vctrs 扩展类型可能就足够了。

用法

new_extension_type(
  storage_type,
  extension_name,
  extension_metadata = raw(),
  type_class = ExtensionType
)

new_extension_array(storage_array, extension_type)

register_extension_type(extension_type)

reregister_extension_type(extension_type)

unregister_extension_type(extension_name)

参数

storage_type

底层存储数组的数据类型。

extension_name

扩展名。这应该使用“点”语法进行命名空间化（即，“some_package.some_type”）。命名空间“arrow”保留给 Apache Arrow 库定义的扩展类型。

extension_metadata

一个包含类型序列化版本的 raw() 或 character() 向量。字符向量必须长度为 1，并在转换为 raw() 之前转换为 UTF-8。

type_class

一个 R6::R6Class，其 $new() 类方法将用于构造类型的新实例。

storage_array

底层存储的 Array 对象。

extension_type

一个 ExtensionType 实例。

返回值

• new_extension_type() 根据指定的 type_class 返回一个 ExtensionType 实例。

• new_extension_array() 返回一个 ExtensionArray，其 $type 对应于 extension_type。

• register_extension_type()、unregister_extension_type() 和 reregister_extension_type() 返回 NULL，不可见。

详情

这些函数创建、注册和注销 ExtensionType 和 ExtensionArray 对象。要使用扩展类型，您需要

• 定义一个继承自 ExtensionType 的 R6::R6Class 并重新实现一个或多个方法（例如，deserialize_instance()）。

• 创建一个类型构造函数（例如，my_extension_type()），它调用 new_extension_type() 来创建一个 R6 实例，该实例可以用作包中其他地方的 数据类型。

• 创建一个数组构造函数（例如，my_extension_array()），它调用 new_extension_array() 来创建扩展类型的 Array 实例。

• 使用您的构造函数创建扩展类型的虚拟实例，并使用 register_extension_type() 注册。

如果在 R 包中定义扩展类型，您可能希望在该包的 .onLoad() 钩子中使用 reregister_extension_type()，因为您的包在开发过程中可能会在同一个 R 会话中重新加载，并且如果为相同的 extension_name 调用 register_extension_type() 两次，它将出错。有关使用大多数这些功能的扩展类型的示例，请参见 vctrs_extension_type()。

示例

# Create the R6 type whose methods control how Array objects are
# converted to R objects, how equality between types is computed,
# and how types are printed.
QuantizedType <- R6::R6Class(
  "QuantizedType",
  inherit = ExtensionType,
  public = list(
    # methods to access the custom metadata fields
    center = function() private$.center,
    scale = function() private$.scale,

    # called when an Array of this type is converted to an R vector
    as_vector = function(extension_array) {
      if (inherits(extension_array, "ExtensionArray")) {
        unquantized_arrow <-
          (extension_array$storage()$cast(float64()) / private$.scale) +
          private$.center

        as.vector(unquantized_arrow)
      } else {
        super$as_vector(extension_array)
      }
    },

    # populate the custom metadata fields from the serialized metadata
    deserialize_instance = function() {
      vals <- as.numeric(strsplit(self$extension_metadata_utf8(), ";")[[1]])
      private$.center <- vals[1]
      private$.scale <- vals[2]
    }
  ),
  private = list(
    .center = NULL,
    .scale = NULL
  )
)

# Create a helper type constructor that calls new_extension_type()
quantized <- function(center = 0, scale = 1, storage_type = int32()) {
  new_extension_type(
    storage_type = storage_type,
    extension_name = "arrow.example.quantized",
    extension_metadata = paste(center, scale, sep = ";"),
    type_class = QuantizedType
  )
}

# Create a helper array constructor that calls new_extension_array()
quantized_array <- function(x, center = 0, scale = 1,
                            storage_type = int32()) {
  type <- quantized(center, scale, storage_type)
  new_extension_array(
    Array$create((x - center) * scale, type = storage_type),
    type
  )
}

# Register the extension type so that Arrow knows what to do when
# it encounters this extension type
reregister_extension_type(quantized())

# Create Array objects and use them!
(vals <- runif(5, min = 19, max = 21))
#> [1] 19.07557 19.97832 19.76972 19.27137 20.76730

(array <- quantized_array(
  vals,
  center = 20,
  scale = 2^15 - 1,
  storage_type = int16()
)
)
#> ExtensionArray
#> <QuantizedType <20;32767>>
#> [
#>   -30290,
#>   -710,
#>   -7545,
#>   -23874,
#>   25142
#> ]

array$type$center()
#> [1] 20
array$type$scale()
#> [1] 32767

as.vector(array)
#> [1] 19.07559 19.97833 19.76974 19.27140 20.76730