⚡

AnnData（注释数据分析包）Skill anndata

AnnData是一个用于处理注释数据矩阵的Python包，特别在单细胞基因组学分析中广泛应用。它支持高效存储、操作和分析生物数据，集成了scverse生态系统，适用于数据科学和生物信息学领域。关键词：AnnData, 单细胞分析, 数据科学, Python, 基因组学, 数据分析, 生物信息学, scverse。

数据分析 0 次安装 0 次浏览 更新于 3/20/2026

名称: anndata 描述: 此技能应用于在Python中处理注释数据矩阵，尤其适用于单细胞基因组学分析、管理带有元数据的实验测量值或处理大规模生物数据集。当任务涉及AnnData对象、h5ad文件、单细胞RNA-seq数据或与scanpy/scverse工具集成时使用。

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

# 带有可选依赖
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({
    '细胞类型': ['T细胞', 'B细胞'] * 50,
    '样本': ['A', 'B'] * 50
}, index=[f'细胞_{i}' for i in range(100)])

var = pd.DataFrame({
    '基因名称': [f'基因_{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')

# 使用后端模式读取（适用于大文件）
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['细胞类型'] == 'T细胞']

# 根据索引子集化
subset = adata[0:50, 0:100]

# 添加元数据
adata.obs['质量分数'] = np.random.rand(adata.n_obs)
adata.var['高度可变'] = np.random.rand(adata.n_vars) > 0.8

# 访问维度
print(f"{adata.n_obs} 个观测 × {adata.n_vars} 个变量")

核心能力

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. 输入/输出操作

以各种格式读写数据，支持压缩、后端模式和云存储。

参见: references/io_operations.md 以获取详细信息：

  • 原生格式（h5ad、zarr）
  • 替代格式（CSV、MTX、Loom、10X、Excel）
  • 后端模式用于大型数据集
  • 远程数据访问
  • 格式转换
  • 性能优化

常见命令：

# 读写h5ad
adata = ad.read_h5ad('data.h5ad', backed='r')
adata.write_h5ad('output.h5ad', compression='gzip')

# 读取10X数据
adata = ad.read_10x_h5('filtered_feature_bc_matrix.h5')

# 读取MTX格式
adata = ad.read_mtx('matrix.mtx').T

3. 拼接

沿观测或变量方向组合多个AnnData对象，具有灵活的连接策略。

参见: references/concatenation.md 以获取综合覆盖：

  • 基本拼接（axis=0用于观测，axis=1用于变量）
  • 连接类型（内连接、外连接）
  • 合并策略（相同、唯一、第一个、仅限）
  • 使用标签追踪数据源
  • 懒拼接（AnnCollection）
  • 磁盘上拼接用于大型数据集

常见命令：

# 拼接观测（组合样本）
adata = ad.concat(
    [adata1, adata2, adata3],
    axis=0,
    join='inner',
    label='批次',
    keys=['批次1', '批次2', '批次3']
)

# 拼接变量（组合模态）
adata = ad.concat([adata_rna, adata_protein], axis=1)

# 懒拼接
from anndata.experimental import AnnCollection
collection = AnnCollection(
    ['data1.h5ad', 'data2.h5ad'],
    join_obs='outer',
    label='数据集'
)

4. 数据操作

高效转换、子集化、过滤和重组数据。

参见: references/manipulation.md 以获取详细指导：

  • 子集化（通过索引、名称、布尔掩码、元数据条件）
  • 转置
  • 复制（完整复制 vs 视图）
  • 重命名（观测、变量、类别）
  • 类型转换（字符串到分类、稀疏/密集）
  • 添加/移除数据组件
  • 重新排序
  • 质量控制过滤

常见命令：

# 根据元数据子集化
filtered = adata[adata.obs['质量分数'] > 0.8]
hv_genes = adata[:, adata.var['高度可变']]

# 转置
adata_T = adata.T

# 复制 vs 视图
view = adata[0:100, :]  # 视图（轻量级引用）
copy = adata[0:100, :].copy()  # 独立副本

# 转换字符串到分类
adata.strings_to_categoricals()

5. 最佳实践

遵循推荐模式以实现内存效率、性能和可重复性。

参见: references/best_practices.md 以获取指导方针：

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

关键推荐：

# 对稀疏数据使用稀疏矩阵
from scipy.sparse import csr_matrix
adata.X = csr_matrix(adata.X)

# 转换字符串到分类
adata.strings_to_categoricals()

# 对大型文件使用后端模式
adata = ad.read_h5ad('large.h5ad', backed='r')

# 过滤前存储原始
adata.raw = adata.copy()
adata = adata[:, adata.var['高度可变']]

与Scverse生态系统集成

AnnData作为scverse生态系统的基础数据结构：

Scanpy（单细胞分析）

import scanpy as sc

# 预处理
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)

# 降维
sc.pp.pca(adata, n_comps=50)
sc.pp.neighbors(adata, n_neighbors=15)
sc.tl.umap(adata)
sc.tl.leiden(adata)

# 可视化
sc.pl.umap(adata, color=['细胞类型', 'leiden'])

Muon（多模态数据）

import muon as mu

# 组合RNA和蛋白质数据
mdata = mu.MuData({'rna': adata_rna, 'protein': adata_protein})

PyTorch集成

from anndata.experimental import AnnLoader

# 为深度学习创建DataLoader
dataloader = AnnLoader(adata, batch_size=128, shuffle=True)

for batch in dataloader:
    X = batch.X
    # 训练模型

常见工作流

单细胞RNA-seq分析

import anndata as ad
import scanpy as sc

# 1. 加载数据
adata = ad.read_10x_h5('filtered_feature_bc_matrix.h5')

# 2. 质量控制
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. 存储原始
adata.raw = adata.copy()

# 4. 标准化和过滤
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['高度可变']]

# 5. 保存处理后的数据
adata.write_h5ad('processed.h5ad')

批次整合

# 加载多个批次
adata1 = ad.read_h5ad('batch1.h5ad')
adata2 = ad.read_h5ad('batch2.h5ad')
adata3 = ad.read_h5ad('batch3.h5ad')

# 带有批次标签拼接
adata = ad.concat(
    [adata1, adata2, adata3],
    label='批次',
    keys=['批次1', '批次2', '批次3'],
    join='inner'
)

# 应用批次校正
import scanpy as sc
sc.pp.combat(adata, key='批次')

# 继续分析
sc.pp.pca(adata)
sc.pp.neighbors(adata)
sc.tl.umap(adata)

处理大型数据集

# 在后端模式中打开
adata = ad.read_h5ad('100GB_dataset.h5ad', backed='r')

# 基于元数据过滤（不加载数据）
high_quality = adata[adata.obs['质量分数'] > 0.8]

# 加载过滤后的子集
adata_subset = high_quality.to_memory()

# 处理子集
process(adata_subset)

# 或以块处理
chunk_size = 1000
for i in range(0, adata.n_obs, chunk_size):
    chunk = adata[i:i+chunk_size, :].to_memory()
    process(chunk)

故障排除

内存不足错误

使用后端模式或转换到稀疏矩阵：

# 后端模式
adata = ad.read_h5ad('file.h5ad', backed='r')

# 稀疏矩阵
from scipy.sparse import csr_matrix
adata.X = csr_matrix(adata.X)

文件读取慢

使用压缩和适当格式：

# 存储优化
adata.strings_to_categoricals()
adata.write_h5ad('file.h5ad', compression='gzip')

# 对云存储使用Zarr
adata.write_zarr('file.zarr', chunks=(1000, 1000))

索引对齐问题

始终对齐外部数据于索引：

# 错误
adata.obs['new_col'] = external_data['values']

# 正确
adata.obs['new_col'] = external_data.set_index('cell_id').loc[adata.obs_names, 'values']

附加资源