第2章 安装与配置BayesSpace环境
各位同学，咱们直接进入正题。做空间转录组分析，环境配置是绕不开的第一道坎。BayesSpace这个工具，说白了是个R包，但背后的依赖链可不简单。我见过太多人卡在安装这一步，原因无非是忽略了一些细节。
这一章，咱们就把环境搞定。你跟着我的步骤走，基本不会出问题。
2.1 环境概览与版本要求
先看看BayesSpace需要什么。我把它整理成一个表格，方便你对照检查。
| 依赖项 | 推荐版本 | 说明 |
|---|---|---|
| R | ≥ 4.1.0 | 建议用4.2.x或4.3.x，更稳定 |
| Bioconductor | ≥ 3.16 | 空间转录组数据底层的依赖 |
| rstan | ≥ 2.21.0 | MCMC采样引擎，核心计算依赖 |
| SpatialExperiment | ≥ 1.10.0 | 空间表达数据的标准容器 |
| ggplot2 | ≥ 3.4.0 | 可视化用，可选但强烈建议 |
嗯，这里要注意：rstan 是BayesSpace的“心脏”。它负责跑MCMC采样，如果装不好，后面所有聚类步骤都跑不起来。我早期做项目时，就因为rstan版本问题折腾了两天，后来发现是C++工具链没配好。
2.2 安装步骤详解
2.2.1 安装R与RStudio
这一步没什么好说的。去CRAN官网下R，装RStudio。我个人习惯是先把R装到默认路径，再装RStudio，这样后续包管理最省心。
验证安装是否成功，打开RStudio，在控制台里输入：
version看到类似 R version 4.3.2 (2023-10-31) -- "Eye Holes" 的输出，就对了。
2.2.2 配置Bioconductor环境
我建议先装BiocManager，它是Bioconductor的包管理入口。命令如下：
if (!requireNamespace("BiocManager", quietly = TRUE))
install.packages("BiocManager")
BiocManager::install(version = "3.18")装完之后，检查一下：
BiocManager::valid()如果返回 TRUE，说明环境干净，没冲突。如果返回包版本不一致的警告，那就得先更新。我遇到过这种情况，说白了就是系统里已经装了一些旧包，跟BiocManager不兼容。解决方案是执行 BiocManager::valid()$out_of_date 看哪些包需要更新，然后一个个来。
2.2.3 安装rstan及其依赖
这是最容易翻车的一步。rstan是R语言对接Stan（概率编程语言）的接口，底层依赖C++编译器和一些系统库。
第一步：检查C++工具链
运行下面命令，看你是不是装了编译器：
Sys.which("make")
Sys.which("g++")如果返回空路径，那就是没装。Windows用户得装Rtools，macOS用户需要Xcode Command Line Tools。别偷懒，必须装。
第二步：安装rstan
我推荐的安装方式：先安装预编译的包，再把MCMC编译优化打开。
install.packages("rstan", repos = c("https://mc-stan.org/r-packages/", getOption("repos")))然后配置编译选项。在 ~/.R/Makevars 文件（Windows是 ~/.R/Makevars.win）里加上：
CXX14 = g++ -std=c++14 -O3 -march=native
CXX14FLAGS = -O3 -march=native
CXX14STD = -std=c++14为什么加 -march=native？说白了就是让编译器针对你的CPU做指令优化，MCMC跑起来能快不少。我在服务器上配这个，采样速度提升了将近30%。
2.2.4 安装BayesSpace本体
终于到了主角登场。BayesSpace托管在Bioconductor上，直接用它来装：
if (!requireNamespace("BiocManager", quietly = TRUE))
install.packages("BiocManager")
BiocManager::install("BayesSpace")装完之后，加载包试试：
library(BayesSpace)
# 应该没有任何错误或警告
packageVersion("BayesSpace")看到版本号输出，比如 [1] '1.14.0'，说明安装成功。
2.3 环境验证与测试
装完了不代表能用。我习惯跑一个迷你测试，确保核心功能都正常。
library(BayesSpace)
library(SpatialExperiment)
# 加载示例数据
data(visium_example)
se <- visium_example
# 看看数据结构
dim(se)
# 预期输出: [1] 50 100
# 50个基因，100个点
# 运行聚类测试（跑几个iteration就行）
set.seed(2024)
se <- spatialPreprocess(se, n.PCs = 10)
se <- spatialCluster(se, q = 5, nrep = 100, save.chain = FALSE)
# 检查聚类结果
table(colData(se)$spatial.cluster)
# 应该有5个簇，每个簇的spot数量大致均衡如果这个测试跑通了，恭喜你，环境完全OK。如果跑的时候卡死或者报错，那基本上是rstan的问题，看看rstan的安装日志。
2.4 本章知识体系
我把整个环境配制的逻辑画成一张图，方便你理解每一步的依赖关系。
这张图从底层系统开始，一步步到顶层应用。你如果能把这个链条上的每一环都理通，以后装别的空间转录组工具也会轻松很多。
2.5 避坑指南与常见问题
最后，我把最常见的几个问题列出来。你们如果遇到类似的，直接对照着排查。
renv 包：renv::init() 初始化项目环境，后面所有包都装在这个隔离环境里，互不干扰。
install.packages() 里加 repos = getOption("repos")["BioC"]，或者手动设置镜像：options(BioC_mirror = "https://mirrors.tuna.tsinghua.edu.cn/bioconductor")。国内的话，用清华镜像通常快很多。
2.6 现在你的环境准备好了
到这一步，你的机器上已经装好了R、Bioconductor、rstan、BayesSpace以及所有核心依赖。你可以放心地进入下一阶段，用真实的空间转录组数据做空间聚类分析。记住，环境越干净，后面跑模型就越省心。