AnnData 实战指南用 annotated data matrices 构建可复用的单细胞分析数据层【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills本文围绕仓库中 anndata 技能 展开系统讲解 AnnData 对象结构、.h5ad/zarr 等格式的读写、数据拼接、子集操作与内存优化策略并给出与 scanpy、scvi-tools、cellxgene-census 等 scverse 生态工具配合使用的完整代码方案。读完本文你将掌握一套在 Python 3.11 环境中用 AnnData 0.12.x 构建、清洗、存储和交付单细胞数据分析结果的标准技能可直接复用于单细胞 RNA-seq、多组学合并与大规模数据集的工程化处理。Skill 定位为什么把数据格式本身做成一项技能在 skills/anndata/SKILL.md 的技能元信息中本 skill 被精确定义为data format skill数据格式技能而不是分析流程技能。这一区分非常重要它决定了在什么场景下应该选用哪个技能需要在.h5ad、zarr 等格式之间搬运、创建、写入带注释的数据矩阵时用anndata需要执行过滤、标准化、聚类、UMAP 等完整单细胞分析流程时应改用 scanpy 技能需要拟合概率生成模型如 scVI、scANVI时应使用 scvi-tools 技能需要在群体规模population-scale上查询数据如 CELLxGENE Census时应使用 cellxgene-census 技能。元信息同时声明了运行时边界要求 Python 3.11 与uv示例针对 AnnData 0.12.16使用实验性 APIanndata.experimental的地方会明确标注。allowed-tools为 Read / Write / Edit / Bash即该技能除了被读取外还预期能写入数据文件、编辑脚本并通过 Bash 安装依赖。安全审查结论见 docs/security-report.md也将该 skill 评估为纯文档型参考材料仅含标准的库用法示例。AnnData 的适用面很广创建、读取、写出 AnnData 对象处理 h5ad、zarr 等基因组学格式进行单细胞 RNA-seq 分析借助稀疏矩阵或 backed 模式管理大规模数据跨批次拼接多个数据集子集、过滤与变换以及与 scanpy、scvi-tools 等 scverse 工具对接。环境要求与安装官方推荐使用uv进行环境管理要求 Python 3.11当前稳定版本 0.12.16。安装分为三档对应不同用途# 最小安装基础读写 uv pip install anndata0.12.16 # 惰性 I/O 与 dask-backed 操作大数据工作流 uv pip install anndata[dask,lazy]0.12.16 # 开发 / 文档面向贡献者 uv pip install anndata[dev,test,doc]0.12.16只有在有意跟踪最新兼容版本时才使用非固定版本安装其余场景建议锁定版本以保证可复现性。版本相关的 API 注意点围绕 0.12 版本skill 文档明确给出了三类 API 使用纪律优先从anndata.io导入非原生格式的辅助读写函数read_*/write_*系列在 0.11 之后主要收归anndata.io模块顶层anndata.read_h5ad与anndata.read_zarr仍受支持且不产生弃用告警。避免已弃用 APIad.read、AnnData.concatenate()、AnnData.*_keys()系列、anndata.__version__均应替换为ad.read_h5ad、ad.concat、映射mapping的.keys()以及importlib.metadata.version(anndata)。anndata.experimental可用但视为不稳定适合用于大数据工作流前提是接受其当前已知限制如AnnCollection、AnnLoader、read_lazy、concat_on_disk等均在 experimental 命名空间下。快速上手创建、读取与基础操作创建一个 AnnData 对象最小创建方式只需一个二维数据矩阵X形状为n_obs × n_varsimport 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[fcell_{i} for i in range(100)]) var pd.DataFrame({ gene_name: [fGene_{i} for i in range(2000)] }, index[fENSG{i:05d} for i in range(2000)]) adata ad.AnnData(XX, obsobs, varvar)其中obs的行索引与X的观测行一一对应var的行索引与X的变量列一一对应这是 AnnData 一切对齐操作的基础。读取数据# 原生格式read_h5ad / read_zarr 保留在顶层 adata ad.read_h5ad(data.h5ad) adata ad.read_h5ad(large_data.h5ad, backedr) # 大文件惰性读取 adata ad.read_zarr(data.zarr) # 其他格式优先从 anndata.io 导入 from anndata.io import read_csv, read_loom, read_mtx adata read_csv(data.csv) adata read_loom(data.loom) # 10X Genomics请用 scanpy而非 anndata读取 import scanpy as sc adata sc.read_10x_h5(filtered_feature_bc_matrix.h5) adata sc.read_10x_mtx(filtered_feature_bc_matrix/)写出数据# 写出 h5ad 文件 adata.write_h5ad(output.h5ad) # 带压缩写出 adata.write_h5ad(output.h5ad, compressiongzip) # 写出其他格式 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)核心数据结构X、obs、var 与多维注释组件AnnData 将实验测量值与注释封装在同一个对象中。完整版对象结构说明见 data_structure.md下面给出各组件的作用与命名习惯。X主数据矩阵X存储(n_obs, n_vars)的实验测量。既可以是稠密numpy.ndarray也推荐在数据稀疏时使用scipy.sparse的 CSR/CSC 矩阵AnnData 0.12 仅接受 CSR 或 CSC 格式的稀疏输入import anndata as ad import numpy as np from scipy.sparse import csr_matrix # 稠密创建 adata ad.AnnData(Xnp.random.rand(100, 2000)) # 稀疏创建推荐用于大规模稀疏数据 sparse_data csr_matrix(np.random.rand(100, 2000)) adata ad.AnnData(Xsparse_data)obs 与 var行列注释obsDataFrame每行对应X中的一个观测如cell_type、treatment、timepoint、n_genes、n_counts等varDataFrame每行对应X中的一个变量如gene_name、chromosome、highly_variable等。obs_df pd.DataFrame({ cell_type: [T cell, B cell, Monocyte], treatment: [control, treated, control], }, index[cell_1, cell_2, cell_3]) adata ad.AnnData(Xnp.random.rand(3, 100), obsobs_df) print(adata.obs[cell_type]) print(adata.obs.loc[cell_1])layers同维度的备用矩阵layers是一个字典存放与X同形状的其他表示便于同时保留原始计数、归一化值与标准化值adata.layers[raw_counts] np.random.randint(0, 100, (100, 2000)) adata.layers[normalized] adata.X / np.sum(adata.X, axis1, keepdimsTrue) adata.layers[scaled] (adata.X - adata.X.mean()) / adata.X.std()常见的 layer 约定包括raw_counts归一化前原始计数、normalizedlog-normalized 或 TPM、scaledZ-score 值供模型使用与imputed插补结果。obsm / varm观测侧与变量侧的多维坐标obsm与观测对齐的多维数组如 PCA 坐标、UMAP/t-SNE 嵌入、diffusion map 坐标甚至 CITE-seq 蛋白表达矩阵varm与变量对齐的多维数组如 PCA 载荷、基因模块打分。adata.obsm[X_pca] np.random.rand(100, 50) # 50 个主成分坐标 adata.obsm[X_umap] np.random.rand(100, 2) # 2D UMAP 嵌入 adata.varm[PCs] np.random.rand(2000, 50) # 变量侧 PCA 载荷约定俗成的键名X_pca、X_umap、X_tsne、X_diffmap、X_draw_graph_fr是 scanpy/scverse 生态互认的关键——scanpy 的绘图函数会直接按这些键名在obsm中查找坐标。obsp / varp成对关系矩阵存储观测与观测、变量与变量之间的成对稀疏矩阵通常存为scipy.sparse矩阵from scipy.sparse import csr_matrix adata.obsp[connectivities] csr_matrix(np.random.rand(100, 100) 0.95) # 细胞邻接图 adata.obsp[distances] csr_matrix(np.random.rand(100, 100)) # 细胞间距离 adata.varp[correlations] csr_matrix(np.random.rand(2000, 2000) 0.99) # 基因相关connectivities与distances分别对应 kNN 图与距离矩阵是 scanpy 中neighbors步骤的直接产物。uns非结构化注释uns用于存放任意自由形式元数据分析参数、调色板、聚类信息、处理历史与版本号等adata.uns[experiment_date] 2025-11-03 adata.uns[pca] {variance_ratio: [0.15, 0.10, 0.08], params: {n_comps: 50}} adata.uns[neighbors] {params: {n_neighbors: 15, method: umap}}raw过滤前的原始快照在过滤基因之前用adata.raw adata.copy()保存原始数据与变量注释之后便可随时用adata.raw.X访问未过滤的表达矩阵用于差异表达检验或对过滤掉基因的可视化。对象属性速查n_observations adata.n_obs n_variables adata.n_vars shape adata.shape # (n_obs, n_vars) obs_names adata.obs_names var_names adata.var_names is_view adata.is_view # 是否为另一对象的视图 is_backed adata.isbacked # 是否由磁盘文件 backing filename adata.filename # backing 文件路径若为 backedobs_vector()与var_vector()可将指定注释列或指定变量的值直接抽取为一维数组方便与 numpy 计算对接。输入输出从 h5ad 到 zarr 再到海量文件策略完整 I/O 指南见 io_operations.md。AnnData 的 I/O 体系围绕原生格式优先、其余格式收归anndata.io展开。H5AD默认的原生格式H5AD 基于 HDF5提供高效存储与快速随机访问并支持 backed 模式# 写文件 adata.write_h5ad(data.h5ad) adata.write_h5ad(data.h5ad, compressiongzip) adata.write_h5ad(data.h5ad, compressiongzip, compression_opts9) # 0-9越高压缩越强 # 读文件 adata ad.read_h5ad(data.h5ad) adata ad.read_h5ad(data.h5ad, backedr) # 只读 backed adata ad.read_h5ad(data.h5ad, backedr) # 可读写 Xbacked 模式是处理大于内存数据集的关键手段adata ad.read_h5ad(large_dataset.h5ad, backedr) # 不加载 X 即可查看元数据 print(adata.obs.head()) print(adata.var.head()) # 切片操作只生成视图不加载数据 subset adata[:100, :500] # 真正按需加载某块数据 X_subset subset.X[:] # 整个对象载入内存 adata_memory adata.to_memory()一个重要约束是backed 模式下只有X的修改会被写回磁盘obs/var/uns的改动必须to_memory()后另存为新文件。Zarr面向云端与并行 I/O# 写 zarrchunks 对性能至关重要 adata.write_zarr(data.zarr, chunks(100, 100)) # 读 zarr adata ad.read_zarr(data.zarr)在 anndata 0.12 中默认仍写 Zarr v2可通过设置项选择 v3 与实验性的自动分片auto-shardingimport anndata as ad ad.settings.zarr_write_format 3 ad.settings.auto_shard_zarr_v3 True # experimental与 zarr_write_format 相互独立 adata.write_zarr(data.zarr, chunks(1000, 1000))远程 zarr 访问可通过fsspec完成但文档明确提示只应从可信且预期的位置打开远程 store如白名单内的 HTTPS/S3/GCS 路径或带签名的 URL不要让 Agent 去拉取任意的用户提供 URLimport fsspec store fsspec.get_mapper(s3://bucket-name/data.zarr) adata ad.read_zarr(store)备选输入格式一览格式函数位于 anndata.io说明CSV/TSVread_csv(path, delimiter,, first_column_namesTrue)基因按列、细胞按行Excelread_excel(path, sheetSheet1)可指定 sheetMatrix Marketread_mtx(path, var_namesgenes.tsv, obs_namesbarcodes.tsv)需配套基因/条形码文件必要时.T转置10Xsc.read_10x_h5/sc.read_10x_mtxscanpy 提供可传genome参数Loomread_loom(path, obs_namesCellID, var_namesGene)旧式单细胞格式纯文本read_text(path, delimiter\t, dtypefloat32)通用定界文本UMI-toolsread_umi_tools(counts.tsv)—通用 HDF5read_hdf(data.h5, keydataset)非 h5ad 的 HDF5写出侧的备选包括write_csvs(output_dir/)生成 X.csv、obs.csv、var.csv 等多个文件可用skip_dataTrue跳过 X与write_loom(output.loom)。细粒度读写与惰性操作对于只读一部分的场景可以用read_elem/write_elem直接操作已打开的 HDF5 store 中的元素对超大文件可用 experimental 的惰性读取接口返回 dask-backed 数组import h5py from anndata.io import read_elem with h5py.File(data.h5ad, r) as f: obs read_elem(f[obs]) # 只读 obs params read_elem(f[uns/pca]) # 只读 uns 子元素 from anndata.experimental import read_lazy, read_elem_lazy adata read_lazy(large_data.zarr) # 惰性读取整对象 with h5py.File(large_data.h5ad, r) as f: X_lazy read_elem_lazy(f[X]) # 惰性读元素 subset X_lazy[:100, :100].compute()格式转换与云端安全下载from anndata.io import read_mtx, read_csv # MTX → H5AD adata read_mtx(matrix.mtx).T adata.write_h5ad(data.h5ad) # CSV → H5AD read_csv(data.csv).write_h5ad(data.h5ad) # H5AD → Zarr ad.read_h5ad(data.h5ad).write_zarr(data.zarr)下载远程数据时io_operations.md 示范了先解析 URL、核对协议与主机白名单、再下载的校验模式避免无差别拉取不可信来源。I/O 性能要点读取大文件用backedrbackedr只用于改XH5AD 随机访问最快zarr 更适合云端与并行访问写入长期存储用compressiongzip或compressionlzfLZF 更快但压缩率更低zarr 的 chunk 大小应匹配访问模式——顺序读用大 chunk随机访问用小 chunk写前优化先把字符串列转成 categorical再写入文件更小。数据拼接ad.concat 与面向大数据的惰性方案多批次、多样本、多模态数据的合并是日常刚需。完整指南见 concatenation.md。沿观测轴与变量轴拼接import anndata as ad import numpy as np adata1 ad.AnnData(Xnp.random.rand(100, 50)) adata2 ad.AnnData(Xnp.random.rand(150, 50)) # 沿观测默认 axis0合并样本/细胞 combined ad.concat([adata1, adata2], axis0) # (250, 50) # 沿变量axis1合并模态/基因 adata_rna ad.AnnData(Xnp.random.rand(100, 2000)) adata_protein ad.AnnData(Xnp.random.rand(100, 50)) multimodal ad.concat([adata_rna, adata_protein], axis1) # (100, 2050)join 与 fill_valuejoininner只保留所有对象共有的变量/观测交集joinouter保留全部并补齐缺失稀疏矩阵补 0、稠密矩阵补 NaN也可用fill_value0显式指定。adata_inner ad.concat([adata1, adata2], joininner) # 交集 adata_outer ad.concat([adata1, adata2], joinouter) # 并集 adata_filled ad.concat([adata1, adata2], joinouter, fill_value0)用 label / keys 追踪数据来源合并时记录每行来自哪个批次是后续批次校正的前提adata_combined ad.concat( [adata1, adata2, adata3], labelbatch, # 标签列名 keys[batch1, batch2, batch3], # 每个对象的标签 ) print(adata_combined.obs[batch].value_counts()) # batch1 100 # batch2 150 # batch3 200不传keys时会退化为整数 0、1、2若各对象行名重叠可用index_unique_在索引后追加批次键生成唯一名例如cell_1_batch1。merge / uns_merge元数据如何合并merge参数控制非拼接轴上元数据的取舍策略mergeNone默认行为仅在元数据完全一致时保留mergesame只保留在所有对象中相同的列mergeunique保留每个键取值唯一的列mergefirst取第一个含有该键对象的取值mergeonly保留只出现在一个对象中的列。uns则通过uns_merge单独控制递归合并时同样支持same/unique等语义。layers、obsm 与成对矩阵的拼接行为只要所有对象都含有某个 layerad.concat会自动沿观测拼接该 layerobsm/varm中的嵌入自动沿各自轴拼接obsm[X_pca]拼成(250, 50)obsp/varp默认不拼接需显式传入pairwiseTrue此时成对矩阵会被拼成块对角矩阵adata_combined ad.concat([adata1, adata2], pairwiseTrue) print(adata_combined.obsp[connectivities].shape) # (250, 250)惰性拼接 AnnCollection 与磁盘拼接面对十几个 GB 级别的分片 h5ad直接ad.concat会把所有数据载入内存。experimental 的AnnCollection提供沿观测轴的惰性拼接视图数据只有在被访问时才真正加载from anndata.experimental import AnnCollection backed_adatas [ad.read_h5ad(p, backedr) for p in [data1.h5ad, data2.h5ad]] collection AnnCollection( backed_adatas, join_obsouter, join_varsinner, labeldataset, keys[dataset1, dataset2], ) print(collection.n_obs) # 总观测数不触发 X 加载 print(collection.obs.head()) # 只加载元数据 subset collection[collection.obs[cell_type] T cell] # 不加载数据的子集 adata collection.to_adata() # 需要真实数据时再整体物化若需要生成真正的合并文件experimental 的concat_on_disk可直接在磁盘上拼接多个 h5ad全程不载入内存from anndata.experimental import concat_on_disk concat_on_disk([data1.h5ad, data2.h5ad], combined.h5ad, joinouter) adata ad.read_h5ad(combined.h5ad, backedr)拼接最佳实践拼接前核对n_vars与var_names兼容性按需选inner最严格各批次基因一致或outer最包容保留全部基因永远用labelkeys记录来源批次大数据优先AnnCollection/concat_on_disk并对结果使用 backed 模式注意拼接不会消除批次效应需在合并后补批次校正如sc.pp.combat(adata, keybatch)合并后验证 shape、批次分布与元数据完整性。数据操作与变换manipulation.md 系统覆盖了子集、转置、复制、重命名、类型转换、增删改与重排等操作。子集化四种索引方式# 按整数下标 subset adata[0:100, 0:500] subset adata[[0, 10, 20, 30, 40], [0, 1, 2]] # 按名称 subset adata[[cell_0, cell_1, cell_2], :] subset adata[:, [gene_0, gene_10, gene_20]] # 按布尔掩码 subset adata[adata.obs[quality_score] 0.5, :] # 按组合元数据条件 filtered adata[ (adata.obs[cell_type] A) (adata.obs[quality_score] 0.7), adata.var[highly_variable] ]转置、复制、重命名# 转置交换 obs 与 var处理基因在行的格式时很有用 adata_T adata.T # 视图与复制切片默认得到 view不复制底层数据 view adata[0:100, :] # 轻量引用 print(view.is_view) # True copy adata[0:100, :].copy() # 独立副本 # 重命名观测/变量 adata.obs_names [fnew_cell_{i} for i in range(adata.n_obs)] adata.obs_names_make_unique() # 为重复名追加后缀 adata.rename_categories(cell_type, {Type_A: T_cell}) # 重命名类别类型转换from scipy.sparse import csr_matrix, issparse # 字符串 → categorical内存效率更高 adata.strings_to_categoricals() # 稠密 ↔ 稀疏 if not issparse(adata.X): adata.X csr_matrix(adata.X) if issparse(adata.X): adata.X adata.X.toarray()增删组件与重排元数据列可用 pandas 语义直接增删layers/obsm/obsp/uns都是字典支持del adata.layers[x]、adata.obsm {}等操作。重排则以索引为媒介# 按元数据排序观测 adata adata[adata.obs.sort_values(quality_score).index, :] # 重排以匹配外部列表 adata adata[desired_cell_order, :] adata adata[:, desired_gene_order]常用操纵模板质控过滤adata.obs[n_genes] (adata.X 0).sum(axis1)后按阈值过滤低质量细胞与稀有基因高变基因筛选计算方差后以np.percentile划阈值掩码子集并.copy()降采样与划分用np.random.choice可设np.random.seed(42)随机抽样或用sklearn.model_selection.train_test_split做按cell_type分层划分训练/测试集。与 scverse 生态集成AnnData 是整个 scverse 生态的共享数据层SKILL.md 专门列出三种典型集成方式。Scanpy单细胞全流程import scanpy as sc # 预处理 sc.pp.filter_cells(adata, min_genes200) sc.pp.normalize_total(adata, target_sum1e4) sc.pp.log1p(adata) sc.pp.highly_variable_genes(adata, n_top_genes2000) # 降维与聚类 sc.pp.pca(adata, n_comps50) sc.pp.neighbors(adata, n_neighbors15) sc.tl.umap(adata) sc.tl.leiden(adata) # 可视化 sc.pl.umap(adata, color[cell_type, leiden])Muon多模态数据import muon as mu # 用 MuData 同时容纳 RNA 与蛋白两个 AnnData mdata mu.MuData({rna: adata_rna, protein: adata_protein})PyTorch深度学习对接experimental 的AnnLoader把 AnnData 包装为 PyTorch DataLoader可直接喂给神经网络from anndata.experimental import AnnLoader dataloader AnnLoader(adata, batch_size128, shuffleTrue) for batch in dataloader: X batch.X # Train model此外更复杂的概率模型交给 scvi-tools 技能群体规模的数据检索交给 cellxgene-census 技能它们都以 AnnData 作为输入输出契约。三个端到端工作流工作流一单细胞 RNA-seq 从 10X 到产物import anndata as ad import scanpy as sc # 1. 读取 10X 数据scanpy 负责 10X 格式 adata sc.read_10x_h5(filtered_feature_bc_matrix.h5) # 2. 质控 adata.obs[n_genes] (adata.X 0).sum(axis1) adata.obs[n_counts] adata.X.sum(axis1) adata adata[adata.obs[n_genes] 200] adata adata[adata.obs[n_counts] 50000] # 3. 过滤前保存 raw adata.raw adata.copy() # 4. 归一化与高变基因 sc.pp.normalize_total(adata, target_sum1e4) sc.pp.log1p(adata) sc.pp.highly_variable_genes(adata, n_top_genes2000) adata adata[:, adata.var[highly_variable]] # 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], labelbatch, keys[batch1, batch2, batch3], joininner ) sc.pp.combat(adata, keybatch) # 拼接后必须显式做批次校正 sc.pp.pca(adata) sc.pp.neighbors(adata) sc.tl.umap(adata)工作流三超内存数据集的 backed 分块处理# 打开不载入内存 adata ad.read_h5ad(100GB_dataset.h5ad, backedr) # 按元数据过滤不加载 X high_quality adata[adata.obs[quality_score] 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)最佳实践与性能优化best_practices.md 给出了覆盖内存、存储、性能与可复现性的完整清单。内存管理三板斧稀疏矩阵当数据零占比超过 50% 时转为 CSR单细胞计数数据通常可比稠密存储减少 10–100 倍内存字符串转 categorical重复字符串列转 category 可减少 10–50 倍内存backed 模式让数据集大小可以超过 RAM。from scipy.sparse import csr_matrix, issparse # 根据稀疏度决定存储形态 density np.count_nonzero(adata.X) / adata.X.size if not issparse(adata.X) and density 0.5: adata.X csr_matrix(adata.X) adata.strings_to_categoricals() # 大文件用 backed 打开只把过滤后的子集 to_memory() adata ad.read_h5ad(large_dataset.h5ad, backedr) filtered adata[adata.obs[quality_score] 0.8] adata_subset filtered.to_memory()View 与 Copy 的取舍切片默认生成 viewis_view True不复制数据、只读操作很省内存但当要保存子集、修改子集数据、或把子集交给会改数据的函数时务必.copy()常见坑subset adata[:100, :]后对subset.X ...可能反过来污染原对象del adata也可能让未复制的 view 失效。存储格式选择H5ADHDF5随机访问快、支持 backed、压缩好覆盖绝大多数场景Zarr云端S3/GCS友好、支持并行 I/O0.12 起可选用 v3 与自动分片适合大数据与并行处理CSV人类可读、可被任何工具消费但体积大且慢仅适合小数据或跨语言共享。写前优化三连稀疏化 → 字符串转 categorical →compressiongzip, compression_opts9典型可让文件体积缩小 5–20 倍。性能小技巧布尔掩码子集优先用 numpy 数组而非 Series整数索引最快避免对同一对象反复切片先用obs.groupby(...).groups分组再一次性取各组下标用chunked_X(chunk_size1000)逐块迭代而不是一次性adata.X。raw 的正确用法在过滤高变基因前用adata.raw adata.copy()保留全基因表达之后做差异表达、绘制被过滤基因的可视化或取回归一化前原始计数都通过adata.raw完成。访问前先判断adata.raw is not None。元数据与可复现性遵循 scverse 命名约定obs用n_genes/n_counts/percent_mito/leidenobsm用X_pca/X_umap…让对象可被生态工具直接消费在uns中记录列描述、处理步骤清单与随机种子版本追踪用from importlib.metadata import version; version(anndata)因为anndata.__version__已弃用分析参数PCA 的n_comps、svd_solver、neighbors 的n_neighbors/metric写进uns便于追溯。数据与元数据校验assert adata.n_obs len(adata.obs) assert adata.n_vars len(adata.var) assert adata.X.shape (adata.n_obs, adata.n_vars) assert adata.obs_names.is_unique and adata.var_names.is_unique # 检查缺失值与负值 if issparse(adata.X): has_nan np.isnan(adata.X.data).any() else: has_nan np.isnan(adata.X).any()索引对齐高频坑位向obs追加外部数据时按顺序直接赋值不可靠必须按索引对齐# 错误假设外部数据顺序一致 adata.obs[new_col] external_data[values] # 正确先建索引再按 obs_names 对齐 adata.obs[new_col] external_data.set_index(cell_id).loc[adata.obs_names, values]完整的优实践工作流best_practices.md 末尾给出了一份可直接套用的 9 步工作流backed 载入 → 元数据速览 → 元数据过滤 →to_memory()→ 字符串转 categorical 稀疏化 → 存 raw → 过滤高变基因并.copy()→ 在uns记录处理过程 → 压缩写出。它把本小节全部要点串成一份生产级模板。常见故障排查SKILL 文档与参考文件共同覆盖了四类高频问题1. 内存溢出OOM改用 backed 模式读取或把稠密矩阵转成稀疏adata ad.read_h5ad(file.h5ad, backedr) from scipy.sparse import csr_matrix adata.X csr_matrix(adata.X)2. 文件读取缓慢 / 体积过大先strings_to_categoricals()再write_h5ad(..., compressiongzip)云端场景改用 zarr 并按需设置 chunkadata.strings_to_categoricals() adata.write_h5ad(file.h5ad, compressiongzip) ad.settings.zarr_write_format 3 adata.write_zarr(file.zarr, chunks(1000, 1000))3. backed 模式下无法改元数据backed 只持久化X的改动元数据变化需to_memory()后另存新文件。4. 索引错位 / 稀疏稠密混用外部数据一律按索引.loc[adata.obs_names, ...]对齐避免在稀疏矩阵上做会触发稠密化的运算如adata.X 1改用稀疏友好的写法X.copy()后修改.data处理完切片后若担心视图副作用遵循需要独立数据就.copy()的纪律。结语与扩展阅读AnnData 的意义在于它把矩阵 注释做成了可验证、可拼接、可流式处理、可对接深度学习的统一数据契约。本技能以 format-first 的姿态把读写、拼接、操纵与大数据的工程细节沉淀为一份可执行文档正好补齐了仓库中 scanpy分析、scvi-tools概率模型、cellxgene-census群体数据 所依赖的底层数据基础设施。仓库内的配套案例见 docs/examples.md也常以anndata作为上游格式定义技能与其他分析技能的组合起点。如需进一步深挖可按主题阅读本技能下的五份参考文档数据结构、I/O 操作、数据拼接、数据操纵 与 最佳实践它们分别对应本技能结构、存取、合并、变换、性能五大能力支柱。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考