跳到主要内容

Jupyter 与交互式分析环境

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

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

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

Notebook 是什么、不是什么​

适合 Notebook 做的事​

  • 记录分析思路（每跑一段代码补一段 Markdown 解释）
  • 逐步运行代码并立刻看结果
  • 快速查看表格 / 图
  • 解释参数选择的理由
  • 分享小型分析示例 / 教学

不适合 Notebook 做的事​

  • 长时间无人值守的大流程（Cell Ranger / STAR 这种小时级任务）
  • 大规模批处理（一次跑 100 个样本）
  • 不能版本控制的正式生产流程
  • 敏感数据输出（Notebook 默认会把输出嵌到文件里，临床数据进 git 就尴尬了）

核心判断：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 跑一下深度学习。

不适合：

  • 长期保存重要环境（会话经常断）
  • 处理隐私 / 临床数据（数据上传 Google）
  • 安装量大的依赖（每次启动都要重装）

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。

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

  • 同一段代码改了 3 次以上 → 抽到函数，放进 scripts/utils.R
  • 这段分析要给同事跑 / 给老板跑 / 自动化重复跑 → 整理成命令行脚本
  • 步骤太长、Notebook 滚不到底 → 拆成多个 Notebook，或拆成脚本
  • 包含敏感数据 → 立刻搬出 Notebook（输出会被保存到 .ipynb 里）

推荐结构：

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

常见坑​

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

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

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

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

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

避免：

  • 提交前清空输出（Cell → All Output → Clear）
  • 或装 nbstripout 自动在 commit 时剥掉输出
  • 或改用 .py + Jupytext，把 Notebook 双向同步成纯 Python

坑 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 还是脚本看自己习惯

横向延伸：

参考资源​

AI 组学实践

让 AI 带我实战这一篇

AI 会读这篇文章后给你 3-5 步学习计划， 逐步带你学完，最后出 1-3 道题验证你掌握得怎么样。 登录后 AI 才能记住你的进度。

静态文件

离线资料下载

手册 HTML / PDF 已在后台预生成，点击后直接下载网站静态资源。

本篇 HTML本篇 PDF手册 HTML手册 PDF说明