anndata

AnnData

概要

AnnData は、注釈付きデータ行列を扱うための Python パッケージです。実験測定値（X）と、観測データのメタデータ（obs）、変数のメタデータ（var）、多次元アノテーション（obsm、varm、obsp、varp、uns）をまとめて保存します。当初は Scanpy を通じた単一細胞ゲノミクス向けに設計されましたが、現在では効率的な保存、操作、分析が必要なあらゆる注釈付きデータに対応する汎用フレームワークとして利用されています。

このスキルを使用する場面

次のような場合にこのスキルを使用します。

• AnnData オブジェクトを作成、読み込み、または書き込む場合
• h5ad、zarr、その他のゲノミクスデータ形式を扱う場合
• 単一細胞 RNA-seq 解析を行う場合
• スパース行列または backed モードで大規模データセットを管理する場合
• 複数のデータセットまたは実験バッチを結合する場合
• 注釈付きデータのサブセット化、フィルタリング、または変換を行う場合
• scanpy、scvi-tools、その他の scverse エコシステムツールと連携する場合

インストール

Python 3.11 以降が必要です。現在の安定版リリース：0.12.16（2026-05-18 リリース）。

uv pip install "anndata==0.12.16"

# Lazy I/O and dask-backed operations
uv pip install "anndata[dask,lazy]==0.12.16"

# Development / docs (contributors)
uv pip install "anndata[dev,test,doc]==0.12.16"

最新の互換性のあるリリースを意図的に追跡する場合に限り、バージョンを固定しないインストールを使用してください。

現在の API に関する注意事項：

• ネイティブ形式以外の read_* および write_* ヘルパーには、anndata.io を使用してください。トップレベルの anndata.read_h5ad および anndata.read_zarr は引き続きサポートされています。
• 非推奨の API（ad.read、AnnData.concatenate()、AnnData.*_keys()、anndata.__version__）は避けてください。代わりに、ad.read_h5ad、ad.concat、マッピングの .keys()、および importlib.metadata.version("anndata") を使用してください。
• anndata.experimental API は便利ですが、安定していないものとして扱ってください。現在の制約を許容できる場合に限り、大規模データのワークフローで優先的に使用してください。

クイックスタート

AnnData オブジェクトの作成

import anndata as ad
import numpy as np
import pandas as pd

# Minimal creation
X = np.random.rand(100, 2000)  # 100 cells × 2000 genes
adata = ad.AnnData(X)

# With metadata
obs = pd.DataFrame({
    'cell_type': ['T cell', 'B cell'] * 50,
    'sample': ['A', 'B'] * 50
}, index=[f'cell_{i}' for i in range(100)])

var = pd.DataFrame({
    'gene_name': [f'Gene_{i}' for i in range(2000)]
}, index=[f'ENSG{i:05d}' for i in range(2000)])

adata = ad.AnnData(X=X, obs=obs, var=var)

データの読み込み

# Native formats (read_h5ad/read_zarr remain at top-level)
adata = ad.read_h5ad('data.h5ad')
adata = ad.read_h5ad('large_data.h5ad', backed='r')  # lazy load for large files
adata = ad.read_zarr('data.zarr')

# Other formats: prefer anndata.io (top-level imports are deprecated)
from anndata.io import read_csv, read_loom, read_mtx

adata = read_csv('data.csv')
adata = read_loom('data.loom')

# 10X Genomics: use scanpy (not anndata) — see scanpy skill
import scanpy as sc
adata = sc.read_10x_h5('filtered_feature_bc_matrix.h5')
adata = sc.read_10x_mtx('filtered_feature_bc_matrix/')

データの書き込み

# Write h5ad file
adata.write_h5ad('output.h5ad')

# Write with compression
adata.write_h5ad('output.h5ad', compression='gzip')

# Write other formats
adata.write_zarr('output.zarr')
adata.write_csvs('output_dir/')

基本操作

# Subset by conditions
t_cells = adata[adata.obs['cell_type'] == 'T cell']

# Subset by indices
subset = adata[0:50, 0:100]

# Add metadata
adata.obs['quality_score'] = np.random.rand(adata.n_obs)
adata.var['highly_variable'] = np.random.rand(adata.n_vars) > 0.8

# Access dimensions
print(f"{adata.n_obs} observations × {adata.n_vars} variables")

主な機能

1. データ構造

X、obs、var、layers、obsm、varm、obsp、varp、uns、raw の各コンポーネントを含む AnnData オブジェクトの構造を理解します。

参照：詳しい情報は references/data_structure.md をご覧ください。

• コアコンポーネント（X、obs、var、layers、obsm、varm、obsp、varp、uns、raw）
• さまざまなソースからの AnnData オブジェクトの作成
• データコンポーネントへのアクセスと操作
• メモリ効率の高い実践方法

2. 入出力操作

圧縮、backed モード、クラウドストレージに対応した、さまざまな形式でのデータの読み込みと書き込みを行います。

参照：詳しくは references/io_operations.md をご覧ください。

• ネイティブ形式（h5ad、zarr）
• 代替形式（CSV、MTX、Loom、10X、Excel）
• 大規模データセット向けの backed モード
• リモートデータへのアクセス
• 形式変換
• パフォーマンスの最適化

一般的なコマンド：

from anndata.io import read_mtx

# Read/write h5ad
adata = ad.read_h5ad('data.h5ad', backed='r')
adata.write_h5ad('output.h5ad', compression='gzip')

# 10X Genomics (via scanpy)
import scanpy as sc
adata = sc.read_10x_h5('filtered_feature_bc_matrix.h5')

# Read MTX format
adata = read_mtx('matrix.mtx').T

3. 結合

柔軟な結合方法を使って、複数の AnnData オブジェクトを観測データまたは変数に沿って結合します。

参照：詳しくは references/concatenation.md をご覧ください。

• 基本的な結合（観測データには axis=0、変数には axis=1）
• 結合タイプ（inner、outer）
• マージ方法（same、unique、first、only）
• ラベルを使ったデータソースの追跡
• 遅延結合（AnnCollection）
• 大規模データセット向けのディスク上での結合

一般的なコマンド：

# Concatenate observations (combine samples)
adata = ad.concat(
    [adata1, adata2, adata3],
    axis=0,
    join='inner',
    label='batch',
    keys=['batch1', 'batch2', 'batch3']
)

# Concatenate variables (combine modalities)
adata = ad.concat([adata_rna, adata_protein], axis=1)

# Lazy collection over backed AnnData objects (experimental)
from anndata.experimental import AnnCollection

backed_adatas = [
    ad.read_h5ad(path, backed='r')
    for path in ['data1.h5ad', 'data2.h5ad']
]
collection = AnnCollection(
    backed_adatas,
    join_obs='outer',
    join_vars='inner',
    label='dataset'
)

4. データ操作

データを効率的に変換、サブセット化、フィルタリング、再編成します。

参照：詳しいガイダンスは references/manipulation.md をご覧ください。

• サブセット化（インデックス、名前、ブールマスク、メタデータ条件による）
• 転置
• コピー（完全なコピーとビュー）
• 名前の変更（観測データ、変数、カテゴリ）
• 型変換（文字列からカテゴリ型、スパースから密）
• データコンポーネントの追加と削除
• 並べ替え
• 品質管理フィルタリング

一般的なコマンド：

# Subset by metadata
filtered = adata[adata.obs['quality_score'] > 0.8]
hv_genes = adata[:, adata.var['highly_variable']]

# Transpose
adata_T = adata.T

# Copy vs view
view = adata[0:100, :]  # View (lightweight reference)
copy = adata[0:100, :].copy()  # Independent copy

# Convert strings to categoricals
adata.strings_to_categoricals()

5. ベストプラクティス

メモリ効率、パフォーマンス、再現性のために、推奨されるパターンに従ってください。

参照先：ガイドラインについては references/best_practices.md をご覧ください。

• メモリ管理（スパース行列、カテゴリ型、バックドモード）
• ビューとコピー
• データストレージの最適化
• パフォーマンスの最適化
• 生データの取り扱い
• メタデータ管理
• 再現性
• エラー処理
• 他のツールとの統合
• よくある落とし穴と解決策

主な推奨事項：

# Use sparse matrices for sparse data
from scipy.sparse import csr_matrix
adata.X = csr_matrix(adata.X)

# Convert strings to categoricals
adata.strings_to_categoricals()

# Use backed mode for large files
adata = ad.read_h5ad('large.h5ad', backed='r')

# Store raw before filtering
adata.raw = adata.copy()
adata = adata[:, adata.var['highly_variable']]

Scverse エコシステムとの統合

AnnData は、scverse エコシステムの基盤となるデータ構造です。

Scanpy（単一細胞解析）

import scanpy as sc

# Preprocessing
sc.pp.filter_cells(adata, min_genes=200)
sc.pp.normalize_total(adata, target_sum=1e4)
sc.pp.log1p(adata)
sc.pp.highly_variable_genes(adata, n_top_genes=2000)

# Dimensionality reduction
sc.pp.pca(adata, n_comps=50)
sc.pp.neighbors(adata, n_neighbors=15)
sc.tl.umap(adata)
sc.tl.leiden(adata)

# Visualization
sc.pl.umap(adata, color=['cell_type', 'leiden'])

Muon（マルチモーダルデータ）

import muon as mu

# Combine RNA and protein data
mdata = mu.MuData({'rna': adata_rna, 'protein': adata_protein})

PyTorch との統合

from anndata.experimental import AnnLoader

# Create DataLoader for deep learning
dataloader = AnnLoader(adata, batch_size=128, shuffle=True)

for batch in dataloader:
    X = batch.X
    # Train model

よくあるワークフロー

単一細胞 RNA-seq 解析

import anndata as ad
import scanpy as sc

# 1. Load data (10X via scanpy; anndata handles h5ad/zarr natively)
adata = sc.read_10x_h5('filtered_feature_bc_matrix.h5')

# 2. Quality control
adata.obs['n_genes'] = (adata.X > 0).sum(axis=1)
adata.obs['n_counts'] = adata.X.sum(axis=1)
adata = adata[adata.obs['n_genes'] > 200]
adata = adata[adata.obs['n_counts'] < 50000]

# 3. Store raw
adata.raw = adata.copy()

# 4. Normalize and filter
sc.pp.normalize_total(adata, target_sum=1e4)
sc.pp.log1p(adata)
sc.pp.highly_variable_genes(adata, n_top_genes=2000)
adata = adata[:, adata.var['highly_variable']]

# 5. Save processed data
adata.write_h5ad('processed.h5ad')

バッチ統合

# Load multiple batches
adata1 = ad.read_h5ad('batch1.h5ad')
adata2 = ad.read_h5ad('batch2.h5ad')
adata3 = ad.read_h5ad('batch3.h5ad')

# Concatenate with batch labels
adata = ad.concat(
    [adata1, adata2, adata3],
    label='batch',
    keys=['batch1', 'batch2', 'batch3'],
    join='inner'
)

# Apply batch correction
import scanpy as sc
sc.pp.combat(adata, key='batch')

# Continue analysis
sc.pp.pca(adata)
sc.pp.neighbors(adata)
sc.tl.umap(adata)

大規模データセットの取り扱い

# Open in backed mode
adata = ad.read_h5ad('100GB_dataset.h5ad', backed='r')

# Filter based on metadata (no data loading)
high_quality = adata[adata.obs['quality_score'] > 0.8]

# Load filtered subset
adata_subset = high_quality.to_memory()

# Process subset
process(adata_subset)

# Or process in chunks
chunk_size = 1000
for i in range(0, adata.n_obs, chunk_size):
    chunk = adata[i:i+chunk_size, :].to_memory()
    process(chunk)

トラブルシューティング

メモリ不足エラー

バックドモードを使用するか、スパース行列に変換してください。

# Backed mode
adata = ad.read_h5ad('file.h5ad', backed='r')

# Sparse matrices
from scipy.sparse import csr_matrix
adata.X = csr_matrix(adata.X)

ファイル読み込みが遅い

圧縮と適切な形式を使用してください。

# Optimize for storage
adata.strings_to_categoricals()
adata.write_h5ad('file.h5ad', compression='gzip')

# Use Zarr for cloud storage; v3 writes are opt-in in anndata 0.12
import anndata as ad

ad.settings.zarr_write_format = 3
ad.settings.auto_shard_zarr_v3 = True  # experimental; independent of zarr_write_format
adata.write_zarr('file.zarr', chunks=(1000, 1000))

インデックスの不整合

外部データは常にインデックスに基づいて整列してください。

# Wrong
adata.obs['new_col'] = external_data['values']

# Correct
adata.obs['new_col'] = external_data.set_index('cell_id').loc[adata.obs_names, 'values']

その他のリソース

• 公式ドキュメント：https://anndata.readthedocs.io/
• Scanpy のチュートリアル：https://scanpy.readthedocs.io/
• Scverse エコシステム：https://scverse.org/
• GitHub リポジトリ：https://github.com/scverse/anndata

エージェントの作業手順

1. 環境を確認します。 ツールのバージョン、参照ゲノム／アノテーションのビルド、入力形式（FASTQ、BAM、VCF、h5ad）を確認します。
2. 入力を明確にします。 データまたはユーザーから形式、識別子、パラメーターを確認します。結果に影響する値を推測せず、質問してください。
3. まず小規模なバージョンを実行します。 最初に小さなサブセット（1 サンプル、1 染色体、数千個の細胞）でパイプラインを実行します。
4. 上記の手順と参考資料を使用して、タスク全体を実行します。
5. 結果を検証します。 結果を解釈する前に、QC 指標、サンプルの同一性、ゲノムビルドの整合性、バッチ効果を確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未解決の不確実性を明記します。

発生した場合	対応
入力間でゲノムビルドまたは識別子が一致しない	続行する前に停止し、調整します（liftover、ID マッピング）。
これらの手順に記載された関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して対応し、ユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、またはパラメーターが曖昧	ユーザーに尋ねるか、実行前に仮定を明示します。

整合性に関するルール

• 結果、パラメーター、識別子、引用、統計値を決して捏造しないでください。実行または検証できないことがあれば、明確に伝えてください。
• 統計的な裏付けを超えて生物学的意義を解釈しないでください。多重検定補正を報告してください。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認してください。
• 費用が発生する操作、共有 GPU またはクラウドクォータを消費する操作、個人データまたは患者データに触れる操作、元に戻せない操作を行う前に確認してください。

関連スキル

• scanpy：標準的な単一細胞 RNA-seq 解析パイプライン。
• cellxgene-census：CZ CELLxGENE Census をプログラムからクエリし、バージョン管理された公開単一細胞および空間トランスクリプトームデータを取得します。
• scvi-tools：scvi-tools の確率的深層生成モデル（scVI、scANVI、totalVI、MultiVI、PeakVI、DestVI、Solo、CellAssign、MrVI…）をトレーニングして適用します。