h5netcdf 1.3.0

新API

新API支持直接对变量和组的分层访问。其设计是h5py对netCDF数据模型的适配。例如

import h5netcdf
import numpy as np

with h5netcdf.File('mydata.nc', 'w') as f:
    # set dimensions with a dictionary
    f.dimensions = {'x': 5}
    # and update them with a dict-like interface
    # f.dimensions['x'] = 5
    # f.dimensions.update({'x': 5})

    v = f.create_variable('hello', ('x',), float)
    v[:] = np.ones(5)

    # you don't need to create groups first
    # you also don't need to create dimensions first if you supply data
    # with the new variable
    v = f.create_variable('/grouped/data', ('y',), data=np.arange(10))

    # access and modify attributes with a dict-like interface
    v.attrs['foo'] = 'bar'

    # you can access variables and groups directly using a hierarchical
    # keys like h5py
    print(f['/grouped/data'])

    # add an unlimited dimension
    f.dimensions['z'] = None
    # explicitly resize a dimension and all variables using it
    f.resize_dimension('z', 3)

注意

• 数组索引的自动调整无限维度的功能不可用。

• 需要手动使用Group.resize_dimension(dimension, size)调整维度的尺寸。

• 数组返回时填充了fillvalue（来自底层hdf5数据集），直到变量的维度当前大小。这种行为与netCDF4-python的Dataset.set_auto_mask(False)等效。

旧API

旧API是为了与netCDF4-python兼容而设计的。要使用它，请导入h5netcdf.legacyapi。

import h5netcdf.legacyapi as netCDF4
# everything here would also work with this instead:
# import netCDF4
import numpy as np

with netCDF4.Dataset('mydata.nc', 'w') as ds:
    ds.createDimension('x', 5)
    v = ds.createVariable('hello', float, ('x',))
    v[:] = np.ones(5)

    g = ds.createGroup('grouped')
    g.createDimension('y', 10)
    g.createVariable('data', 'i8', ('y',))
    v = g['data']
    v[:] = np.arange(10)
    v.foo = 'bar'
    print(ds.groups['grouped'].variables['data'])

旧API旨在便于netCDF4-python用户尝试，但它并不完全匹配。以下是我们不包含的功能的列表（不完整）：

• 不直接必要的工具函数，如chartostring、num2date等。

• h5netcdf变量不支持自动掩码或缩放（例如，与_FillValue属性匹配的值）。我们更愿意将此功能留给客户端库（例如，xarray），这些库可以实现其精确的缩放行为。不过，数组返回时填充了fillvalue（来自底层hdf5数据集），直到变量的维度当前大小。这种行为与netCDF4-python的Dataset.set_auto_mask(False)等效。

无效的netCDF文件

h5py实现了一些不会导致有效netCDF文件的特征

• 数据类型

  • 布尔值

  • 复数值

  • 非字符串的可变长度类型

  • 枚举类型

  • 引用类型

• 任意过滤器

  • 比例-偏移量过滤器

默认情况下[1]，h5netcdf不允许使用这些功能来写入文件，因为具有这些功能的文件不能被其他netCDF工具读取。

然而，这些仍然是有效的HDF5文件。如果您不关心netCDF兼容性，可以在创建文件时设置invalid_netcdf=True来使用这些功能。

# avoid the .nc extension for non-netcdf files
f = h5netcdf.File('mydata.h5', invalid_netcdf=True)
...

# works with the legacy API, too, though compression options are not exposed
ds = h5netcdf.legacyapi.Dataset('mydata.h5', invalid_netcdf=True)
...

在这种情况下，_NCProperties属性将不会保存到文件中或从现有文件中删除。如果文件具有.nc-扩展名，将发出警告。

脚注

解码可变长度字符串

h5py 3.0 引入了处理可变长度字符串的新行为。[新行为](https://docs.h5py.org/en/stable/strings.html)。不再自动使用 UTF-8 将其解码为 str 类型的 NumPy 数组，而是需要作为 bytes 类型的数组提供。

遗留的 API 保留了 h5py（与 netCDF4 匹配）的旧行为，并自动解码字符串。

新的 API 与 h5py 的行为相匹配。在 h5netcdf.File 构造函数中显式设置 decode_vlen_strings=True 以启用自动解码。

缺失维度缩放的数据集

默认情况下，如果访问没有与其中一个轴关联维度缩放的变量，h5netcdf 会引发 ValueError。在打开文件时设置 phony_dims='sort' 可以让 h5netcdf 根据 [netCDF](https://docs.unidata.ucar.edu/netcdf-c/current/interoperability_hdf5.html) 行为创建假维度。

# mimic netCDF-behaviour for non-netcdf files
f = h5netcdf.File('mydata.h5', mode='r', phony_dims='sort')
...

注意，这将遍历整个组层次结构一次。如果依赖组的惰性访问，则这会影响性能。您可以改为设置 phony_dims='access' 以在组访问时延迟创建假维度。创建的假维度命名将与 [netCDF](https://docs.unidata.ucar.edu/netcdf-c/current/interoperability_hdf5.html) 行为不同。

f = h5netcdf.File('mydata.h5', mode='r', phony_dims='access')
...

脚注

跟踪顺序

从 h5netcdf 1.1.0 版本开始，如果检测到 h5py 3.7.0 或更高版本，则将 track_order 参数设置为 True，从而启用新创建的 netCDF4 文件的对顺序跟踪。[顺序跟踪](https://docs.unidata.ucar.edu/netcdf-c/current/file_format_specifications.html#creation_order)。这有助于确保使用 h5netcdf 库创建的文件可以被其他软件堆栈中使用的 netCDF4-c 和 netCDF4-python 实现修改。由于此更改对大多数用户应该是透明的，因此没有进行弃用。

由于 track_order 在创建时设置，因此使用 track_order=False（除 0.13.0 之外的所有 1.0.2 及更早版本）创建的数据集将继续以禁用顺序跟踪的方式打开。

以下描述了 h5netcdf 在几个关键版本中对顺序跟踪的行为：

• 0.12.0 及更早版本，track_order 参数缺失，因此顺序跟踪隐式设置为 False。

• 0.13.0 通过默认将参数 track_order 设置为 True 启用顺序跟踪，而没有进行弃用。

• 0.13.1 至 1.0.2 版本由于 h5netcdf 核心依赖项 h5py 的一个错误而将 track_order 设置为 False，该错误在 h5py 3.7.0 中通过 h5netcdf 团队的帮助得到解决。[上游错误](https://github.com/h5netcdf/h5netcdf/issues/136)。

• 在 1.1.0 版本中，如果检测到 h5py 3.7.0 或更高版本，则默认将 track_order 参数设置为 True。