用途
AnnData 是一个用于处理带注释数据矩阵的 Python 包，将实验测量数据（X）与观测元数据（obs）、变量元数据（var）以及多维注释（obsm、varm、obsp、varp、uns）一起存储。它最初面向单细胞基因组学，通过 Scanpy 使用，如今已作为通用框架，适用于任何需要高效存储、操作和分析的带注释数据。
主要能力
数据结构
理解 AnnData 对象结构，包括 X、obs、var、layers、obsm、varm、obsp、varp、uns 与 raw 组件，支持从多种来源创建对象、访问和操作数据组件，以及内存高效实践。
输入输出操作
支持多种格式的读写，包括原生格式（h5ad、zarr）、替代格式（CSV、MTX、Loom、10X、Excel）、大型数据集的 backed 模式、远程数据访问、格式转换与性能优化。
拼接
沿观测或变量方向合并多个 AnnData 对象，支持灵活的连接策略，包括基本拼接（axis=0 按观测，axis=1 按变量）、连接类型（inner、outer）、合并策略（same、unique、first、only）、用标签追踪数据来源、惰性拼接（AnnCollection）以及大型数据集的磁盘拼接。
数据操作
高效地转换、子集、过滤和重组数据，包括按索引、名称、布尔掩码或元数据条件进行子集选择，转置，复制（完整副本与视图），重命名（观测、变量、类别），类型转换（字符串转分类变量、稀疏/稠密），添加或移除数据组件，重新排序，以及质量控制过滤。
最佳实践
遵循推荐模式以实现内存效率、性能和可复现性，涵盖内存管理（稀疏矩阵、分类变量、backed 模式）、视图与副本、数据存储优化、性能优化、原始数据处理、元数据管理、可复现性、错误处理、与其他工具的集成以及常见陷阱与解决方案。
使用方式
安装
uv pip install anndata
可选依赖
uv pip install anndata[dev,test,doc]
创建 AnnData 对象
import anndata as ad import numpy as np import pandas as pd
最小创建
X = np.random.rand(100, 2000) # 100 个细胞 × 2000 个基因 adata = ad.AnnData(X)
带元数据
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)
读取数据
读取 h5ad 文件
adata = ad.read_h5ad('data.h5ad')
以 backed 模式读取（用于大文件）
adata = ad.read_h5ad('large_data.h5ad', backed='r')
读取其他格式
adata = ad.read_csv('data.csv') adata = ad.read_loom('data.loom') adata = ad.read_10x_h5('filtered_feature_bc_matrix.h5')
写入数据
写入 h5ad 文件
adata.write_h5ad('output.h5ad')
带压缩写入
adata.write_h5ad('output.h5ad', compression='gzip')
写入其他格式
adata.write_zarr('output.zarr') adata.write_csvs('output_dir/')
基本操作
按条件子集
t_cells = adata[adata.obs['cell_type'] == 'T cell']
按索引子集
subset = adata[0:50, 0:100]
添加元数据
adata.obs['quality_score'] = np.random.rand(adata.n_obs) adata.var['highly_variable'] = np.random.rand(adata.n_vars) > 0.8
访问维度
print(f"{adata.n_obs} observations × {adata.n_vars} variables")
适用场景
单细胞 RNA 测序分析
结合 Scanpy 进行数据加载、质量控制、归一化与过滤、高变基因选择、降维、可视化等完整流程。
批次整合
加载多个批次数据，按批次标签拼接，应用批次校正（如 sc.pp.combat），继续后续分析。
大型数据集处理
以 backed 模式打开数据（如 100GB 数据集），基于元数据过滤而不加载数据，将过滤后的子集加载到内存，或分块处理。
与 Scverse 生态集成
AnnData 是 scverse 生态的基础数据结构，可与 Scanpy（单细胞分析）、Muon（多模态数据）、PyTorch（通过 AnnLoader 创建 DataLoader）等工具集成。
常见问题排查
内存不足时可使用 backed 模式或转换为稀疏矩阵；文件读取慢时使用压缩和适宜格式；索引对齐问题时始终按索引对齐外部数据。
限制
资料中未明确列出 AnnData 的功能限制或约束条件。使用时建议参考官方文档与教程。
其他资源
官方文档：https://anndata.readthedocs.io/ Scanpy 教程：https://scanpy.readthedocs.io/ Scverse 生态：https://scverse.org/ GitHub 仓库：https://github.com/scverse/anndata