Monocle3在服务器上安装这件事前前后后折腾了我快两天。单细胞分析做到轨迹推断那一步基本绕不开这个包。它从2019年底推出以来就是拟时序分析的事实标准之一Cluster、UMAP降维、learn_graph学轨迹、order_cells算拟时时间一整条分析链路都能在它里面完成。但问题也出在这——它的依赖生态太庞大了在本地Windows上装都容易翻车放到服务器上更是集齐了权限、编译工具链、R版本、Bioconductor版本等各种烂事。这篇东西就是把我在服务器上安装monocle3踩过的坑、试过的方法、验证过的最佳路径全部写下来。无论你是刚接手服务器的小白还是已经被报错折磨到想放弃的老手照着这里面的路线走一遍基本都能顺利跑起来。1. 安装前必须搞清楚的几件事1.1 monocle3 的依赖生态为什么它天生难装先别急着敲命令搞清楚它依赖什么能帮你少走一半弯路。monocle3 不是那种install.packages(monocle3)一行就能装完的包它的核心依赖分三层。第一层是Bioconductor系。它构建在SingleCellExperiment数据结构之上同时依赖BiocGenerics、S4Vectors、SummarizedExperiment、DelayedArray、DelayedMatrixStats、limma、batchelor、HDF5Array等一大批Bioconductor包。这一层包如果版本不兼容后面编译monocle3的时候会直接报错。第二层是统计和绘图系。lme4做混合效应模型ggplot2和ggrastr负责可视化terra处理空间数据。ggrastr和terra都是需要系统级依赖库的这也是服务器上最常见的坑——R包本身装好了结果系统缺lib编译到一半挂掉。第三层是编译工具链。monocle3本体需要用Rcpp编译C代码所以你的服务器上必须要有完整的gcc、g、gfortran、make工具链。很多生物背景的同学服务器上连这些基础编译工具都没有一上来就install_github必然会炸。理解了这个依赖层次你就明白为什么网上教程那么多、还总是有人失败——因为每个人缺的东西不一样报错也五花八门。所以我下面给出的方案重点不是一条命令装完而是先帮你把环境理顺再谈安装。1.2 三种安装路线怎么选我在服务器上试过三种主流安装方式各有优劣给你做个对比安装路线优点缺点适合人群conda 预编译安装一条命令依赖自动处理极少编译需要装conda环境隔离是额外的学习成本新手、不想折腾环境的人Bioconductor依赖 GitHub源码编译可以拿到最新版灵活可控需要完整编译工具链报错概率高有一定Linux基础、需要最新功能的人Docker/Singularity镜像环境完全隔离换机器可复现镜像拉取容易失败存储和文件挂载配置有门槛需要跨机器复现、或服务器有容器平台的人我的个人建议是如果你只是为了做分析不是开发monocle3本身第一优先走conda路线。今天服务器上装环境我已经默认把conda作为第一选择理由后面细说。如果你一定要用GitHub上的最新开发版那至少在conda环境里把R和依赖装好再手动编译主体这能省掉90%的依赖冲突问题。2. 服务器环境准备2.1 用 conda 隔离出一个干净环境为什么要在服务器上装monocle3之前先装conda核心原因是隔离。生物信息服务器通常是多人共用的系统R可能是好几个版本乱了套Python环境更是谁都能动两下。如果你直接在系统R里面装包大概率会遇到权限不够、和别人的包版本冲突、装了一半发现某个依赖被覆盖。conda能让你在当前用户目录下创建一个完全独立的R环境不碰系统任何东西想怎么折腾都行。假设你服务器上还没装过conda用Miniconda安装最简单wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda3安装完成后初始化$HOME/miniconda3/bin/conda init然后重新登录终端或者直接source ~/.bashrc让conda生效。验证一下conda --version接着创建一个独立的单细胞分析环境名字自己定我习惯叫scrnaconda create -n scrna conda activate scrna注意很多人喜欢在这条命令里直接指定r-base4.2但我不建议一上来就指定。原因是你可能还需要在这个环境里装其他生信工具提前锁死版本反而容易冲突。先建空白环境后面按需装。提示如果服务器有管理员帮你装好了Anaconda你自己没有root权限无法全局安装也可以在个人目录装一个Miniconda完全不影响使用。这也是conda在生信服务器上这么流行的原因之一——不需要sudo一切都在用户目录里。2.2 系统级依赖库安装这一步非常关键很多人就是死在这里的。monocle3依赖的R包在编译时会调用一些C/C系统库如果你缺少它们编译会报各种configure: error: ... not found。常见需要的系统库包括libxml2-dev、libssl-dev、libcurl4-openssl-dev、libgsl-dev、libgeos-dev、libgdal-dev、libudunits2-dev、libproj-dev、zlib1g-dev。如果你在Ubuntu/Debian服务器上且有root权限sudo apt-get update sudo apt-get install -y libxml2-dev libssl-dev libcurl4-openssl-dev \ libgsl-dev libgeos-dev libgdal-dev libudunits2-dev libproj-dev zlib1g-dev同时检查编译工具链gcc --version g --version gfortran --version make --version如果哪个命令提示找不到就用apt装sudo apt-get install -y build-essential gfortran那如果你没有root权限呢两条路。一是直接用conda里的编译工具和系统库在conda环境里执行conda install -c conda-forge gcc_linux-64 gxx_linux-64 gfortran_linux-64 make二是直接用后面3.1的conda预编译路线conda会自动处理全部系统依赖不用手动装系统库。这也是conda最大的好处——把系统依赖也一起管了。2.3 R 包管理配置镜像提速在服务器上装R包默认下载源是CRAN和Bioconductor官方国内访问速度经常让人崩溃。装一个小包等五分钟装monocle3这种大型依赖树干等一小时都可能。所以提前配置镜像非常有必要。启动Roptions()$repos # 查看当前CRAN源改成清华镜像或你网络条件下更快的镜像options(repos c(CRAN https://mirrors.tuna.tsinghua.edu.cn/CRAN/))如果你想一劳永逸把这些配置写进~/.Rprofile文件echo options(repos c(CRAN https://mirrors.tuna.tsinghua.edu.cn/CRAN/)) ~/.RprofileBioconductor中国镜像在设置BioC源时也可以这样处理options(BioC_mirror https://mirrors.tuna.tsinghua.edu.cn/bioconductor)说实话镜像这个问题装了之后你感受最明显的就是下载速度快了好几倍你会有一种原来装包可以这么顺畅的感叹。3. 正式安装 monocle33.1 路线一conda 预编译一条龙最稳这是我最推荐给绝大多数人的路线尤其是纯生信数据分析的同学不用跟编译过程较劲。monocle3已经收录在bioconda渠道中可以直接通过conda安装conda activate scrna conda install -c conda-forge -c bioconda r-monocle3如果你前面已经建好环境这条命令会自动解析所有依赖包括R本体、Bioconductor包、系统库全部用预编译好的二进制安装整个过程基本不会触发源码编译所以几乎不会遇到编译失败的经典报错。装完之后在终端里执行R然后在R里加载library(monocle3)正常不报错就说明安装成功了。这个方案唯一的缺点是conda渠道里的monocle3版本可能比GitHub上的最新开发版慢一点但一般不影响分析使用。生信分析讲究的是稳定可复现而不是追新conda版本完全够用。3.2 路线二Bioconductor依赖 GitHub源码编译最灵活如果你坚持要用最新的GitHub版本或者conda渠道里没找到你想要的版本那走源码编译路线。这条路线比较长一步步来。先在R里安装Bioconductor依赖if (!requireNamespace(BiocManager, quietly TRUE)) install.packages(BiocManager) BiocManager::install(c( BiocGenerics, DelayedArray, DelayedMatrixStats, limma, lme4, S4Vectors, SingleCellExperiment, SummarizedExperiment, batchelor, HDF5Array, terra, ggrastr ))这一层如果某个包提示缺系统库回到2.2看对应那个库装上就行。接着安装devtools/remotesinstall.packages(remotes)然后从GitHub安装monocle3本体remotes::install_github(cole-trapnell-lab/monocle3)这里编译过程会持续一段时间终端上会刷大量的编译日志。如果最后出现DONE (monocle3)就代表编译成功。注意源码编译需要2-4GB左右的内存小内存云服务器比如2G的机器很容易在中途被系统杀掉进程。后面第4部分我会专门讲这个问题。3.3 路线三从 GitHub 拉最新开发版如果你想尝鲜GitHub上正在开发的新功能可以安装开发分支。仓库还是cole-trapnell-lab/monocle3但需要指定对应的分支或PRremotes::install_github(cole-trapnell-lab/monocle3dev)开发版的依赖变化更快可能会要求某几个Bioconductor包更新到最新版本。如果报错说某个依赖版本不足就更新那个包再重新编译一次。说实话这条路我只在需要某个新功能时才走日常分析还是用稳定版更好。3.4 安装自检加载测试与依赖体检无论哪条路线装完都要做一次完整的自检。光能library(monocle3)还不够还得确认关键依赖都能正常加载。在R里执行library(monocle3) packageVersion(monocle3) library(SingleCellExperiment) library(SeuratWrappers)如果你连SeuratWrappers一起装了就可以在Seurat对象和monocle3的cell_data_set对象之间来回转换这是单细胞分析工作流里很常用的一步。如果没有安装可以用BiocManager::install(SeuratWrappers)注意SeuratWrappers在CRAN和Bioconductor上都有安装方式服务器上常见的是通过remotes安装GitHub版本remotes::install_github(satijalab/seurat-wrappers)我在实际中踩过这个坑装了Bioconductor版本的SeuratWrappers结果和Seurat 5版本不兼容最后重装了GitHub版本才解决。所以这里也提醒一句如果你的Seurat版本是5.xGitHub的SeuratWrappers兼容性更高。4. 服务器上最常见的安装报错与排查方法4.1 编译器/系统依赖缺失类报错这类报错在源码编译路线里非常常见。典型的错误信息长这样configure: error: libxml2 not found或者System library ‘gsl’ not found或者configure: error: PROJ 6 or later is required看到这类信息先别想什么高深的问题十有八九就是系统缺库。回到2.2把对应的系统依赖装一遍。这里我把常见报错和需要安装的包整理成一张速查表报错关键词系统依赖Ubuntu/Debianlibxml2 not foundlibxml2-devlibssl / openssllibssl-devlibcurl not foundlibcurl4-openssl-devgsl not foundlibgsl-devGEOS not foundlibgeos-devGDAL / PROJlibgdal-dev libproj-devudunitslibudunits2-devzlibzlib1g-devgfortran not foundgfortran编译器在conda环境下优先用conda install -c conda-forge 包名代替apt安装这样conda会管理依赖避免系统库和conda环境冲突。4.2 R 与 Bioconductor 版本不匹配源码编译路线里第二个高频坑是R版本太旧或太新导致Bioconductor包装不上。比如R 4.0时代SingleCellExperiment还是1.x版本等R升到4.2之后Bioconductor 3.15/3.16的包接口有了变化monocle3的部分功能在不匹配时会直接报错。解决办法先把R版本升到4.2或4.3。在conda环境里指定版本安装conda install -c conda-forge r-base4.2然后重新装依赖。如果你用的是系统R那就得想别的办法我一般不推荐改系统R版本容易弄崩。conda的优势在这里就体现出来了——版本随便切换。另一个判断R/Bioconductor版本是否匹配的小技巧在R里执行BiocManager::version()它会告诉你当前Bioconductor版本。对照官网的版本对应表确认你的R版本是不是在支持范围内。4.3 编译卡死、内存溢出与超时服务器上编译monocle3最常见的一个问题不是报错而是编译到一半进程被kill掉。你观察到的现象是终端突然什么都不刷了回到命令行提示符似乎什么都没发生过。这多半是内存不足内核OOM Killer把编译进程干掉了。验证方法dmesg | grep -i killed process或者直接看系统内存free -h如果内存不够比如2G内存的小服务器有几个应对方案方案一增加swap空间sudo fallocate -l 8G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile方案二限制R编译时的线程数减少并发内存消耗。在编译前设置环境变量export MAKEFLAGS-j2方案三干脆走conda预编译路线不需要编译就没有这个问题。还有一个小技巧把R包编译目录放在磁盘空间充足的地方别放/tmp下因为/tmp如果满了也会导致诡异报错。可以在~/.R/Makevars里指定临时目录。4.4 conda 环境与系统 R 互相打架在服务器上很多时候conda环境和系统R是并存的。一个典型场景你明明在conda环境里conda install r-base装了新的R执行R命令的时候却调用到了系统里的老版R。原因很简单——PATH环境变量里conda的bin目录优先级不够或者你根本没有conda activate scrna。排查方法which R R --version如果which R显示的不是你conda环境路径下的R那就是PATH有问题。执行echo $PATH确认conda环境的bin目录在系统目录之前。正常情况下conda activate scrna which R应该显示/home/你的用户名/miniconda3/envs/scrna/bin/R。另一个打架场景是R包安装到了系统库加载时版本混乱。在R里检查.libPaths().libPaths()正常conda环境下的R.libPaths()第一项应该指向conda环境的lib/R/library。如果指向了/usr/lib/R/library说明R被系统的配置文件干扰了。可以在conda环境下设置R_LIBS_USER环境变量强制指向当前环境的包目录避免装到外面去。5. 装完之后跑通一个最小示例验证5.1 用内置数据创建 cell_data_setmonocle3安装好只是第一步能跑通流程才是最终目的。monocle3官方提供了一个小鼠胚胎单细胞数据集可以直接用来测试。在R里执行library(monocle3) expression_matrix - readRDS(url(https://cole-trapnell-lab.github.io/monocle3/mouse_embryo_expression_matrix.rds)) cell_metadata - readRDS(url(https://cole-trapnell-lab.github.io/monocle3/mouse_embryo_cell_metadata.rds)) gene_metadata - readRDS(url(https://cole-trapnell-lab.github.io/monocle3/mouse_embryo_gene_metadata.rds)) cds - new_cell_data_set(expression_matrix, cell_metadata cell_metadata, gene_metadata gene_metadata)new_cell_data_set是monocle3的核心构造函数三个输入分别是表达矩阵、细胞元数据、基因元数据。表达矩阵的格式是基因行× 细胞列这个方向千万别搞反了。如果数据下载慢或卡在url读取上可以把rds文件下载到本地再readRDS读取download.file(https://cole-trapnell-lab.github.io/monocle3/mouse_embryo_expression_matrix.rds, destfile mouse_embryo_expression_matrix.rds) expression_matrix - readRDS(mouse_embryo_expression_matrix.rds)5.2 从 Seurat 对象转换的实操细节如果你是用Seurat做前处理的那大概率手里是一个Seurat对象需要转成monocle3的cell_data_set。这个转换很常用也经常会出问题。转换代码很简单library(Seurat) library(SeuratWrappers) cds - as.cell_data_set(seurat_obj)但有几个细节要特别注意一是Seurat对象的assay名称。如果你的Seurat对象用了多个assay比如RNA和ADTas.cell_data_set默认取的是当前默认assay。转换前用DefaultAssay(seurat_obj)确认一下。二是如果你已经跑过UMAP坐标想保留这个坐标。monocle3会尝试从Seurat对象中读取UMAP坐标但如果转换后发现坐标丢失可以用cdsint_colDatalistData$reducedDims查看。有时坐标需要手动提取并赋值cdsreduce_dim_aux$UMAP - seurat_objreductions$umapcell.embeddings三是基因元数据。Seurat对象的meta.features可以赋给cds的基因元数据这样后续图形展示时能显示基因名gene_meta - seurat_obj[[RNA]]meta.features gene_meta$gene_short_name - rownames(gene_meta) cdsrowDataelementMetadata - gene_meta这一套转换操作我在实际项目中踩过好几次坑核心就是转换前做好数据检查转换后再检查元数据有没有完整复制过去。你不要等后面画图发现基因名都是空的再回头排查是不是转换时丢了字段。5.3 最小拟时序流程聚类、轨迹、拟时最后跑一个最小流程确认所有核心功能都正常。我用的测试数据集是monocle3官方示例代码写出来大概是这样cds - preprocess_cds(cds, num_dim 100) cds - reduce_dimension(cds) cds - cluster_cells(cds) cds - learn_graph(cds) cds - order_cells(cds) plot_cells(cds, color_cells_by pseudotime)一步步解释一下preprocess_cdsPCA降维num_dim是保留的主成分数一般用50~100之间根据数据规模调整。reduce_dimension默认用UMAP进一步降维到二维空间方便可视化和后续轨迹学习。算法平衡了全局结构和局部结构比tSNE更适合用来学习轨迹。cluster_cells在UMAP空间上进行聚类默认是Louvain算法。聚类结果会写入cell元数据里可以通过cdsclusters查看。learn_graph这一步是monocle3的核心——学习细胞状态转换的主图。它试图在UMAP空间中构建一个连接各种细胞状态的图后续拟时序就沿着这个图计算。order_cells手动选择根节点root然后计算每个细胞在图上的伪时间。运行之后会弹出交互式窗口让你选根节点如果是在无显示环境的服务器上跑会有点尴尬。服务器上无交互式选择根节点的话有一个替代做法先用plot_cells画出图确定根节点的UMAP坐标再用order_cells传入root_prune_graph或root_cells参数指定根细胞。官方文档里推荐用root_cells c(某细胞barcode)的方式这样可以在脚本里完成不做交互。如果以上流程都能跑通恭喜你monocle3安装成功并且可以正常使用了。单细胞分析的后续剧情——marker基因识别用top_markers轨迹基因用graph_test基因模块用find_gene_modules——就都可以放心去用了。这里补充一个我自己在服务器上跑单细胞分析的经验千万不要直接在白板终端里跑长任务一定要用screen或tmux把会话托管起来。单细胞数据动辄几万细胞learn_graph和order_cells跑起来可能是几十分钟甚至几小时的事SSH一断全部白干。我习惯所有分析脚本都放在tmux new -s analysis的会话里跑这是服务器上做生物信息分析最基本的习惯。好了关于monocle3在服务器上的安装能想到的坑和解决办法基本都写在上面了。最后说点个人的体会。我发现不少人遇到安装报错的第一反应是去搜索引擎复制报错信息然后一条一条试试不通就放弃。其实安装这类重依赖的R包最有效的思路是先诊断环境——R版本对不对、依赖层全不全、系统库缺不缺、权限有没有问题这四个维度检查完绝大多数问题都能准确定位。一个好的环境配置能让你在之后几个月的分析里都受益。还有一个建议是如果你现在所在实验室或公司有共享的服务器尽量在服务器上配好conda环境和这套安装流程后续同组同学就不用重复踩坑了。我甚至会把装好的环境直接打包成镜像或导出environment.yml换机器部署时就非常省事。如果你在安装过程中遇到了这里没写到的报错建议先看报错信息里有没有ERROR: dependency ... is not available这种提示那通常意味着某个依赖没装上补装就行。编译类报错就看是不是缺系统库。祝顺利跑通第一个轨迹分析。