环境搭建：Python 依赖安装、mofapy2 包安装与测试运行
说实话，很多跑 MOFA 的人，一上来就栽在环境上。代码还没跑通，先被各种依赖报错折磨半小时。我自己这几年接触过的项目里，因为 Python 版本不一致、虚拟环境没隔离导致的问题，起码占了一半。所以这一章，咱们就把环境彻底拧清楚。
嗯，先聊个题外话。我的习惯是，所有数据分析项目都单独建一个虚拟环境。为什么？因为项目间依赖冲突太常见了——你跑 A 项目需要 numpy 1.23，B 项目偏偏只能在 1.18 上跑。不隔离，早晚出事。
基础环境要求
先确认你的 Python 版本。我用的是 Python 3.8 到 3.11 之间。太老了（比如 3.6）有些包连安装都会报错，太新了（比如 3.12）mofapy2 本身的脚本可能不兼容。
| 组件 | 推荐版本 | 我踩过的坑 |
|---|---|---|
| Python | 3.8–3.11 | 3.12 下 numpy 编译失败 |
| pip | ≥ 23.0 | —— |
| 操作系统 | Linux / macOS / WSL2（Windows） | Windows 原生 cmd 容易缺 GCC 环境 |
如果你用的是 Windows 原生环境，我个人建议装个 WSL2。否则后面编译某些底层扩展时，你会想砸电脑的。我曾经在一个 Windows 服务器上配了两天，最后换了 WSL2 半小时搞定。
Python 依赖安装
MOFA 本身对底层科学计算包依赖很严格。核心依赖包括：numpy、scipy、pandas、scikit-learn、h5py。别小看这些“基础包”——版本错了，模型训练时直接崩溃。
我个人习惯的做法是——先创建一个虚拟环境，再挨个装。有人觉得麻烦，但这是最稳的。
# 创建虚拟环境（我的习惯是用 python3 -m venv）
python3 -m venv mofa_env
# 激活环境
# Linux / macOS:
source mofa_env/bin/activate
# Windows (cmd):
mofa_env\Scripts\activate.bat环境激活后，开始安装依赖。我一般先把核心科学计算包一次性装上，这样可以避免依赖顺序问题。
pip install numpy==1.24.3
pip install scipy==1.10.1
pip install pandas==2.0.3
pip install scikit-learn==1.3.0
pip install h5py==3.9.0你可能会问：为什么不直接用 requirements.txt 一键安装？可以，但如果你是新机器，我建议你先装 numpy。为什么？因为 mofapy2 的安装脚本在编译时会依赖 numpy 的 C API。如果你先装 mofapy2 再补 numpy，大概率会报 ImportError。我遇到过至少两次这种坑。
mofapy2 包安装
核心包装完后，轮到 mofapy2 了。这个包现在托管在 PyPI 上，直接 pip 就能装。但要注意，它有两个版本通道：一个是稳定版，一个是开发版。我个人只推荐稳定版，除非你非要尝鲜新功能。
# 稳定版安装（推荐）
pip install mofapy2安装过程中，你会看到终端刷屏——一部分是编译 Cython 扩展，一部分是下载依赖。等它完全静下来后，怎么确认成功？
快速验证方法：在激活的虚拟环境中，打开 Python，运行下面两行代码。不报错，就算是装上了。
python -c "import mofapy2; print(mofapy2.__version__)"如果输出类似 1.6.1 这样的版本号，恭喜你，环境搭成了。
验证安装与测试运行
光导包不报错还不够，我还会跑一个最小化的测试用例。MOFA 官方提供了一个模拟数据集，正好拿来用。这叫“冒烟测试”——能跑通，才算真的能用。
from mofapy2.run.mofa import entry_point
# 创建一个最小配置
ent = entry_point()
ent.set_data_options(scale_views=True, scale_groups=True)
# 使用内置模拟数据（20 个样本，5 个特征，1 个视图）
ent.set_data_from_url("https://raw.githubusercontent.com/bioFAM/MOFA2/master/data/example_data.txt", delimiter=",")
# 设置模型参数（我习惯先设个小模型跑得快）
ent.set_model_options(factors=5, likelihoods="gaussian")
ent.set_train_options(iter=500, startELBO=1, freqELBO=1, seed=2024)
# 训练
ent.build()
ent.run()
# 输出模型信息
print("训练完成，模型已保存至", ent.model.datafile)这段代码跑完后，会输出一个包含因子结果的对象。如果你在本机看到类似 "Converged at iteration 347" 这样的收敛信息，那就说明环境完全可用。
一个小技巧：如果你的机器配置不高，把 iter 设小一点（比如 200），收敛门槛设松一点，也能快速验证环境是否正确。我经常在笔记本上这么干——先确认环境可用，再去服务器上跑全量。
常见问题与避坑
- ImportError: No module named 'numpy.core._multiarray_umath' —— 这是 numpy 版本不兼容的经典表现。我曾经在 Python 3.11 上装了 numpy 1.26，结果 mofapy2 编译报错。降回 1.24 就好了。
- Compilation error: 'Python.h' not found —— 你的系统缺少 Python 开发头文件。在 Ubuntu 上装
python3-dev，在 macOS 上装xcode-select --install。 - RuntimeWarning: scipy.linalg._solve_toeplitz —— 这是 scipy 版本过新导致的废弃警告。降 scipy 到 1.10.x 就安静了。
- 训练无限循环不收敛 —— 检查你的数据是否有 NaN 或无穷值。我遇到过好几次，数据预处理没做干净，MOFA 直接卡死。
警告：不要在 Jupyter Notebook 内核里反复安装和卸载 mofapy2。某些 C 扩展会留下缓存，导致奇怪的行为。要清缓存，就把 _mofa 文件夹手动删掉（一般在 site-packages/mofapy2 下）。我犯过这种蠢事——查了两天才发现是缓存污染。
本章知识结构
整个环境搭建的流程，我画了一张结构图，方便你对照查漏补缺。
图里从“开始环境搭建”到“验证 → 测试运行”，总共 5 个关键步骤，每一步都有明确的执行动作。中间我加了一些常见问题和避坑提示——说白了很多问题都出在第一步（Python 版本）和第三步（numpy 安装顺序）上。你把这两个卡住点搞定，剩下的基本半自动成功。