rockhopper 0.2.0

高维数组

Rockhopper非常专注于2D的斜行数组，然而，对于高维斜行数组的一个变体是允许的：斜行数组的行可以是多维的，而不是一维数组。

构建过程基本上与预期相符。以下展示了创建相同的多维斜行数组的3种不同方式。

import numpy as np
from rockhopper import ragged_array, RaggedArray

# Construct from nested lists.
from_nested = ragged_array([
    [[0,  1], [2, 3]],
    [[4, 5]],
    [[6, 7], [8, 9], [10, 11]],
    [[12, 13]],
])

# Construction from flat contents and either ...
flat = np.array([
    [0,  1], [2, 3], [4, 5], [6, 7], [8, 9], [10, 11], [12, 13]
])
# ... row lengths, ...
from_lengths = RaggedArray.from_lengths(flat, [2, 1, 3, 2])
# ... or row bounds.
from_bounds = RaggedArray(flat, [0, 2, 3, 6, 7])

结构化数组

斜行数组还可以使用结构化数据类型。为此，当使用ragged_array()构造函数时，必须显式设置dtype参数。否则，NumPy会将所有内容转换为一种兼容的类型（通常是str）。

ragged = ragged_array([
    [("abc", 3), ("efg", 5)],
    [("hij", 1)],
    [("klm", 13), ("nop", 99), ("qrs", 32)],
], dtype=[("foo", str, 3), ("bar", int)])

然而，这个特性只完成了半部分，因为ragged["foo"]需要内部对跨距平坦数组的支持（Rockhopper目前还不具备）。

1D索引

以下将通过示例展示所有索引。这是一个乏味的斜行数组，可以用来玩耍。

from rockhopper import ragged_array

ragged = ragged_array([
    [1, 2, 3, 4],
    [5, 6],
    [7, 8, 9],
    [10, 11, 12, 13],
])

使用单个整数进行1D索引时，会得到作为常规数组的单行。

>>> ragged[2]
array([7, 8, 9])
>>> ragged[3]
array([10, 11, 12, 13])

但是，使用切片、整数数组或布尔掩码进行索引时，会得到另一个斜行数组。

>>> ragged[::2]
RaggedArray.from_nested([
    [1, 2, 3, 4],
    [7, 8, 9],
])
>>> ragged[[2, -1]]
RaggedArray.from_nested([
    [7, 8, 9],
    [10, 11, 12, 13],
])

即使所有行恰好具有相同的长度，这也是正确的。

2D索引

2D索引ragged[rows, columns]会得到单个单元格。也可以使用索引数组、切片和布尔掩码代替单个数字。使用上面相同的乏味的斜行数组如上所述

# Individual indices.
>>> ragged[0, 0], ragged[0, 1], ragged[0, 2]
(1, 2, 3)

# Arrays of indices.
>>> ragged[0, [0, 1, -1]]
array([1, 2, 4])
>>> ragged[0, [[1, 2], [0, 2]]]
array([[2, 3],
       [1, 3]])
>>> ragged[[0, 3, 2], [2, 3, 1]]
array([ 3, 13,  8])

# Slices as row numbers (including the null slice [:]).
>>> ragged[:, 0]
array([ 1,  5,  7, 10])
>>> ragged[2:, -1]
array([ 9, 13])

# Again, multiple column numbers may be given.
# The following gets the first and last element from each row.
>>> ragged[:, [0, -1]]
array([[ 1,  4],
       [ 5,  6],
       [ 7,  9],
       [10, 13]])

# If the second index is a slice or bool mask, the output is a ragged array.
# Even if each row is of the same length.
>>> ragged[:, :2]
RaggedArray.from_nested([
    [1, 2],
    [5, 6],
    [7, 8],
    [10, 11],
])

如果第二个索引不是一个切片，那么getitem的输出是一个副本，并且不与父斜行数组共享内存。

3D（或更高）索引

高维数组可以使用3个索引（或更多）进行切片。

使用另一个乏味的枚举示例——这次是一个3D数组

ragged = ragged_array([
    [[ 0,  1,  2], [ 3,  4,  5]],
    [[ 6,  7,  8], [ 9, 10, 11]],
    [[12, 13, 14], [15, 16, 17], [18, 19, 20]],
    [[21, 22, 23]],
])

3D数组遵循与2D数组相同的索引规则，除了每个cell实际上是另一个数组。

>>> ragged[0, 1]
array([3, 4, 5])

并使用一组索引来访问单个元素。

>>> ragged[2, 0, 1]
13

列表的列表

tolist() 方法将它们转换回嵌套列表（就像最初构建数组时使用的那些列表）。

>>> ragged.tolist()
[[1, 2, 3], [4, 5, 6], [7, 8], [9, 10], [11, 12, 13]]

列表的列表

当一个稀疏数组要么不是非常稀疏（行长度大部分相同）要么根本不稀疏（所有行长度相同）时，根据行长分割它通常很有帮助，从而得到一系列标准矩形数组，这些数组可以通过 for 循环 进行迭代。使用 to_rectangular_arrays() 方法实现。

>>> ragged.to_rectangular_arrays()
[array([[1, 2, 3],
        [4, 5, 6]]),
 array([[7, 8],
        [9, 10]]),
 array([[11, 12, 13]])]

在不太可能的情况下，如果您不关心行出现的顺序，可以将 reorder 选项设置为允许它预先对行进行升序排序，以最小化碎片化。

>>> sort_args, arrays = ragged.to_rectangular_arrays(reorder=True)
# The numpy.argsort() arguments are returned in case you want them.
>>> sort_args
array([2, 3, 0, 1, 4])
# By sorting, only 2 arrays are needed rather than 3.
>>> arrays
[array([[ 7,  8],
        [ 9, 10]]),
 array([[ 1,  2,  3],
        [ 4,  5,  6],
        [11, 12, 13]])]

二进制

目前 rockhopper 只知道一种二进制格式：高度典型但与 NumPy 严重不兼容的二进制格式

row-length | row-content | row-length | row-content

通常在 3D 图形中找到的二进制格式，其中 row-length 可能是任何无符号整数类型，无论是字节序，row-content 可能是任何数据类型或字节序，并且没有任何分隔符或元数据。

对于这种格式，RaggedArray() 提供了 loads() 方法用于读取，以及 dumps() 方法用于写入。

一些例子

# Write using:
#  - Row contents: The current data type (ragged.dtype) and endian.
#  - Row lengths: ``numpy.intc`` native endian
# Note that the output is a memoryview() which is generally interchangeable
# with bytes(). This may still be written to a file with the usual
# ``fh.write()``.
dumped = ragged.dumps()

# Read back using:
#  - Row contents: The same dtype used to write it
#  - Row lengths: ``numpy.intc`` native endian
ragged, bytes_consumed = RaggedArray.loads(dumped, ragged.dtype)

# Write then read using:
#  - Row contents: Big endian 8-byte floats
#  - Row lengths: Little endian 2-byte unsigned integers
dumped = ragged.astype(">f8").dumps(ldtype="<u2")
ragged, bytes_consumed = RaggedArray.loads(dumped, ">f8", ldtype="<u2")

默认情况下，loads() 将继续添加行，直到它遇到它正在解析的字节数组末尾。因此，bytes_consumed（从 dumped 中使用的字节数）将始终满足 bytes_consumed == len(dumped)。

某些文件格式包含一个嵌入在较大文件中的序列化稀疏数组，但未指定稀疏数组属于多少字节，以及随后的内容属于多少字节。相反，它们指定应该有多少行。要读取此类数据，请使用 rows 关键字参数。

# Read a 20 row ragged array of floats from a long ``bytes()`` object called
# **blob**. Will raise an error if it runs out of data.
ragged, bytes_consumed = ragged.loads(blob, "f8", rows=20)

# ``bytes_consumed`` indicates where the ragged array stopped.
rest_of_blob = blob[bytes_consumed:]

Pickle

如果您不需要其他程序能够读取输出，则普通的 pickle 也适用。

>>> import pickle
>>> arr = ragged_array([
...    ["cake", "biscuits"],
...    ["socks"],
...    ["orange", "lemon", "pineapple"],
... ])
>>> pickle.loads(pickle.dumps(arr))
RaggedArray.from_nested([
    ["cake", "biscuits"],
    ["socks"],
    ["orange", "lemon", "pineapple"],
])

枚举类

上述假设您想要分组的参数只是一个枚举。如果不是这种情况，并且您还没有厌倦使用我编写的软件，那么您可以使用 hirola.HashTable() 来有效地枚举要分组的参数。

例如，要按动物类别对以下动物列表进行分组

animals = np.array([
    ("cow", "mammal"),
    ("moose", "mammal"),
    ("centipede", "insect"),
    ("robin", "bird"),
    ("spider", "insect"),
    ("whale", "mammal"),
    ("woodpecker", "bird"),
], dtype=[("name", str, 15), ("class", str, 15)])

使用类似以下的方法

>>> from hirola import HashTable
>>> animal_classes = HashTable(len(animals), animals.dtype["class"])
>>> enum = animal_classes.add(animals["class"])

>>> RaggedArray.group_by(animals["name"], enum)
RaggedArray.from_nested([
    ['cow', 'moose', 'whale'],
    ['centipede', 'spider'],
    ['robin', 'woodpecker'],
])
>>> animal_classes.keys
array(['mammal', 'insect', 'bird'], dtype='<U15')