BioF3 组学数据分析

Jupyter 与交互式分析环境

导出日期：2026年6月27日

Jupyter 与交互式分析环境

组学分析的第一个工程问题是：在哪里写下可以重复运行的分析过程？

Jupyter Notebook 是最常见的答案。它把代码、说明、图表和运行结果放在一份文档里，适合探索性分析和教学演示。

但 Notebook 不是万能的。这一篇把它的用法和边界都说清楚 — 哪些事 Notebook 该做、哪些事必须用脚本。

Notebook 是什么、不是什么

适合 Notebook 做的事

不适合 Notebook 做的事

核心判断：Notebook 是"探索 + 记录"载体，不是"执行 + 部署"载体。稳定下来的步骤应该整理到 .R / .py 脚本里。

四种常见环境

1. Jupyter Notebook（经典界面）

适合初学者起步。文件 .ipynb，内部保存代码单元、Markdown 文本、输出结果。

pip install notebook
jupyter notebook

2. JupyterLab（推荐）

更完整的工作界面：Notebook + 终端 + 文本编辑器 + 文件浏览器一体。真实项目里基本都用 JupyterLab。

pip install jupyterlab
jupyter lab

3. Google Colab（云端，临时用）

打开浏览器就能跑 Python。免费用户也能用 GPU。

适合：快速试代码 / 课堂演示 / 共享小型 Notebook / 临时用 GPU 跑一下深度学习。

不适合：

4. 服务器 Notebook（真实项目首选）

数据在服务器上时，把 JupyterLab 起在服务器，浏览器通过 SSH 端口转发访问。

服务器端：

ssh aliyun
cd /path/to/project
conda activate sc-env
jupyter lab --no-browser --port 8888

本地终端：

ssh -L 8888:localhost:8888 aliyun
# 然后浏览器打开 http://localhost:8888

注意权限、数据路径、端口安全（不要把 8888 直接暴露公网）。

在 R 里也能用 Notebook

.ipynb 不只是 Python 的。装一个 IRkernel，就能在 Jupyter 里跑 R。

install.packages("IRkernel")
IRkernel::installspec()

之后启动 JupyterLab，新建 Notebook 时能选 R 内核。Seurat / DESeq2 / ggplot2 都能直接在里面跑，输出图也能内嵌。

备选：很多 R 用户直接用 RStudio + R Markdown / Quarto，效果跟 Notebook 类似。单纯做 R 分析不一定非要 Jupyter。Jupyter 的优势在 Python 重，或者多语言混合的项目。

Notebook 的基本结构

每个 Notebook 由一组**单元（cell）**组成，主要两种：

Markdown 单元 — 写说明

## 质量控制

本步骤过滤低质量细胞：

- `nFeature_RNA < 200`：基因数太少的可能是空 droplet
- `percent.mt > 20`：线粒体比例高的可能是死细胞或破损

Code 单元 — 跑代码

import pandas as pd

metadata = pd.read_csv("data/metadata.csv")
metadata.head()

输出（表 / 图 / 错误信息）会显示在单元下方，并保存进 .ipynb 文件。

把环境记下来

每个 Notebook 跑完都建议在最后加一个版本记录单元：

Python：

import sys, pandas as pd, numpy as np
print(sys.version)
print(pd.__version__, np.__version__)

R：

sessionInfo()

这一段救过无数"半年前的我跑得动，现在跑不出来"的事故。

从 Notebook 走向脚本

Notebook 的价值不是"把所有分析塞在一个文件里"。稳定下来的部分应该走出 Notebook。

判断"该不该走"的几条原则：

推荐结构：

project/
├── notebooks/        # 探索性 + 教学 Notebook
├── scripts/          # 稳定可复现脚本
├── data/
└── results/

常见坑

坑 1：Notebook 里的代码跑顺序乱了

Notebook 允许任意顺序运行单元，变量状态不一定跟你看到的顺序一致。新手常常跑出"看着都跑过但结果不对"的玄学情况。

避免：定期点 "Restart Kernel & Run All"，确保从头到尾顺次跑下来还是同样结果。这是 Notebook 可复现性的核心保证。

坑 2：把 .ipynb 提交进 git，diff 一片乱码

.ipynb 是 JSON 格式，包含 base64 编码的图片输出。每次重跑都生成不同 metadata，git diff 完全不可读。

避免：

坑 3：把临床数据载进 Notebook，输出嵌进文件，提交 git

直接违规。患者数据原文进了 Notebook 输出，再随手 git push，敏感信息泄漏到公开仓库。

避免：临床 / 未脱敏数据永远不在 Notebook 里直接展示原文。脱敏到样例数据，分析跑在样例上；真实数据只在合规环境处理，输出不嵌进 .ipynb。

坑 4：依赖 Notebook 里 !pip install，环境没固定

调试时图省事，在 Notebook 里 !pip install scanpy 装包。当时能跑，几个月后版本不一致跑不出。

避免：用项目级环境（environment.yml / requirements.txt / renv.lock），Notebook 只 import，不在里面装包。

坑 5：Notebook 越写越长，最后跑一次要 30 分钟

探索性分析很容易越写越长，跑一次几十分钟，每改一处都要全跑。

避免：定期把"这一段已经稳了"的部分搬到 scripts/，Notebook 只保留当前在调的部分。或者把中间产物 pickle / saveRDS 存到磁盘，下次直接加载。

下一步

接着深入：

  1. 数据与环境准备 — 在 Notebook 里 import seurat 之前，先把环境搭好
  2. R 数据整理与 ggplot2 可视化 — Notebook 里画图的能力直接决定它有多好用
  3. 单细胞实践 01 — 第一个完整可跑的真实流程，是 Notebook 还是脚本看自己习惯

横向延伸：

参考资源