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

环境搭建：别让工具链卡住你的分析

做空间转录组分析，最让人头疼的往往不是算法本身，而是先把环境搭起来。Python、R、一堆包，还有 conda 的依赖地狱……说实话，我刚开始搞这个方向时，光配环境就折腾了两天。后来摸清了一套套路，基本半小时搞定。这一章我就把踩过的坑和最佳实践都摊开讲。

1. 选对包管理工具：conda + mamba

Python 生态里，pip 够用，但空间转录组涉及到很多底层 C/C++ 库（比如 anndata、igraph、sctransform），直接用 pip 编译很容易报错。我个人的习惯是优先用 conda，它能直接拉预编译好的二进制，省去编译烦恼。

更推荐装 mamba——它是 conda 的 C++ 重写版，解析依赖和安装速度翻倍。安装 conda 后，直接装 mamba：

conda install -c conda-forge mamba

遇到「Solving environment」卡住十几分钟？换 mamba 就行，基本秒解。

2. 创建独立环境

一定不要直接在 base 环境装东西。我吃过这个亏——某次装了 SeuratDisk 的 Python 版，把 base 里其他项目依赖搞崩了。后来我严格按项目建环境，一个分析项目一个环境。

mamba create -n spatialomics python=3.10
mamba activate spatialomics

Python 版本我推荐 3.9-3.11，目前社区对 3.12 支持还不全，尤其是 R 包通过 rpy2 调用时可能出现兼容问题。

3. 核心 Python 包安装

空间转录组 Python 栈以 Scanpy 和 Squidpy 为核心。Scanpy 做单细胞级的预处理、降维、聚类；Squidpy 专注于空间统计与形态学分析。我是这么装的：

mamba install -c conda-forge scanpy squidpy
mamba install -c conda-forge leidenalg  # 可选，但推荐加速聚类

千万别用 pip install 硬装 scanpy，除非你确保系统里 gcc 版本够新。我在 CentOS 7 上遇过 ld: cannot find -lpython3.10 的错误，换 conda 秒解。

其他常用辅助包：

anndata：常用数据结构，scanpy 已自动依赖
matplotlib + seaborn：可视化必备
scipy、pandas、numpy：基础计算库
igraph：网络分析，Squidpy 空间图用

全部装完可以用这个命令验证：

python -c "import scanpy as sc; import squidpy as sq; print(sc.__version__, sq.__version__)"

4. R 环境：用 renv 或 conda 管理

虽然 Python 越来越强，但 Seurat 仍然是空间转录组界的「老大哥」，很多新方法（如 Cell2location、Stereoscope）原生就是 R 包。我一般用 conda 管理 R，比手动装 R 再逐个装包省心——尤其是当依赖 Bioconductor 包时。

mamba install -c conda-forge r-base=4.3
mamba activate spatialomics

然后进入 R 交互环境装 Seurat 和其空间依赖：

install.packages("Seurat")
install.packages("remotes")
remotes::install_github("satijalab/seurat-data")

if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install(c("SpatialExperiment", "ggspavis"))

如果安装 Seurat 时提示缺少字体库，别挣扎——直接 apt install libfontconfig1-dev（Linux）或 brew install fontconfig（macOS）。

5. Squidpy 与 Seurat 协同注意点

你可能在同一个项目里同时用 Scanpy/Squidpy（Python）和 Seurat（R）。两个世界的数据交换靠 anndata 与 SeuratObject 之间的桥梁。

功能	工具	说明
读取 visium 数据	Scanpy / Seurat	两边都原生支持 Space Ranger 输出
空间邻居图构建	Squidpy / Seurat	Squidpy 用坐标网格法，Seurat 用 X/Y 距离法
数据转换到 Python	SeuratDisk / anndata2ri	我常用 anndata2ri，直接在 R 环境中写 h5ad 文件
可视化	Scanpy / ggplot2	可单独选，别混用

转换示例（在 R 中执行）：

library(anndata)
# 将 Seurat 对象转换成 h5ad
seu_obj <- readRDS("seurat.rds")
ad <- AnnData(
    X = t(GetAssayData(seu_obj, slot = "data")),
    obs = seu_obj[[]],
    var = data.frame(gene = rownames(seu_obj))
)
ad$write_h5ad("converted.h5ad")

一句话总结：Python 做预处理和空间统计，R 跑 Seurat 里那些成熟的整合算法（如 Harmony、CCA）。两个环境不冲突，关键在于数据格式统一。

6. 避坑指南——我踩过的那些坑

conda 环境中混合使用 pip 和 conda 装同一库：容易导致符号表冲突，特别是 numpy、scipy。我的规则：底层库用 conda，纯 Python 包（如 matplotlib）可以用 pip。
R 包的本地编译失败：我曾在 macOS M1 上装 Seurat 报错，最后发现是 Xcode 命令行工具版本太老。运行 xcode-select --install 后解决。
Scanpy 版本过低导致 Squidpy 不兼容：Squidpy 1.2+ 要求 Scanpy >= 1.9，如果用 conda 自动解析，通常不会出问题。但如果你手动装了低版本，记得检查。
空间坐标数据丢失：我在转换 Seurat 到 anndata 时，忘记把 spatial 坐标塞到 obs 里，后来 Squidpy 画空间图时一片空白。解决方案：在 Seurat 中用 GetTissueCoordinates(seu_obj) 拿到坐标，手动写入 anndata 的 obs。

7. 本章知识图谱

下面这张图概览了从零到可分析的环境搭建流程。我个人觉得它最能帮新手快速建立全局认知：

8. 最后：检查你的环境是否完备

我在新机器上装完后，会跑一段「烟雾测试」——用官方样例数据集快速过一遍流程，确保所有包能正确协作。给你一个最简单的测试脚本：

import scanpy as sc
import squidpy as sq

# 下载 Visium 小鼠脑切片示例
adata = sq.datasets.visium_hne_adata()
sc.pp.filter_genes(adata, min_cells=3)
sc.pp.normalize_total(adata, target_sum=1e4)
sc.pp.log1p(adata)
sq.gr.spatial_neighbors(adata)
print("空间邻居图构建完成，无报错")

如果这行得通，恭喜——你的环境已经 ready，可以正式进入数据预处理与空间分析环节了。