📚 课程目录第3章 Seurat简介与安装

3. Seurat 简介与安装：Seurat 生态介绍，安装与依赖配置（R 包版本管理）

3.1 Seurat 到底是什么？

做单细胞分析，绕不开 Seurat。这玩意儿是 Satija 实验室开发的 R 包，从 2015 年第一版到现在，已经成了单细胞数据分析的「事实标准」。我说的标准，不是因为它强制你用，而是社区生态太成熟了——教程、插件、问答、工具链，全围着它转。

我个人习惯把 Seurat 理解成一个「单细胞数据瑞士军刀」。从读数据、质控、归一化、降维、聚类，到差异表达、可视化、整合批次，它一套搞定。你不需要东拼西凑十几个包，一个 Seurat 能覆盖 80% 以上的分析流程。

嗯，这里要注意：Seurat 不是一个孤立的包，它背后有一整套依赖生态。你装 Seurat 的时候，系统会拉下来几十个依赖包——搞不好就冲突了。我后面会细讲怎么避坑。

    核心定位： Seurat 是单细胞转录组数据分析的集成式 R 包，提供从原始数据到生物学解释的全流程支持。

3.2 安装 Seurat：两种方式，各有场景

装 Seurat 有两种主流方式。我两种都用过，看场景选。

3.2.1 从 CRAN 安装（稳定版）

这是最推荐的方式。CRAN 上的版本经过严格测试，依赖关系也是打过包的。你直接跑一行命令就行：

install.packages("Seurat")

系统会自动拉取所有依赖包。R 4.0 以上版本一般不会出大问题。但——我遇到过几次，因为网络镜像源的问题，下载到一半断了。建议你提前配好国内镜像：

options(repos = c(CRAN = "https://mirrors.tuna.tsinghua.edu.cn/CRAN/"))
install.packages("Seurat")

小技巧： 如果你在公司内网或网络受限环境，可以先下载 .tar.gz 源码包，再用 install.packages("path/to/Seurat.tar.gz", repos = NULL, type = "source") 离线安装。

3.2.2 从 GitHub 安装（开发版）

有时候 CRAN 版本太稳了，稳到新功能还没上去。比如你想用 Seurat v5 的某些实验性整合方法，就得装开发版。

remotes::install_github("satijalab/seurat", "develop")

你想想看，开发版每天都有可能更新。好处是新功能快，坏处是——不稳定。我曾在项目中期因为更新了开发版，导致之前跑的聚类结果对不上，排查了两小时才发现是某个函数改了默认参数。

警告： 生产环境（正式分析项目）请用 CRAN 稳定版。开发版只建议在测试环境或验证新功能时使用。切换版本前，务必记录当前 Seurat 版本号，以便回溯。

3.3 依赖配置：R 包版本管理的那些坑

Seurat 的依赖包非常多。装完 Seurat 后，你用 packageDescription("Seurat")$Depends 看一下，会看到一长串。我这里列几个关键依赖：

依赖包	用途	常见版本问题
SeuratObject	定义 Seurat 数据结构	版本不匹配会导致对象无法读取
Matrix	稀疏矩阵运算	旧版本不支持某些新函数
dplyr / tidyr	数据操作	太新的 dplyr 可能和旧代码冲突
ggplot2 / patchwork	可视化	ggplot2 3.4+ 改了部分主题参数
RcppAnnoy / uwot	降维算法	需要本地编译工具链支持
spatstat.* (系列包)	空间转录组分析	安装时容易因为系统依赖报错

说白了，版本管理这件事，不做没事，一做全是事。尤其你同时跑多个项目，每个项目用的 Seurat 版本不一样——那感觉，酸爽。

3.3.1 用 renv 做项目级包管理

我个人强烈建议用 renv。它是 R 生态里目前最成熟的包版本管理工具，没有之一。

# 安装 renv
install.packages("renv")

# 在项目根目录初始化
renv::init()

# 安装 Seurat（版本会被锁定到 renv.lock 文件中）
renv::install("Seurat")

# 后续其他人克隆项目后，直接恢复环境
renv::restore()

renv 会在你的项目目录下生成一个 renv.lock 文件，里面记录了所有包的精确版本号。你把这个文件提交到 Git，团队其他人拉下来跑 renv::restore()，就能复现一模一样的环境。

    我曾经踩过的坑： 有次合作者发给我一个 Seurat 对象，我死活打不开。查了半天，发现他用 Seurat v4.9 存的，我装的是 v4.4。后来我养成了习惯——每接手一个项目，先跑 renv::init() 再看数据。

3.3.2 用 packrat 做备选方案

packrat 是 renv 的前身，理念类似，但更老一些。如果你还在用 R 3.x，packrat 可能是更稳的选择。不过新项目我建议直接上 renv。

install.packages("packrat")
packrat::init()
packrat::install("Seurat")

3.3.3 不用工具？那你得记住几个原则

如果你不做版本管理，至少记住这几点：

固定 R 版本。 一个项目对应一个 R 版本。不要用 R 4.3 跑完分析，切换 R 4.4 继续跑。
记录 Seurat 版本号。 每次输出结果时，顺手跑一句 sink("session_info.txt"); sessionInfo(); sink()。
别随便更新。 项目进行到一半，除非遇到 bug 必须修，否则不要更新任何包。
用 Docker 兜底。 如果你连 renv 都懒得配，至少打个 Docker 镜像。镜像在，环境就在。

3.4 验证安装：跑一个最小工作流

装完之后，怎么知道一切正常？别光看 library(Seurat) 不报错就完了。我建议你跑一个完整的最小流程：

library(Seurat)

# 创建一个小测试对象
test_counts <- matrix(rpois(2000, lambda = 1), nrow = 200, ncol = 10)
rownames(test_counts) <- paste0("Gene", 1:200)
colnames(test_counts) <- paste0("Cell", 1:10)

test_obj <- CreateSeuratObject(counts = test_counts)
test_obj <- NormalizeData(test_obj)
test_obj <- FindVariableFeatures(test_obj)
test_obj <- ScaleData(test_obj)
test_obj <- RunPCA(test_obj)
test_obj <- FindNeighbors(test_obj)
test_obj <- FindClusters(test_obj)
test_obj <- RunUMAP(test_obj)

DimPlot(test_obj, label = TRUE)

print("Seurat 安装验证通过！")

如果能跑通，说明你的 Seurat 环境和依赖都没问题。如果卡在某一部，看报错信息——大部分是依赖包版本不对，换个版本就行了。

快速诊断： 如果 library(Seurat) 报错依赖包缺失，用 install.packages("依赖包名") 逐个补装。如果报错提示「Namespace 不可用」，多半是包版本太旧，用 update.packages() 更新即可。

3.5 我的一点经验之谈

做了几年单细胞分析，我总结了几条关于 Seurat 安装和版本管理的血泪教训：

不要用 R 自带终端装 Seurat。 用 RStudio 或 Posit Cloud 会省心很多——依赖解析更透明，报错信息更友好。
Windows 用户注意。 有些依赖包（比如 RcppAnnoy）需要本地编译工具链。你去装个 Rtools（对应你的 R 版本），不然会卡在「编译失败」上。我曾经帮一个学生远程调试，折腾了两小时，最后发现他没装 Rtools。
Mac 用户用 Homebrew。 先装好 gfortran 和 OpenMP 支持，不然 uwot 包装不上。
Linux 用户最省心。 但注意系统库：libcurl, libxml2, libssl-dev 提前装好。

特别提醒： Seurat v5 与 Seurat v4 的对象结构有细微差异。如果你的项目需要兼容旧版本代码，请在安装时确认版本号：packageVersion("Seurat")。不同版本之间的 SeuratObject 可能不能直接互相读取。

嗯，关于安装和版本管理，就聊到这儿。你把这个基础打牢了，后面做整合分析的时候才不会被环境问题绊住脚。记住一句话：环境配不好，分析两行泪。