zarr-python

Zarr Python

概述

Zarr 是一个 Python 库，用于通过分块和压缩存储大型 N 维数组。使用此技能可实现高效的并行 I/O、云原生工作流，并与 NumPy、Dask 和 Xarray 无缝集成。

当前上游版本： zarr 3.2.1（发布于 2026-05-05）。文档：zarr.readthedocs.io。新建数组默认采用 Zarr 格式 3；如需兼容旧版本，请设置 zarr_format=2。Zarr 3.2 新增了直线型分块，并继续完善 v3 编解码器管线。此技能是由 Kalaris Labs 维护的社区指南，并非 zarr-developers 的官方软件包。

快速入门

安装

uv pip install "zarr==3.2.1"

当前稳定版 Zarr-Python 需要 Python 3.12+ 和 NumPy 2.0+。对于远程存储（S3、GCS、HTTP），请在项目锁文件中固定可选额外依赖和后端：

uv pip install "zarr[remote]==3.2.1" "s3fs==2026.4.0" "gcsfs==2026.5.0"

仅当项目已提交锁文件并包含兼容性测试时，才使用 zarr>=3,<4 这样的版本范围。对于 Zarr-Python 2 / Python 3.10–3.11 工作流，请从 support-v2 发布说明中选择确切的 zarr==2.x.y 补丁版本，并提交生成的锁文件。

创建基本数组

import zarr
import numpy as np

# Create a 2D array with chunking and compression
z = zarr.create_array(
    store="data/my_array.zarr",
    shape=(10000, 10000),
    chunks=(1000, 1000),
    dtype="f4"
)

# Write data using NumPy-style indexing
z[:, :] = np.random.random((10000, 10000))

# Read data
data = z[0:100, 0:100]  # Returns NumPy array

核心操作

创建数组

Zarr 提供了多个便捷函数来创建数组：

# Create empty array
z = zarr.zeros(shape=(10000, 10000), chunks=(1000, 1000), dtype='f4',
               store='data.zarr')

# Create filled arrays
z = zarr.ones((5000, 5000), chunks=(500, 500))
z = zarr.full((1000, 1000), fill_value=42, chunks=(100, 100))

# Create from existing data
data = np.arange(10000).reshape(100, 100)
z = zarr.array(data, chunks=(10, 10), store='data.zarr')

# Create like another array
z2 = zarr.zeros_like(z)  # Matches shape, chunks, dtype of z

打开现有数组

# Open array (read/write mode by default)
z = zarr.open_array('data.zarr', mode='r+')

# Read-only mode
z = zarr.open_array('data.zarr', mode='r')

# The open() function auto-detects arrays vs groups
z = zarr.open('data.zarr')  # Returns Array or Group

读取和写入数据

Zarr 数组支持类似 NumPy 的索引：

# Write entire array
z[:] = 42

# Write slices
z[0, :] = np.arange(100)
z[10:20, 50:60] = np.random.random((10, 10))

# Read data (returns NumPy array)
data = z[0:100, 0:100]
row = z[5, :]

# Advanced indexing
z.vindex[[0, 5, 10], [2, 8, 15]]  # Coordinate indexing
z.oindex[0:10, [5, 10, 15]]       # Orthogonal indexing
z.blocks[0, 0]                     # Block/chunk indexing

调整大小和追加

# Resize array (v3: pass shape as a tuple)
z.resize((15000, 15000))

# Append data along an axis
z.append(np.random.random((1000, 10000)), axis=0)  # Adds rows

组和层级结构

组可按层级组织多个数组，类似于目录或 HDF5 组。

创建和使用组

# Create root group
root = zarr.group(store='data/hierarchy.zarr')

# Create sub-groups
temperature = root.create_group('temperature')
precipitation = root.create_group('precipitation')

# Create arrays within groups
temp_array = temperature.create_array(
    name='t2m',
    shape=(365, 720, 1440),
    chunks=(1, 720, 1440),
    dtype='f4'
)

precip_array = precipitation.create_array(
    name='prcp',
    shape=(365, 720, 1440),
    chunks=(1, 720, 1440),
    dtype='f4'
)

# Access using paths
array = root['temperature/t2m']

# Visualize hierarchy
print(root.tree())
# Output:
# /
#  ├── temperature
#  │   └── t2m (365, 720, 1440) f4
#  └── precipitation
#      └── prcp (365, 720, 1440) f4

组 API（v3）

请使用 create_array / require_array（类似 h5py 的 create_dataset / require_dataset 已在 v3 中移除）：

root = zarr.group('data.zarr')
arr = root.create_array('my_data', shape=(1000, 1000), chunks=(100, 100), dtype='f4')

grp = root.require_group('subgroup')
arr2 = grp.require_array('array', shape=(500, 500), chunks=(50, 50), dtype='i4')

属性和元数据

使用属性为数组和组附加自定义元数据：

# Add attributes to array
z = zarr.zeros((1000, 1000), chunks=(100, 100))
z.attrs['description'] = 'Temperature data in Kelvin'
z.attrs['units'] = 'K'
z.attrs['created'] = '2024-01-15'
z.attrs['processing_version'] = 2.1

# Attributes are stored as JSON
print(z.attrs['units'])  # Output: K

# Add attributes to groups
root = zarr.group('data.zarr')
root.attrs['project'] = 'Climate Analysis'
root.attrs['institution'] = 'Research Institute'

# Attributes persist with the array/group
z2 = zarr.open('data.zarr')
print(z2.attrs['description'])

重要：属性必须可序列化为 JSON（字符串、数字、列表、字典、布尔值、null）。

分块、压缩、存储和性能

• references/chunking_and_compression.md： 根据访问模式确定分块大小（目标约为 1 MB；云端为 5–100 MB）、分片以及 编解码器选择。
• references/storage_backends.md：本地、内存、ZIP 和 fsspec 远程存储（S3、GCS），并提供凭据指导——优先使用 IAM 角色或 工作负载身份，切勿打印凭据值。
• references/integration.md：与 NumPy、Dask 和 Xarray 的集成、线程安全以及合并元数据。
• references/performance_and_patterns.md： 优化、可追加的时间序列和大型矩阵模式、格式转换以及 故障排查。
• references/api_reference.md 和 references/v3_migration.md：完整 API 和 v2 到 v3 的 迁移说明。

其他资源

随附参考资料

文件	内容
references/api_reference.md	函数签名、存储、编解码器、索引
references/v3_migration.md	Zarr-Python 2→3 的破坏性变更和开发中功能

上游官方资源

• 文档：https://zarr.readthedocs.io/en/stable/
• 3.0 迁移指南：https://zarr.readthedocs.io/en/stable/user-guide/v3_migration/
• 存储后端：https://zarr.readthedocs.io/en/stable/user-guide/storage/
• Zarr 规范：https://zarr-specs.readthedocs.io/
• GitHub：https://github.com/zarr-developers/zarr-python
• 开发者聊天：https://ossci.zulipchat.com/#narrow/channel/423692-Zarr-Python

相关库： Xarray、Dask、NumCodecs

Agent 操作流程

1. 检查环境。 确认 Python 环境和库版本（python -c "import pkg; print(pkg.__version__)"），并检查数据的形状、类型和缺失值。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会改变结果的值都应询问，不要猜测。
3. 先运行小规模版本。 先在样本或单个折上运行，并检查运行时间和内存。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 使用留出数据、固定随机种子和适当的指标；检查是否存在数据泄漏；报告不确定性（置信区间、不同随机种子下的标准差）。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及哪些方面仍不确定。

如果发生这种情况	请这样做
内存不足或执行速度很慢	进行子采样，使用分块或惰性计算，或缩小模型规模，并告知用户所做的更改。
这些说明中的函数、标志或端点在已安装版本中不存在	查看已安装版本自带的文档（help()、--help、官方文档），调整用法，并告知用户。切勿虚构 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明假设。

诚信规则

• 切勿伪造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请直言说明。
• 切勿报告本次会话中未计算的指标；展示生成每个数值的代码路径。
• 此处与版本相关的细节可能已过时：请根据已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，请先征得同意。

相关技能

• dask：用于处理规模超过内存容量的 pandas/NumPy 工作流的分布式计算。