PyTables文件格式、PyTables 文件支持的数据类型

翻译自 https://www.pytables.org/usersguide/file_format.html，http://www.pytables.org/usersguide/datatypes.html

PyTables 文件格式

PyTables 具有处理 HDF5 文件的强大功能。但是，在某些情况下，您可能希望使用这些工具创建真正原生的 PyTables 文件，同时保持与 PyTables 格式的完全兼容性。这是完全可能的，并且在本附录中介绍了您应该赋予自己生成的文件的格式，以便获得完全兼容 PyTables 的文件。

此处讨论的是PyTables 文件格式的2.0 版本 （在 PyTables 2.0 版中引入）。

PyTables 文件由 HDF5 groups（PyTables 命名方案中的组）和datasets（PyTables 命名方案中的叶子）组成。对于groups，唯一的要求是它们必须具有一些 可用的系统属性system attributes。按照惯例，PyTables 中的系统属性用大写字母书写，用户属性用小写字母书写，但这不是强制的。在datasets的情况下，除了必需的系统属性外，还需要一些条件：它们的存储布局以及其中使用的数据类型。

最后，您可以使用任何过滤器来创建 PyTables 文件，前提是过滤器是 HDF5 中的标准过滤器，例如zlib、 shuffle或szip（虽然最后一个不能在 PyTables 中使用来创建一个新文件，szip 压缩的数据集可以读取，因为它是透明地解压的 HDF5 库）。

文件的必需属性

File 对象实际上是一个特殊的 HDF5组结构，它是 对象树上其余对象的根。下一个属性对于PyTables 文件中的 HDF5根组结构是必需的：

• CLASS：对于组结构，此属性应始终设置为“GROUP”。

• PYTABLES_FORMAT_VERSION：它代表内部格式版本，目前应该设置为 '2.0' 字符串。

• TITLE：一个字符串，用户可以在其中对该组的用途进行一些描述。

• VERSION：应包含字符串“1.0”。

Group的必需属性

下一个属性对于group结构是必需的：

• CLASS：对于组结构，此属性应始终设置为“GROUP”。

• TITLE：一个字符串，用户可以在其中对该组的用途进行一些描述。

• VERSION：应包含字符串“1.0”。

组的可选属性

下一个属性对于组结构是可选的：

• FILTERS：当存在时，此属性包含过滤器属性（过滤器实例，请参阅过滤器类部分），可以由在此组下直接创建的叶或组继承。这是一个打包的 64 位整数结构，其中

  • byte 0（最低有效字节）是压缩级别（complevel）。

  • byte1是使用的压缩库（complib）：不相关时为 0，Zlib 为 1，LZO 为 2，Bzip2 为 3。

  • byte 2表示启用了哪些无参数过滤器（shuffle 和 fletcher32）：位 0 用于随机播放，而位 1 用于*Fletcher32*。

  • 其他字节保留供将来使用。

Leaves的必需属性、存储布局和支持的数据类型

这取决于Leaf的种类。每种类型的格式如下。

Table格式

必填属性

table结构的下一个属性是必需的：

• CLASS：必须设置为“TABLE”。

• TITLE：一个字符串，用户可以在其中对该数据集的用途进行一些描述。

• VERSION：应包含字符串“2.6”。

• FIELD_X_NAME：它包含不同字段的名称。X 表示字段的编号，从零开始（注意，订单很重要）。您应该添加与记录中的字段一样多的此类属性。

• FIELD_X_FILL：它包含不同字段的默认值。除了当前使用 Pickle 序列化的复杂类型之外，所有数据类型都被原生支持。X 表示字段的编号，从零开始（注意，订单很重要）。您应该添加与记录中的字段一样多的此类属性。这些字段用于永久保存默认值，它们的存在是可选的。

• NROWS：这应该包含数据集中复合数据类型条目的数量。它必须是int数据类型。

存储布局

Table中有一个dataspace用1-dimensional chunked布局。

支持的数据类型

Table 的元素（行）的数据类型必须是 H5T_COMPOUND 复合数据类型，并且这些复合组件中的每一个都必须仅使用下一个 HDF5 数据类型类构建：

• H5T_BITFIELD：该类用于表示 Bool 类型。这种类型必须使用 H5T_NATIVE_B8 数据类型构建，然后是 HDF5 H5Tset_precision 调用以将其精度设置为仅 1 位。

• H5T_INTEGER：这包括以下数据类型：

  • H5T_NATIVE_SCHAR：这表示有符号的 char C 类型，但它有效地用于表示 Int8 类型。

  • H5T_NATIVE_UCHAR：这表示unsigned char C 类型，但它有效地用于表示 UInt8 类型。

  • H5T_NATIVE_SHORT : 这代表一个短的C 类型，它有效地用来代表一个 Int16 类型。

  • H5T_NATIVE_USHORT：这表示无符号短C 类型，它有效地用于表示 UInt16 类型。

  • H5T_NATIVE_INT：这表示int C 类型，它有效地用于表示 Int32 类型。

  • H5T_NATIVE_UINT：这表示无符号 int C 类型，它有效地用于表示 UInt32 类型。

  • H5T_NATIVE_LONG：这表示long C 类型，它有效地用于表示 Int32 或 Int64，具体取决于您运行的是 32 位还是 64 位架构。

  • H5T_NATIVE_ULONG：这表示无符号长C 类型，它有效地用于表示 UInt32 或 UInt64，具体取决于您运行的是 32 位还是 64 位架构。

  • H5T_NATIVE_LLONG：这表示long long C 类型（__int64，如果您使用的是 Windows 系统）并且它有效地用于表示 Int64 类型。

  • H5T_NATIVE_ULLONG：这表示一个unsigned long long C 类型（注意：该类型在 Windows 系统上没有对应关系）并且它有效地用于表示 UInt64 类型。

• H5T_FLOAT：这包括以下数据类型：

  • H5T_NATIVE_FLOAT：这表示一个浮点C 类型，它有效地用于表示一个 Float32 类型。

  • H5T_NATIVE_DOUBLE：这表示双C 类型，它有效地用于表示 Float64 类型。

• H5T_TIME：这包括下一个数据类型：

  • H5T_UNIX_D32：这表示 POSIX time_t C 类型，它有效地用于表示“Time32”别名类型，对应于 Int32 类型。

  • H5T_UNIX_D64：这表示 POSIX struct timeval C 类型，它有效地用于表示“Time64”别名类型，它对应于 Float64 类型。

• H5T_STRING：用于描述 PyTables 中字符串的数据类型是 H5T_C_S1（即字符串C 类型），然后调用 HDF5 H5Tset_size() 函数来设置它们的长度。

• H5T_ARRAY：这允许构造同构的多维数组，以便您可以在复合记录中包含此类对象。支持作为 H5T_ARRAY 数据类型元素的类型是上述类型。目前，PyTables 不支持嵌套的 H5T_ARRAY 类型。

• H5T_COMPOUND：这允许支持复合的数据类型（这在本手册中也称为嵌套类型）。

  此支持还可用于定义复数。其格式描述如下：

  H5T_COMPOUND 类型类包含两个成员。两个成员都必须具有 H5T_FLOAT 原子数据类型类。第一个成员的名字应该是“r”，代表实部。第二个成员的名字应该是“i”，代表虚部。H5T_FLOAT 成员的精度属性必须是 32 位有效位（例如 H5T_NATIVE_FLOAT）或 64 位有效位（例如 H5T_NATIVE_DOUBLE）。它们分别代表 Complex32 和 Complex64 类型。

数组格式

必填属性

下一个属性对于数组结构是必需的：

• CLASS：必须设置为“阵列”。

• TITLE：一个字符串，用户可以在其中对该数据集的用途进行一些描述。

• VERSION：应包含字符串“2.3”。

存储布局

Array 有一个数据空间，具有N 维连续布局（如果您更喜欢分块布局，请参阅下面的 EArray）。

支持的数据类型

Array 的元素必须具有 HDF5原子数据类型或表示复数的 复合数据类型。原子数据类型目前可以是下一个 HDF5 数据类型类之一：H5T_BITFIELD、H5T_INTEGER、H5T_FLOAT 和 H5T_STRING。H5T_TIME 类也支持读取现有的 Array 对象，但不支持创建它们。请参阅表格式描述表格式有关这些类型的详细信息。

除了 HDF5 原子数据类型之外，Array 格式还支持具有 H5T_COMPOUND 数据类型类的复数。请参阅表格式描述表格式有关此特殊类型的更多信息。

您应该注意 Array 对象中不允许使用 H5T_ARRAY 类数据类型。

CArray 格式

必填属性

CArray结构的下一个属性是必需的：

• 类：必须设置为“CARRAY”。

• TITLE：一个字符串，用户可以在其中对该数据集的用途进行一些描述。

• VERSION：应包含字符串“1.0”。

存储布局

CArray 具有具有N 维分块布局的数据空间。

支持的数据类型

CArray 的元素必须具有 HDF5原子数据类型或表示复数的 复合数据类型。原子数据类型目前可以是下一个 HDF5 数据类型类之一：H5T_BITFIELD、H5T_INTEGER、H5T_FLOAT 和 H5T_STRING。H5T_TIME 类也支持读取现有的 CArray 对象，但不支持创建它们。请参阅表格式描述表格式有关这些类型的详细信息。

除了 HDF5 原子数据类型之外，CArray 格式还支持具有 H5T_COMPOUND 数据类型类的复数。请参阅表格式描述表格式有关此特殊类型的更多信息。

您应该注意 Array 对象中还不允许使用 H5T_ARRAY 类数据类型。

EArray 格式

必填属性

下一个属性对于earray结构是必需的：

• 类：必须设置为“EARRAY”。

• EXTDIM : ( Integer ) 必须设置为可扩展维度。目前仅支持一种可扩展维度。

• TITLE：一个字符串，用户可以在其中对该数据集的用途进行一些描述。

• VERSION：应包含字符串“1.3”。

存储布局

EArray 有一个具有N 维分块布局的数据空间。

支持的数据类型

允许 EArray 的元素具有与 Array 格式中的元素相同的数据类型。它们可以是HDF5的一个原子数据类型 的类：H5T_BITFIELD，H5T_INTEGER，H5T_FLOAT，H5T_TIME或H5T_STRING，请参阅表格式描述表格式有关这些类型的详细信息。它们也可以是代表复数a H5T_COMPOUND数据类型，请参阅表格式说明表格式。

您应该注意 EArray 对象中不允许使用 H5T_ARRAY 类数据类型。

VLArray 格式

必填属性

下一个属性对于vlarray结构是必需的：

• 类：必须设置为“VLARRAY”。

• PSEUDOATOM：用于指定VLArray的伪原子类型（参见 VLArray 格式）。它可以采用值“vlstring”、“vlunicode”或“object”。如果您的原子不是伪原子，则不应指定它。

• TITLE：一个字符串，用户可以在其中对该数据集的用途进行一些描述。

• VERSION：应包含字符串“1.3”。

存储布局

一个VLArray具有数据空间用1维分块布局。

支持的数据类型

VLArray对象的元素（行）的数据类型必须是H5T_VLEN 变长（或简称VL）数据类型，为VL数据类型指定的基本数据类型可以是表格式中列出的任何原子HDF5数据类型说明表格格式。这包括以下课程：

• H5T_BITFIELD

• H5T_INTEGER

• H5T_FLOAT

• H5T_TIME

• H5T_STRING

• H5T_ARRAY

它们也可以是表示复数的 H5T_COMPOUND 数据类型，详细说明请参见表格格式中的表格格式说明。

您应该注意，这不包括其他 VL 数据类型，或不适合复数描述的复合数据类型。还要注意，对于对象和 vlstring 伪原子，VL 数据类型的基础始终是 H5T_NATIVE_UCHAR（对于 vlunicode，H5T_NATIVE_UINT）。这意味着必须使用数据集中的完整行条目才能完全序列化对象或可变长度字符串。

叶子的可选属性

叶子的下一个属性是可选的：

• FLAVOR：这旨在提供有关保留在 Leaf 中的对象类型的信息，即当读取数据集时，它将被转换为指示的风味。它可以采用下一个字符串值：

  • “numpy”：读取的数据（结构数组、数组、记录、标量）将作为 NumPy 对象返回。

  • “python”：读取的数据将作为 Python 列表、元组或标量返回。

PyTables 文件支持的数据类型

PyTables支持NumPy所支持的所有完整的数据类型。表字段的数据类型可以通过Col类或其子类（参见 The Col class and its descendants）的实例来进行设置，而数组元素的数据类型可以通过使用Atom类和它的子类（参见The Atom class and its descendants）来实现。

PyTables使用普通的字符串去存储它的类别，大多数都辐合NumPy的标量类型，一个PyTables的类型由两部分组成，一个类别kind和用位数表示的精度precision。对于只有一种精度（如bool类）或无固定长度（如字符串）的情况下，precision可以被忽略。

PyTables支持八类数据类型：

• bool: Boolean (true/false) types. Supported precisions: 8 (default) bits.

• int: Signed integer types. Supported precisions: 8, 16, 32 (default) and 64 bits.

• uint: Unsigned integer types. Supported precisions: 8, 16, 32 (default) and 64 bits.

• float: Floating point types. Supported precisions: 16, 32, 64 (default) bits and extended precision floating point (see note on floating point types).

• complex: Complex number types. Supported precisions: 64 (32+32), 128 (64+64, default) bits and extended precision complex (see note on floating point types).

• string: Raw string types. Supported precisions: 8-bit positive multiples.

• time: Data/time types. Supported precisions: 32 and 64 (default) bits.

• enum: Enumerated types. Precision depends on base type.

注意 

半精度浮点数据类型 (float16) 和扩展精度数据类型 (fload96、float128、complex192、complex256) 仅当 numpy 在主机平台上支持时才可用。
此外，为了使用半精度浮点类型 (float16)，需要 numpy >= 1.6.0。

time和enum类型有一些特殊，因为他们是HDF5类型，且没有直接对应的Python类型，尽管这些类型的元素或多或少有等效的NumPy数据类型。

有两种时间类型：4位有符号整型（time32）和8位双精度浮点数（time64）。他们均反映了自Unix纪元（即1970年1月1日 00:00:00 UTC）以来的秒数。它们分别作为 NumPy 的 int32 和 float64 存储在内存中，并使用 H5T_TIME 类存储在 HDF5 文件中。在HDF5文件中使用H5T_TIME类。整数时间就这样存储在磁盘上，而浮点时间被分成两个有符号整型数值代表秒和微秒（注意：较小的小数会丢失！）。

PyTables也支持HDF5_H5T_ENUM 迭代（唯一名称和唯一数值对的受限集合）。枚举值的 NumPy 表示（枚举，请参阅The Enum class）取决于用于在 HDF5 文件中存储枚举的具体基类。目前，枚举中仅支持标量整数值（有符号和无符号）。当 HDF5 支持枚举值的其他类型时，可以取消此限制。

此处快是完整的PyTables支持数据类型集：

Data types supported for array elements and tables columns in PyTables.

Type Code	Description	C Type	Size (in bytes)	Python Counterpart
bool	boolean	unsigned char	1	bool
int8	8-bit integer	signed char	1	int
uint8	8-bit unsigned integer	unsigned char	1	int
int16	16-bit integer	short	2	int
uint16	16-bit unsigned integer	unsigned short	2	int
int32	integer	int	4	int
uint32	unsigned integer	unsigned int	4	long
int64	64-bit integer	long long	8	long
uint64	unsigned 64-bit integer	unsigned long long	8	long
float16 1	half-precision float		2
float32	single-precision float	float	4	float
float64	double-precision float	double	8	float
float96 1 2	extended precision float		12
float128 1 2	extended precision float		16
complex64	single-precision complex	struct {float r, i;}	8	complex
complex128	double-precision complex	struct {double r, i;}	16	complex
complex192 1	extended precision complex		24
complex256 1	extended precision complex		32
string	arbitrary length string	char[]		str
time32	integer time	POSIX’s time_t	4	int
time64	floating point time	POSIX’s struct timeval	8	float
enum	enumerated value	enum

Footnotes

1(1,2,3,4,5)

see the above note on floating point types.

2(1,2)

currently in numpy. “float96” and “float128” are equivalent of “longdouble” i.e. 80 bit extended precision floating point.