第3章 环境配置与工具安装：Seurat、Scanpy、STUtility、BayesSpace部署

这一章我们聊聊环境配置。说实话，很多初学者第一步就卡在这儿了——装了一堆包，一运行报错，最后发现是版本冲突。我当年做第一个空间转录组项目时，光装Seurat就折腾了两天。后来才发现，问题的根源在于没有做好环境隔离。

空间转录组工具链比较特殊：R阵营和Python阵营都要用，而且很多底层库（比如spatialdeconv、harmony）还会互相依赖。所以我的建议是——先别急着装，先把环境规划好。

3.1 整体架构：工具之间的关系

我们先画一张图，把你要装的工具和它们负责的环节看清楚。这样装起来心里有数，不会装错。

3.2 系统级依赖准备

不管你是用Windows、macOS还是Linux，下面这几样东西是绕不开的。

3.3 Conda环境创建与激活

我习惯为每个项目建独立环境，空间转录组项目我一般建两个：spatial_r 和 spatial_py。下面一步步来。

3.3.1 创建R环境

conda create -n spatial_r -c conda-forge r-base=4.3 r-essentials
conda activate spatial_r

R包里的Seurat可以用install.packages()，但我的经验是用BiocManager更稳，因为它会帮你处理版本依赖。

conda activate spatial_r
R
> install.packages("BiocManager")
> BiocManager::install("Seurat")
> BiocManager::install("STUtility")
> BiocManager::install("BayesSpace")

注意：STUtility的安装可能需要提前装好Spaceranger吗？不需要。STUtility直接读10x Visium的H5文件，跟Spaceranger是独立的关系。你只要保证Seurat版本在5.0以上就行。

3.3.2 创建Python环境

conda create -n spatial_py python=3.10
conda activate spatial_py
pip install scanpy[leiden]  # 或者用conda install -c conda-forge scanpy leidenalg
pip install anndata
pip install matplotlib seaborn
pip install jupyterlab

如果要用Scanpy里的sc.tl.leiden，别忘记装leidenalg和igraph。我刚开始总是忽略这步，然后跑聚类时报错——其实就是少装了一个包。

3.4 STUtility 的部署细节

STUtility主要是为了把多个Visium切片合并成一个整合对象。它内部用到了SpatialExperiment框架。安装时注意：

conda activate spatial_r
R
> BiocManager::install("STUtility")

如果报错package ‘RcppArmadillo’ not available，先装它：

install.packages("RcppArmadillo")

STUtility依赖spatstat.geom和terra，这些在conda环境里经常要编译。我个人建议在Linux上装系统库libgdal-dev和libproj-dev，不然terra会卡住。

3.5 BayesSpace 的部署

BayesSpace可以增强空间分辨率（比如从spot级别到subspot），我强烈推荐。它的安装有两种方式：

BayesSpace用到了RStan，而RStan又依赖C++工具链。我遇到过一个典型案例：在CentOS服务器上编译RStan失败，原因是gcc版本太低（4.8.5）。解决办法是用conda装gcc：

conda activate spatial_r
conda install -c conda-forge gxx_linux-64  # 在conda环境内提供现代gcc
R
> install.packages("rstan", repos = "https://cloud.r-project.org")

装完后检查一下：

library(BayesSpace)
?spatialCluster  # 能正常弹出帮助就算成功

3.6 配置验证：跑一个最小示例

装完不能就算完事，我习惯跑一段极小数据集验证每个工具是否正常工作。下面是个Scanpy验证例子：

conda activate spatial_py
python -c "
import scanpy as sc
adata = sc.datasets.pbmc3k()
sc.pp.filter_cells(adata, min_genes=200)
sc.pp.filter_genes(adata, min_cells=3)
sc.pp.normalize_total(adata, target_sum=1e4)
sc.pp.log1p(adata)
sc.tl.pca(adata)
sc.tl.leiden(adata)
print('Scanpy 验证通过，聚类数:', len(adata.obs['leiden'].unique()))
"

再验证Seurat：

conda activate spatial_r
R -e "
library(Seurat)
pbmc.data <- Read10X_h5(system.file('extdata','pbmc_10x.h5',package='SeuratObject'))
pbmc <- CreateSeuratObject(counts = pbmc.data)
pbmc <- NormalizeData(pbmc)
pbmc <- FindVariableFeatures(pbmc)
pbmc <- ScaleData(pbmc)
pbmc <- RunPCA(pbmc)
print('Seurat 验证通过')
"

验证通过后，你才算真正把环境搭好。

conda activate spatial_py
python -m ipykernel install --user --name spatial_py --display-name "Python (spatial)"
conda activate spatial_r
R -e "IRkernel::installspec(name='spatial_r', displayname='R (spatial)')"

3.7 常见避坑指南

• 坑一：R包版本冲突。比如Seurat 5要求SeuratObject >= 5.0.0，但BiocManager有时会装低版本。建议用remotes::install_version指定版本。
• 坑二：Scanpy导入错误。如果你遇到ImportError: cannot import name 'ensure_dtype_objs' from 'anndata'，多半是anndata版本太新（>0.8）。降级：pip install anndata==0.7.8。
• 坑三：STUtility空间对齐时出现“no valid spots”。这往往是你的Visium数据没有包含组织区域标记（如“tissue_positions_list.csv”），或者你的样本切片质量太差。检查一下raw_feature_bc_matrix目录下的barcode是否都在。
• 坑四：BayesSpace报错“Cholmod not found”。这是SPARK（空间自相关）库导致的。装SPARK前先装系统库libcholmod-dev。

3.8 小结：环境配置清单

我把核心命令整理成了一张清单，方便你对照执行。这张表也适合作为你本地配置的checklist。

环境配置是所有分析的基础。我曾经为了省事直接装全局R包，结果某次更新后Seurat和BayesSpace不兼容，整个项目延期一周——从那以后我真的老老实实用Conda环境。希望你一次成功，不用踩我踩过的坑。