alterlab-anndata

AnnData

概要

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

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

次の場合にこのスキルを使用します：

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

該当しないケース

ケース	代わりに使用
QC、正規化、HVG、クラスタリング、UMAP、またはマーカー遺伝子	alterlab-scanpy
スプライス済み／未スプライスのレイヤーから RNA velocity を解析する	alterlab-scvelo
深層生成モデル／バッチ統合（scVI、scANVI）	alterlab-scvi-tools
参照細胞を探すために公開 CELLxGENE Census をクエリする	alterlab-cellxgene
AnnData モデルの範囲外でチャンク化された n 次元配列を扱う	alterlab-zarr

インストール

uv pip install anndata          # 0.13.x as of 2026-09; needs Python >= 3.12

# Lazy/backed reads (ad.experimental.read_lazy) need dask + xarray:
uv pip install 'anndata[lazy]'   # or 'anndata[dask]' for dask-backed arrays only

0.13 での変更点（破壊的変更）

既存のスクリプトに影響するため、古いコードを実行する前に確認してください：

• AnnData.concatenate() は削除されました — モジュールレベルの ad.concat([...]) を使用してください。
• .X は layers／obsm と同様にコピーオンライトになりました：サブセットへの書き込み（view.X = 0）は、親オブジェクトに反映されなくなりました。.X は現在 layers[None] として保存されるため、repr と .layers.keys() に表示されます。
• AnnData コンストラクターの dtype= 引数は削除されました — X はご自身で型変換してください。
• zarr v3 のみ（zarr >= 3.1）となりました。v2 形式の書き込みは 0.13.4 で非推奨となり、0.14 で削除されます。ストアはデフォルトでシャーディング形式で書き込まれます。
• anndata.__version__ と adata.*_keys() メソッドは非推奨です — importlib.metadata.version("anndata") と sorted(adata.obs)／k in adata.uns を使用してください。
• Loom I/O は非推奨です（ad.io.read_loom、adata.write_loom）。h5ad／zarr を使用してください。

クイックスタート

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)

データの読み込み

import scanpy as sc  # 10x readers live in scanpy, not anndata

# Read h5ad file
adata = ad.read_h5ad('data.h5ad')

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

# Read other formats (these live under ad.io as of anndata 0.11)
adata = ad.io.read_csv('data.csv')
adata = ad.io.read_mtx('matrix.mtx')
adata = sc.read_10x_h5('filtered_feature_bc_matrix.h5')

API 名前空間（anndata >= 0.11）：すべての形式リーダー／ライターは anndata.io モジュール（ad.io.read_csv、ad.io.read_mtx、ad.io.read_loom、ad.io.read_elem、...）にあります。トップレベルの ad.read_csv 形式のエイリアスは引き続き解決されますが、FutureWarning が発生します（0.12 で DeprecationWarning から引き上げられました）。また、anndata.read は 0.12 で削除されました。例外：ad.read_h5ad、ad.read_zarr、adata.write_h5ad、adata.write_zarr は警告なしで引き続きトップレベルにあります。

10x リーダー（read_10x_h5、read_10x_mtx）は anndata ではなく scanpy（sc.read_10x_h5）にあります。このスキルでは、解析固有の I/O は scanpy に委ねます。

データの書き込み

# 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')                  # zarr v3, sharded by default
adata.write_csvs('output_dir/', skip_data=False)  # skip_data defaults to True (obs/var only)

基本操作

# 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 モード
• リモートデータアクセス
• 形式変換
• パフォーマンスの最適化

よく使うコマンド：

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

# Read 10X data (10x readers live in scanpy, not anndata)
import scanpy as sc
adata = sc.read_10x_h5('filtered_feature_bc_matrix.h5')

# Read MTX format (.mtx is variables x observations; transpose so cells are rows)
adata = ad.io.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 concatenation — AnnCollection takes AnnData objects (open them backed), not paths
from anndata.experimental import AnnCollection
adatas = {p: ad.read_h5ad(f'{p}.h5ad', backed='r') for p in ('data1', 'data2')}
collection = AnnCollection(adatas, join_obs='outer', 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; writes to it copy-on-write in 0.13+)
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（シングルセル解析）

AnnData は scanpy のネイティブオブジェクトです。構築または読み込み後、そのまま渡せます。 前処理、次元削減、クラスタリング、プロット （sc.pp.normalize_total、sc.pp.highly_variable_genes、sc.pp.pca、 sc.pp.neighbors、sc.tl.umap、sc.tl.leiden、sc.pl.*）はanndata ではなく scanpy の役割です。解析ワークフローは scanpy に任せてください。

import scanpy as sc

sc.pp.filter_cells(adata, min_genes=200)  # scanpy mutates the AnnData in place
# ... continue the analysis pipeline in scanpy

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 (also accepts an AnnCollection)
dataloader = AnnLoader(adata, batch_size=128, shuffle=True)

for batch in dataloader:
    X = batch["X"]      # dict-style access; tensors, not attributes
    labels = batch["obs"]["cell_type"]
    # Train model

よくあるワークフロー

シングルセルデータのライフサイクル（anndata が担当する部分）

データを読み込み、obs／var の基本的な QC 指標を計算し、raw のスナップショットを作成して、サブセット化し、書き出します。 正規化／log1p／HVG／クラスタリングの手順は scanpy の担当です。そちらに引き継いでください。

import anndata as ad
import scanpy as sc

# 1. Load (10x readers live in scanpy)
adata = sc.read_10x_h5('filtered_feature_bc_matrix.h5')

# 2. Quick QC metrics on obs/var, then mask-subset (pure anndata wrangling)
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.obs['n_counts'] < 50000)].copy()

# 3. Snapshot raw before any gene filtering
adata.raw = adata.copy()

# 4. Hand off normalization / HVG / clustering to scanpy, then come back:
#    sc.pp.normalize_total / sc.pp.log1p / sc.pp.highly_variable_genes / ...
adata = adata[:, adata.var['highly_variable']].copy()  # subset is anndata's job

# 5. Save processed data
adata.write_h5ad('processed.h5ad', compression='gzip')

バッチ統合（連結してから補正を委ねる）

# Load and concatenate batches with source labels — this is anndata's job
adatas = [ad.read_h5ad(p) for p in ['batch1.h5ad', 'batch2.h5ad', 'batch3.h5ad']]
adata = ad.concat(
    adatas,
    label='batch',
    keys=['batch1', 'batch2', 'batch3'],
    join='inner',
)

# Batch correction and downstream analysis (combat / pca / neighbors / umap)
# are scanpy territory — pass `adata` to scanpy from here.

大規模データセットの操作

# 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
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

AlterLab Academic Skills スイートの一部です。