AnnData

概要

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

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

以下の場合このスキルを使用してください:

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

インストール

uv pip install anndata

# With optional dependencies
uv pip install anndata[dev,test,doc]

クイックスタート

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)

データの読み込み

# 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
adata = ad.read_csv('data.csv')
adata = ad.read_loom('data.loom')
adata = ad.read_10x_h5('filtered_feature_bc_matrix.h5')

データの書き込み

# 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. 入出力操作

圧縮、バックドモード、クラウドストレージをサポートする様々な形式でデータを読み書きします。

参考: references/io_operations.md では以下について詳しく説明しています:

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

一般的なコマンド:

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

# Read 10X data
adata = ad.read_10x_h5('filtered_feature_bc_matrix.h5')

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

3. 連結

柔軟な結合戦略で複数の AnnData オブジェクトを観測または変数に沿って結合します。

参考: references/concatenation.md では以下について包括的にカバーしています:

• 基本的な連結 (観測は axis=0、変数は axis=1)
• 結合タイプ (内部、外部)
• マージ戦略 (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
from anndata.experimental import AnnCollection
collection = AnnCollection(
    ['data1.h5ad', 'data2.h5ad'],
    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)
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
adata = ad.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
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