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"）で渡してください。BloscShuffle／BloscCname 列挙型は 3.1 以降非推奨です。
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 スイートの一部です。