📚 课程目录第2章环境搭建

2. 环境搭建

做单细胞和空间转录组分析，环境搭建是第一步，也是最容易踩坑的一步。我个人习惯先把基础环境搭得干净一点，后面能省很多时间。这章我就带着你从零搭一套 Python 和 R 的双语分析环境。

为什么环境这么重要？

说白了，多模态整合需要同时调十几个包。Python 那边有 Scanpy、Squidpy，R 这边有 Seurat、STUtility。它们依赖的底层库经常打架——比如 NumPy 版本不对，或者 R 的 Matrix 包编译不过。我刚开始做空间转录组时，光装 Squidpy 就折腾了两天，最后发现是 conda 和 pip 混用导致 glibc 冲突。嗯，那次之后我就学乖了，坚持用 conda 隔离环境。

所以建议你专门为这门课建一个新环境，不要跟其他项目混在一起。

Python 环境：conda + Scanpy / Squidpy

Python 这边我推荐直接用 miniconda。装好之后创建一个专属环境，指定 Python 3.10 左右（太新的版本有些包还没适配）。

conda create -n spatial_multi python=3.10 -y
conda activate spatial_multi

小技巧： 用 conda 不要加 -c conda-forge 参数去装生物信息包，直接 conda install 会自动从 conda-forge 解析依赖，速度更快。

接着安装核心包。Scanpy 和 Squidpy 是主线，anndata 和 leidenalg 是它们的下游依赖。

conda install -c conda-forge scanpy squidpy anndata leidenalg -y

如果你需要做图像处理，比如从 H&E 切片提取组织区域，Squidpy 依赖 opencv。我遇到过 opencv 在 conda 下安装失败的情况，后来换成 pip 就好了。

pip install opencv-python headless

其他常用辅助包也一起装上：

pip install matplotlib seaborn scikit-misc numpy pandas jupyter

验证 Python 环境

装完之后跑一段简单脚本测试，别等到跑数据时才发现缺包：

import scanpy as sc
import squidpy as sq
print(f"Scanpy version: {sc.__version__}")
print(f"Squidpy version: {sq.__version__}")

如果输出版本号，Python 环境就搭好了。我记得有一次打印出来 Squidpy 版本是 1.2.2 但文档里明明有 1.3 的功能，后来发现 conda 默认源更新慢，需要手动升级。

pip install --upgrade squidpy

R 环境：Seurat / STUtility

R 的环境搭建比 Python 玄学一点。我在项目里遇到过 R 4.2 和 Seurat 5 的兼容问题，也遇到过 STUtility 依赖的 spdep 包编译不过去。所以建议你直接从 R 4.3 开始。

先装 R 和 RStudio

去 CRAN 官网下载对应系统的 R 4.3 以上版本，再装 RStudio（可选，但推荐）。然后启动 R 控制台或 RStudio 的终端。

安装 Seurat

Seurat 是单细胞分析的标杆，但它的依赖挺重。直接装稳定版：

install.packages("Seurat")

如果你的网络慢，可以用国内镜像：

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

注意： 如果你用的是 R 4.2 或更早版本，Seurat 5 可能装不上。建议升级到 R 4.3。我曾经在老版本上花了半小时编译，最后报错找不到 VGAM，果断放弃升级。

安装 STUtility

STUtility 是把空间转录组数据转成 Seurat 对象的关键工具。它从 GitHub 安装，需要先装 remotes。

install.packages("remotes")
remotes::install_github("johandahlberg/STUtility")

安装过程中如果报错说缺 sf 或 spdep，先手动装上：

install.packages(c("sf", "spdep", "rgeos"))

装完之后测试：

library(Seurat)
library(STUtility)
sessionInfo()

能看到两个包的版本就算成功。有个坑：STUtility 的数据对象有时候自带列名是“ST”开头，和 Seurat 的默认行为不一样，分析前最好统一成小写，不过我后面会讲怎么处理。

各包的功能对比（一张表看清）

包名	语言	主要用途	典型场景
Scanpy	Python	单细胞转录组（质控、聚类、差异表达）	scRNA-seq 标准流程
Squidpy	Python	空间转录组（组织分割、空间近邻、基因表达趋势）	空间切片分析、配受体共定位
Seurat	R	单细胞 + 空间整合（harmony、标签转移）	多种数据整合、交互可视化
STUtility	R	将 10x Visium / ST 数据读入 Seurat 对象	空间数据预处理、批次校正

常见避坑指南

conda 与 pip 混用： 尽量先用 conda 装，如果找不到再用 pip，并且每次只在一个环境下操作。混用会导致两个包管理器互相覆盖，环境炸了谁都救不了。
R 包编译错误： 看到 "configure: error: gdal-config not found" 之类，去装系统库。Ubuntu 用 sudo apt install libgdal-dev，macOS 用 brew install gdal。
Scanpy 和 Squidpy 版本不匹配： 建议保持两者大版本一致。我用 Scanpy 1.9 配 Squidpy 1.2 没问题，但用 1.9 配 1.0 就会报函数名变化。直接 pip install 最新版省事。
Seurat 的 Assay5： 新版本默认创建 Assay5，但 STUtility 输出的是旧格式。分析前用 as(object, "Assay") 转换，否则某些函数报错。

我曾经在项目交付前夜发现 Squidpy 的 sq.gr.spatial_neighbors 函数在低版本上参数名不同，导致分析结果对不上。所以建议你装完环境后对照官方文档跑一遍教程数据集，确认功能正常再投入正式数据。

完整环境结构一览

我把 Python 和 R 两侧的依赖关系画成了一幅简图，方便你理解它们如何组装成一条工作流。

最后的检查清单

搭建完环境后，建议按下面的步骤走一遍，确认一切都就绪。否则真到分析时才发现缺包，会很影响节奏。

Python 端： 激活 conda 环境，运行 jupyter notebook 打开一个空白笔记本，依次 import scanpy、squidpy、anndata、matplotlib，没有报错。
R 端： 启动 R 终端，输入 library(Seurat); library(STUtility)，不出现红字错误。
数据测试： 用 Squidpy 内置的 Visium 切片示例跑一次 sq.datasets.visium_hne_adata()，或用 Seurat 加载 demo 数据试试。

我的习惯： 装完环境后会给它拍个快照（conda 用 conda list --export > environment.txt，R 用 sessionInfo() 保存）。以后项目重现或者换机器时直接还原，省去大量调试时间。

环境搭好了，我们就可以正式进入数据分析的实操了。我记得第一次成功跑通 Scanpy 的聚类流程时，还是蛮有成就感的。希望你也能顺利过关。