单细胞分析

Seurat 对象搬到另一台机器后还能打开,却读不出表达矩阵,怎样修好?

作者:发布于 2026-11-17约 9 分钟阅读
Seurat 对象打开了,矩阵却读不出?,把旧目录藏起来,再验一次迁移。object.Rds 与真正的 BPCells 磁盘矩阵;只搬普通 RDS,旧矩阵路径失效时读层失败;48 颗细胞,计数总和 3,001,MS4A1 共 51

把一个 Seurat 对象从旧目录拷到另一台机器,读入没有报错,细胞数看起来也对。一旦提取某个基因的表达,程序才说找不到文件。这是使用磁盘矩阵时很有代表性的故障:对象的标签、元数据和某些降维坐标可能已经进了 RDS,表达层的实际内容却仍放在另一个目录。本篇直接附上一套真正能打开的小对象。我们先让旧路径失效,复现只搬普通 RDS 的失败,再从新的工作位置重新打开对象和矩阵,逐条码核对一次。

Seurat 对象打开了,矩阵却读不出?,把旧目录藏起来,再验一次迁移。object.Rds 与真正的 BPCells 磁盘矩阵;只搬普通 RDS,旧矩阵路径失效时读层失败;48 颗细胞,计数总和 3,001,MS4A1 共 51

下载完整代码、示例数据与参考输出(ZIP) · 下载图文操作手册(PDF)

为什么能看到细胞名,仍然不能说迁移成功

BPCells 可以把表达矩阵压缩存放在磁盘上,在 R 对象中保留对外部数据的引用和待执行操作。于是保存整个 Seurat 对象时,元数据可能已经足够让你列出样本、看到过去画好的 UMAP,甚至按标签给已有坐标重新上色;真正读取某一层的原始表达或执行新的汇总时才需要访问底层文件。这种依赖关系带来了大数据分析的便利,也改变了平日拷贝对象的习惯。接收文件后,第一件事应该是提取一小块自己认识的表达值,而不是只盯着对象摘要里的细胞总数。Seurat 的 BPCells 数据访问示例

练习取自公开 PBMC3K 的四十八颗实际细胞,八个参考标签各取六颗,选九个免疫相关基因。原始数表、条码与标签都很小,便于手算,这九个基因合计三千零一个分子,MS4A1 一行有五十一个。这里的三千零一仅指练习面板总和,不是四十八颗细胞的完整转录组深度。我们把同一矩阵用无符号整数类型交给 BPCells 写到磁盘,建立带有 RNA 计数层的 Seurat 对象。随包的对象、目录和输出均来自真实软件运行,没有用写一个伪 RDS 文件来模拟错误。

先造一份可核对的“搬家前”记录

从源对象实际读取 RNA 计数层,保留有顺序的条码、每个条码的面板计数总和,以及同一基因的逐条码原始值。只保存全局总数的证据不够,两个条码互换顺序后,整表求和仍然相同;甚至一个细胞少一个分子、另一个多一个分子,全局总数也不变。若项目依赖多个 assay 或外部数据层,还应把每层的类型、维度、基因名和细胞名记录下来,再选若干已知标记、低表达和零值区域作为迁移校验。按行列正式连接时使用条码与基因名,避免只靠保存文件的排列顺序蒙混过关。

这份教学矩阵很小,可以在示例函数里把它完整读出验证。几百万细胞的现实对象则应使用磁盘矩阵支持的按列求和和分块计算,再挑少数基因实际取值,别为了测试搬迁突然将整张矩阵转成稠密数组。逐文件的哈希与表达层的数值校验也互相补充:前者能找出漏拷、损坏或新旧版本混杂,后者验证加载函数确实指到预期的 assay、层和条码。就算两个同名 counts 目录结构完全一样,如果混用了别的样本,单靠“文件存在”仍会误判成功。

RDS 和磁盘目录怎样打包

练习首先让 counts 目录与 object.Rds 位于同一文件夹,调用官方保存函数记录相对路径,再把二者作为一组复制。这里使用的是 move 为假,因为矩阵已经放在需要的目录中,保存函数无需替我们移动原数据。选择相对路径是为了允许父目录变化,前提是 RDS 与其外部数据之间的结构保持一致。若实际对象来自多次合并,多个 assay 都有各自的磁盘层,不能机械复制一个名为 counts 的目录了事,要先列清所有依赖及路径,避免扁平化时撞名。SeuratObject 官方保存与读取说明

portable <- file.path(original,"object.Rds")
SaveSeuratRds(obj,file=portable,move=FALSE,relative=TRUE)
stage <- file.path(dst,"portable")
if(dir.exists(stage)) stop("Use a fresh output directory")
dir.create(stage)
stopifnot(file.copy(portable,stage),file.copy(disk,stage,recursive=TRUE))

在脚本自己创建的临时目录中,我们另存一份普通 RDS,再把原矩阵所在的临时源目录改名,从而使旧引用真实失效。接着尝试从普通 RDS 获取同一基因,读层失败。这个设计刻意不碰用户自己的源文件。若实际迁移时旧服务器仍在线,使用原绝对路径的对象可能通过共享挂载悄悄读回旧数据,那次所谓验收并未检验新副本。比起删除正式源文件,更稳妥的测试方式是在独立环境、未挂载旧路径的容器或新的会话里,从刚复制的资料夹完成读回。

验收项 搬迁前 目标目录中实际读取
特征与细胞数 9 × 48 9 × 48
面板原始计数总和 3,001 3,001
MS4A1 原始计数总和 51 51
每颗细胞的总数与 MS4A1 计数 保存成带条码的表 48 行逐条完全一致

从任意工作位置打开下载包

把 ZIP 完整解压,切到包根目录运行下面的命令。第一条 R 命令就能打开随包提供的实物;第二条使用源数表在新的输出目录从头重现一次普通 RDS 失败与完整包成功的对照。默认 Python 核验则读取真实 R 运行留下的前后数表和磁盘文件清单,绘出相同坐标轴、相同条码顺序的 MS4A1 表达图。若只有 Python,能核查参考计数和文件完整性;要测试你自己的 R 和 BPCells 是否真的能打开对象,应运行 R 的读回命令。不同层次的验收对应不同问题。

Rscript load_portable.R example/fit/portable
Rscript relocate.R example my_migration
python -m pip install -r requirements.txt
python run.py --input example --out results

在本例实测的软件组合中,读取相对路径的缓存时会按 R 当前工作目录查找。因此读回小程序先进入 RDS 所在的资料夹,再调用专门的加载函数;使用作用域限制的工作目录,离开后恢复调用者原来的位置。同时开启严格检查,若底层文件找不到,就不会把一个缺少 counts 的空壳对象当成验证通过。我们还从另一个新位置启动了第二次独立读回。碰到只在某个目录能工作的对象,可先打印实际工作目录、RDS 的绝对路径和矩阵相对位置,往往比反复重新安装包更快定位问题。

obj <- withr::with_dir(folder, LoadSeuratRds("object.Rds"))
m <- LayerData(obj, assay="RNA", layer="counts")
stopifnot(nrow(m)>0L, ncol(m)>0L, "MS4A1" %in% rownames(m))
print(c(features=nrow(m), cells=ncol(m), total_counts=sum(BPCells::colSums(m)),
        MS4A1=sum(as.matrix(m["MS4A1",,drop=FALSE]))))

哪些情况值得回到矩阵本身

如果有一个标记全为零,先看这个基因在迁移前是否确实不为零,再确认读取的层是否为原始计数,基因名有没有从符号换成稳定标识,目标细胞是否真在这个子集里。若条码数一致而总计数不同,优先检查是否混用了归一层、缩小面板或其他版本的底层文件。若只有一部分样本失败,检查对象内是否某个来源仍指向旧项目的绝对目录。验证时,可以对每个供者挑一颗有已知非零标记的细胞,既查零值也查非零,防止一整层被误替成零矩阵而没有被察觉。

如果接收者只有部分数据的读取权限,也可以先做最小复核:列出对象期望的各层目录,逐个实际读取第一批和最后一批条码,再比较少数分布在矩阵不同位置的非零值。读取目录列表成功不代表目录中每个文件都能访问。若仅在后半批条码报错,就把具体层、样本、条码范围和底层文件名记进交接记录,随后只补齐缺少的那部分,重跑同一套验收即可。

完整交接时,不妨让接手人用一个空工作目录启动 R,从压缩包原样解压的资料夹读取,再将输出的条码表和源记录对齐。除代码和对象外,保存版本、矩阵实际路径、文件清单以及一张可重画的表达图,下一次项目搬迁就有了验收标准。等到要把完整队列迁入新的计算环境,可先用这四十八颗细胞跑通读回,再携实际矩阵大小、磁盘需求与原软件版本选择云生信科研服务器租赁。

把知识用于当前任务

把方法直接跑起来

使用单细胞在线分析入口,减少环境配置和重复操作。

打开单细胞工具仍有疑问,联系客服 ↗