zarr-python

Zarr Python

概要

Zarr は、チャンク化と圧縮を使用して、大規模な N 次元配列を保存するための Python ライブラリです。効率的な並列 I/O、クラウドネイティブなワークフロー、NumPy、Dask、Xarray とのシームレスな統合に活用してください。

現在の上流バージョン： zarr 3.2.1（リリース日：2026-05-05）。ドキュメント：zarr.readthedocs.io。新しい配列はデフォルトで Zarr format 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 ロールまたは ワークロード ID を優先し、認証情報の値を出力しないでください。
• 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

エージェントの運用手順

1. 環境を確認します。 Python 環境とライブラリのバージョン（python -c "import pkg; print(pkg.__version__)"）を確認し、データの形状、型、欠損値を調べます。
2. 入力を特定します。 データまたはユーザーに確認して、形式、識別子、パラメーターを把握します。結果を左右する値は推測せず、質問してください。
3. まず小規模に実行します。 まずサンプルまたは単一のフォールドで実行し、実行時間とメモリを確認します。
4. 上記の指示と参考情報を使って、タスク全体を実行します。
5. 結果を検証します。 ホールドアウトデータ、固定した乱数シード、適切な指標を使い、データリークがないか確認します。不確実性（CI、シード間の標準偏差）を報告します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未解決の不確実性を明記します。

次のような場合	対応
メモリ不足、または実行が非常に遅い	サブサンプリング、チャンク化または遅延計算の使用、モデルサイズの縮小を行い、変更内容をユーザーに伝えます。
この手順に記載された関数、フラグ、エンドポイントがインストール済みバージョンにない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して対応し、ユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧	ユーザーに確認するか、実行前に仮定を明示します。

誠実性に関するルール

• 結果、パラメーター、識別子、引用、統計値を捏造してはいけません。実行または検証できないことは、明確に伝えてください。
• このセッションで計算していない指標を報告してはいけません。すべての数値について、その算出に使ったコードの経路を示してください。
• ここに記載されたバージョン固有の情報は古くなっている可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントで確認してください。
• 費用が発生するアクション、共有 GPU やクラウドのクォータを消費するアクション、個人データや患者データを扱うアクション、取り消せないアクションを行う前に、ユーザーに確認してください。

関連スキル

• dask：RAM を超える規模の pandas／NumPy ワークフロー向け分散コンピューティング。