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. 数据结构

了解 AnnData 对象结构，包括 X、obs、var、layers、obsm、varm、obsp、varp、uns 和 raw 组件。

参见：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，了解以下方面的指南：

• 内存管理（稀疏矩阵、分类数据、backed 模式）
• 视图与副本
• 数据存储优化
• 性能优化
• 使用原始数据
• 元数据管理
• 可复现性
• 错误处理
• 与其他工具集成
• 常见陷阱及解决方案

主要建议：

# 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 模式或转换为稀疏矩阵：

# 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

Agent 操作流程

1. 检查环境。 确认工具版本、参考基因组/注释版本和输入格式（FASTQ、BAM、VCF、h5ad）。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会改变结果的值都应询问，而非猜测。
3. 先运行小规模版本。 先在小型子集（一个样本、一条染色体、几千个细胞）上运行工作流。
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…）