bitemporal-h5

基于HDF5 (h5py) 的通用双时间戳模型

模型

双时间戳的基本模型是一个HDF5数据集，该数据集可以沿着一个维度扩展，具有命名列和每列不同的dtypes。在内存中，这将被表示为一个numpy结构化数组。在此处，我们将此结构称为《表》。

请注意，HDF5在高级接口（hdf5-hl）中具有自己的Table数据结构。我们不会在这里使用高级表，原因有两个。首先，`h5py` 不支持HDF5的高级结构。其次，我们计划最终用去重缓存替换值列。依赖于低级HDF5结构使我们能够在未来获得这种灵活性。

表中现有的列如下

• transaction_id (uint64)：这是一个单调整数，表示导致此行写入的确切写操作。可能同时写入多行，因此此值在行之间不是唯一的，但假定具有给定事务ID的所有行在表中是连续的。此值从0开始索引。当前最大的事务ID应写入表属性作为max_transaction_id（也是uint64）。写操作应将max_transaction_id增加1。
• transaction_time (datetime64)：这是一个时间戳（自纪元以来的秒数）。关于时区的时间元数据应存储为数据集的字符串属性，即transaction_time_zone。这表示写入操作记录数据的时间。所有具有相同transaction_id的行在这里应该具有相同的值。
• valid_time (datetime64)：这是一个时间戳（自纪元以来的秒数）。关于时区的时间元数据应存储为数据集的字符串属性，即valid_time_zone。这是时间序列的主轴。它表示存储在value列中的数据。
• value ((I,J,K,...)<scalar-type>|)：该列表示时间序列的实际值。这可能是一个任何有效dtype的N维数组。可能只需要将我们限制为浮点数和整数，但模型应该足够通用，可以接受任何标量dtype。此外，典型用法将是此列为一个标量浮点值。

因此，一个示例numpy dtype具有浮点值和形状(1, 2, 3)的例子是

np.dtype([
    ('transaction_id', '<uint64'),
    ('transaction_time', '<M8'),
    ('valid_time', '<M8'),
    ('value', '<f8', (1, 2, 3))
])

快速入门API

写入bitemporal HDF5存储的接口如下

import bth5

with bth5.open("/path/to/file.h5", "/path/to/group", "a+") as ds:
    # all writes are staged into a single transaction and then
    # written when the context exits. Transaction times and IDs
    # are automatically applied. The first write call determines
    # the dtype & shape of value, if the data set does not already
    # exist.
    ds.write(t1, p1)
    ds.write(valid_time=t2, value=p2)
    ds.write(valid_time=[t3, t4, t5], value=[p3, p4, p5])
    ds.write((t6, p6))
    ds.write([(t7, p7), (t8, p8)])

从数据集读取应遵循正常的numpy索引

# opened in read-only mode
>>> ds = bth5.open("/path/to/file.h5", "/path/to/group")
>>> in_mem = ds[:]
>>> in_mem.dtype
np.dtype([
    ('valid_time', '<M8'),
    ('value', '<f8', (1, 2, 3))
])

这应该返回在缩减数据集中存在的最新有效时间和值。此外，还有一个逃生阀可以访问磁盘上表示的实际数据集。这是raw属性，它返回对h5py数据集的引用。

>>> ds = bth5.open("/path/to/file.h5", "/path/to/group")
>>> ds.raw