SuperAPI AI 工具集

zarr-python

编程与开发

查看项目

更新于 10-15 23:43

技能介绍

用途:面向分块科学数组的存储与查询,支持层级存储、编解码器、分片、部分读取、云对象存储,以及与 NumPy、Dask、Xarray 的互操作。本指南针对 Zarr-Python 3.4.0(2026-09-15 发布,Python 3.12+)。包版本与磁盘格式相互独立:该版本可读写格式 2 和 3,新建数组默认使用格式 3;依赖 zarr<3 的下游包应放在独立环境中。

安装:uv pip install "zarr==3.4.0" "numpy==2.5.3";可选远程后端与迁移 CLI:uv pip install "zarr[remote,cli]==3.4.0" "fsspec==2026.9.0" "s3fs==2026.9.0" "gcsfs==2026.8.1"。应提交项目解析后的 lockfile。此处验证过的可选集成版本包括 Dask 2026.8.0、Xarray 2026.9.0、h5py 3.16.0、NumCodecs 0.17.0、obstore 0.11.1。远程示例仅为说明,需真实已授权存储,不构成云权限、生产吞吐或下游读取器兼容性保证。

主要能力与用法:创建数组可用 create_array(data= 与 shape=+dtype= 不可混用)、zeros、ones、full、zeros_like。索引支持普通切片、vindex/get_coordinate_selection 的坐标配对索引、oindex 正交索引以及 blocks;不支持负步长切片。写入应分块进行,每个存储分块(分片时为每个分片)只分配一个写入者,元数据、追加和 resize 操作需串行化。追加与 resize:append 须匹配所有非追加维度,resize 接收元组;缩小会移除新形状之外的块,但保留边界块中的值在再次扩展时可能重现,resize 不是安全擦除或缺失值策略。组与属性:用 open_group/create_group/require_group 与 create_array/require_array(create_dataset/require_dataset 已移除),属性须为 JSON 兼容且属于所在节点,可通过 tree() 查看逻辑层级。

推荐流程:先检查 shape、dtype、轴名称、坐标、单位、缺失值约定、格式、编解码器可用性和目标读取器,保留样本 ID 与轴顺序;按实际选择与内存预算设置 chunk,分片维度为 chunk 维度的整数倍并做基准测试;用 overwrite=False 或 mode="w-" 新建,mode="r" 只读检查("a" 可创建缺失存储,"w" 会销毁内容);写入后以只读重新打开并比对数值、dtype、shape、坐标、单位、掩码和元数据——未写入或缺失的块通常读作 fill_value,成功打开并不证明数据完整;组层级完成后可选合并元数据(格式 3 合并为实验性,元数据变更后需刷新并验证消费者),验证完成后才发布。

限制:新建格式 3 数值数组默认是 bytes 序列化器加 ZstdCodec,而非 Blosc,若要可复现应显式设置编解码器。默认 CPU 配置下读取返回 NumPy 数据;np.asarray(z)、np.sum(z)、z[:] 或对完整数组做 Dask .compute() 可能物化整个逻辑数据集,应使用有界选择或惰性归约。名称与单位仅为声明,不做单位换算或科学校验;require_array 只检查兼容性,不重新分块。远程存储权限、生产吞吐及下游读取器兼容性暂未提供保证。