anndata

用途

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 模式和云存储。10X Genomics 格式需通过 scanpy 读取。

拼接：可沿观测或变量方向组合多个 AnnData 对象，支持 inner/outer 连接类型、same/unique/first/only 合并策略，以及通过标签追踪数据来源。支持惰性拼接（AnnCollection）和面向大型数据集的磁盘拼接。

数据操作：支持按索引、名称、布尔掩码或元数据条件进行子集选择，转置、复制（完整副本与视图）、重命名、类型转换（字符串转分类、稀疏/稠密）、添加/删除数据组件、重排序和质量控制过滤。

最佳实践：提供内存管理（稀疏矩阵、分类变量、backed 模式）、视图与副本、数据存储优化、性能优化、原始数据处理、元数据管理、可复现性和错误处理等指南。

使用方式

安装要求 Python 3.11+，当前稳定版本为 0.12.16（2026-05-18 发布）。

uv pip install "anndata==0.12.16"

# 惰性 I/O 和 dask 后端操作
uv pip install "anndata[dask,lazy]==0.12.16"

# 开发/文档（贡献者）
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、mapping .keys() 和 importlib.metadata.version("anndata")。anndata.experimental API 视为有用但不稳定，仅在其当前限制可接受时用于大型数据工作流。

基本操作示例：

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

# 最小创建
X = np.random.rand(100, 2000)  # 100 个细胞 × 2000 个基因
adata = ad.AnnData(X)

# 读取数据
adata = ad.read_h5ad('data.h5ad')
adata = ad.read_h5ad('large_data.h5ad', backed='r')  # 大文件惰性加载
adata = ad.read_zarr('data.zarr')

# 写入数据
adata.write_h5ad('output.h5ad')
adata.write_h5ad('output.h5ad', compression='gzip')
adata.write_zarr('output.zarr')

# 子集选择
t_cells = adata[adata.obs['cell_type'] == 'T cell']
subset = adata[0:50, 0:100]

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

适用场景

创建、读取或写入 AnnData 对象
处理 h5ad、zarr 或其他基因组数据格式
执行单细胞 RNA-seq 分析
使用稀疏矩阵或 backed 模式管理大型数据集
拼接多个数据集或实验批次
对注释数据进行子集、过滤或转换
与 scanpy、scvi-tools 或其他 scverse 生态工具集成

限制

需要 Python 3.11+。
10X Genomics 格式需通过 scanpy 读取，而非 anndata。
anndata.experimental API 不稳定，仅在其当前限制可接受时用于大型数据工作流。
部分 API 已弃用，需使用替代方法。
版本特定细节可能过时，需对照已安装版本的官方文档确认。
不得编造结果、参数、标识符、引用或统计；无法运行或验证的内容应明确说明。
涉及费用、共享 GPU 或云配额、个人或患者数据、不可撤销操作时需先询问。

附加资源

官方文档：https://anndata.readthedocs.io/
Scanpy 教程：https://scanpy.readthedocs.io/
Scverse 生态：https://scverse.org/
GitHub 仓库：https://github.com/scverse/anndata

技能介绍

用途

主要能力

使用方式

适用场景

限制

相关技能

附加资源