alterlab-zarr

Zarr Python

概述

Zarr 是一个用于通过分块和压缩存储大型 N 维数组的 Python 库。对于高效并行 I/O、云原生工作流，以及与 NumPy、Dask 和 Xarray 的无缝集成，请使用此技能。本指南面向 zarr-python 3.x（当前版本为 3.4.0），该版本默认写入 Zarr v3 格式。

何时使用此技能

当用户想要以下操作时，请使用此技能：

• 创建、打开或写入经过分块和压缩的 N 维数组（zarr.create_array、组、属性）。
• 根据访问模式选择块形状、分片和编解码器（Zstandard、Blosc、Gzip）。
• 将数组存储到 S3/GCS 或其他对象存储中，并远程读取切片（合并元数据、分片）。
• 将 HDF5/NumPy/NetCDF 数据转换为 Zarr，或将 Zarr v2 时代的代码（compressor=、synchronizer=、create_dataset）迁移到 v3。

不适用的情形

情形	改用
对已存储在 Zarr 中的数组进行并行或分布式计算（调度、外存计算）	alterlab-dask
探索未知数据文件并编写结构/质量报告	alterlab-eda
存储为 .h5ad 或 AnnData-on-zarr 的单细胞 AnnData 对象	alterlab-anndata
对大型 CSV/Parquet 文件进行表格分析	alterlab-polars

快速开始

安装

uv pip install zarr

Zarr v3（zarr>=3）；zarr 3.2+ 需要 Python 3.12+ 和 NumPy 2（3.1.x 系列仍支持 Python 3.11）。如需云存储支持，请安装相应的 fsspec 后端：

uv pip install s3fs   # For S3
uv pip install gcsfs  # For Google Cloud Storage

创建基本数组

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

核心工作流

1. 创建或打开 数组/组，并根据环境选择合适的存储（本地、内存、ZIP、S3/GCS）。
2. 选择分块方式，使其符合访问模式（目标块大小为 1-10 MB；按行优先 → 块覆盖多列，反之亦然）。这是影响性能最大的单一因素。
3. 根据工作负载通过 compressors= 选择压缩方式 — Zstandard（默认）、Blosc+LZ4（速度快）、Gzip（压缩率最高）；使用 compressors=None 禁用压缩。Blosc 选项请使用字符串（shuffle="shuffle"、cname="zstd"）；自 3.1 起，BloscShuffle/BloscCname 枚举已弃用。
4. 使用 NumPy 风格索引读写数据；随着数据增长调整大小/追加内容。
5. 使用 Dask（惰性、外存、并行）扩展规模，或使用 Xarray 为气候/地理空间数据添加标签。
6. 对于云端和多数组存储，请合并元数据，并考虑分片以减少对象/文件数量。合并元数据是 zarr-python 的一种约定，尚未纳入 v3 规范（zarr 会发出警告），因此其他读取器可能会忽略它。

# Minimal end-to-end
import zarr, numpy as np
z = zarr.create_array(store="data/my_array.zarr", shape=(10000, 10000),
                      chunks=(1000, 1000), dtype="f4")
z[:, :] = np.random.random((10000, 10000))
sub = z[0:100, 0:100]            # returns a NumPy array

路由 — 查看位置

你需要……	前往
数组创建/打开、读写、调整大小/追加、属性、组与层级结构、合并元数据	references/array_operations.md
块大小指南、使块与访问模式对齐、分片、压缩编解码器与技巧	references/chunking_compression.md
本地/内存/ZIP/S3/GCS 存储和云端最佳实践	references/storage_backends.md
NumPy/Dask/Xarray 集成、线程安全和进程安全的并行写入	references/integration.md
性能检查清单、性能分析、常见模式（时间序列、大型矩阵、云原生、格式转换）、故障排查	references/patterns_performance.md
完整 API	references/api_reference.md

其他资源

• 官方文档：https://zarr.readthedocs.io/
• Zarr 规范：https://zarr-specs.readthedocs.io/
• GitHub 仓库：https://github.com/zarr-developers/zarr-python
• 相关项目：Xarray（带标签的数组）、Dask（并行计算）、NumCodecs（压缩编解码器）

属于 AlterLab Academic Skills 套件。