working-in-notebooks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Working in Notebooks

在 Notebook 中工作

Use this skill to create, maintain, and choose between notebook environments (Jupyter, marimo, Colab) for data work. Covers tool selection, reproducibility patterns, and workflow best practices.

使用此 skill 创建、维护 notebook，并在不同 notebook 环境（Jupyter、marimo、Colab）之间进行选择。内容涵盖工具选型、可复现性模式和工作流最佳实践。

When to use this skill

何时使用此 skill

Setting up a notebook environment — choosing between Jupyter, marimo, VS Code, or Colab
Converting between notebook formats — Jupyter to marimo, .ipynb to .py, or vice versa
Making notebooks reproducible — pinning dependencies, managing random seeds, avoiding hardcoded paths
Improving notebook structure — organizing cells, refactoring code, adding tests
Publishing or sharing notebooks — nbconvert, Quarto, Voilà, or Git workflows
Jupyter-specific features — magic commands, widgets, extensions, kernel management
Marimo-specific workflows — reactive execution, UI components, version control patterns

搭建 notebook 环境 — 在 Jupyter、marimo、VS Code 或 Colab 之间选择
转换 notebook 格式 — 将 Jupyter 转换为 marimo、将 .ipynb 转换为 .py，或反向转换
让 notebook 具备可复现性 — 固定依赖版本、管理随机种子、避免硬编码路径
改进 notebook 结构 — 组织 cells、重构代码、添加测试
发布或共享 notebook — 使用 nbconvert、Quarto、Voilà 或 Git 工作流
Jupyter 专属功能 — magic commands、widgets、extensions、kernel 管理
marimo 专属工作流 — reactive execution、UI components、版本控制模式

When NOT to use this skill

何时不应使用此 skill

Use a different skill for these related but distinct tasks:

Instead of...	Use this skill	Because...
Building a stakeholder-facing dashboard	`building-data-apps`	Apps are for external users; notebooks are for analysts/developers
Creating interactive data explorers for non-technical users	`building-data-apps`	Streamlit, Panel, Gradio are purpose-built for this
Exploratory data analysis patterns	`analyzing-data`	EDA patterns (profiling, statistical tests) belong there
Visualization library selection	`analyzing-data`	Chart types and library comparison is covered there
Production ML feature engineering	`engineering-ml-features`	Feature engineering logic is domain-specific
Model evaluation and cross-validation	`evaluating-ml-models`	Model comparison and metrics belong there

对于以下相关但不同的任务，应使用其他 skill：

不应使用本 skill 的场景	应改用此 skill	原因
构建面向利益相关者的 dashboard	`building-data-apps`	Data app 面向外部用户；notebook 面向分析师/开发者
为非技术用户创建交互式 data explorer	`building-data-apps`	Streamlit、Panel、Gradio 是专门为这类场景设计的
探索性数据分析模式	`analyzing-data`	EDA 模式（profiling、statistical tests）属于该 skill
可视化库选型	`analyzing-data`	图表类型和库对比在该 skill 中介绍
生产环境中的 ML feature engineering	`engineering-ml-features`	Feature engineering 逻辑具有领域特异性
模型评估和交叉验证	`evaluating-ml-models`	模型对比和 metrics 属于该 skill

Quick boundary check

快速边界判断

Notebook = code + markdown + outputs in cells, run interactively, often .ipynb or .py format
Data app = deployed web interface with widgets, for non-coders to interact with
If the user asks for a "dashboard," "app," or mentions "users clicking buttons," use
```
building-data-apps
```
If the user asks for "notebook," "Jupyter," "marimo," or "explore data interactively," use this skill

Notebook = 将 code、markdown 和 outputs 放在 cells 中交互式运行，通常采用 .ipynb 或 .py 格式
Data app = 部署带有 widgets 的 web interface，供非技术用户交互
如果用户要求“dashboard”、“app”，或提到“用户点击按钮”，请使用
```
building-data-apps
```
如果用户要求“notebook”、“Jupyter”、“marimo”，或提到“交互式探索数据”，请使用此 skill

Tool selection guide

工具选型指南

Quick decision checklist

快速决策清单

Question	If yes, consider
Need reactive execution (cells auto-update)?	marimo
Want pure Python files for version control?	marimo
Need specific Jupyter extensions ecosystem?	JupyterLab
Using Google Colab features (TPU, shared GPUs)?	Google Colab
Want IDE-native experience (IntelliSense, debugger)?	VS Code + Jupyter
Converting from existing .ipynb files?	Jupyter → marimo with `marimo convert`
Teaching beginners (familiarity matters)?	JupyterLab or Colab

问题	如果是，可考虑
需要 reactive execution（cells 自动更新）？	marimo
希望使用纯 Python 文件进行版本控制？	marimo
需要特定的 Jupyter extensions 生态？	JupyterLab
使用 Google Colab 功能（TPU、共享 GPU）？	Google Colab
希望获得 IDE 原生体验（IntelliSense、debugger）？	VS Code + Jupyter
从现有 .ipynb 文件转换？	使用 `marimo convert` 将 Jupyter 转换为 marimo
教授初学者（熟悉度很重要）？	JupyterLab 或 Colab

Tool comparison

工具对比

Tool	Best For	Key Feature	File Format
JupyterLab	Traditional data science, rich extensions	Full IDE experience, 1000+ extensions	`.ipynb` (JSON)
marimo	Reproducible notebooks, reactive execution	Python-native, version-control friendly	`.py` (pure Python)
VS Code + Jupyter	IDE-native notebook experience	IntelliSense, debugging, git integration	`.ipynb`
Google Colab	Cloud GPUs, easy sharing, collaboration	Free TPU/GPU, zero setup	`.ipynb` (cloud)

工具	最适合	核心功能	文件格式
JupyterLab	传统数据科学、丰富的 extensions	完整 IDE 体验，1000+ extensions	`.ipynb` （JSON）
marimo	可复现 notebook、reactive execution	Python 原生，适合版本控制	`.py` （纯 Python）
VS Code + Jupyter	IDE 原生的 notebook 体验	IntelliSense、debugging、Git 集成	`.ipynb`
Google Colab	云端 GPU、便捷共享与协作	免费 TPU/GPU，无需配置	`.ipynb` （云端）

Core workflow: Creating a reproducible notebook

核心工作流：创建可复现的 Notebook

Step 1: Choose your tool

第 1 步：选择工具

See decision checklist above. If starting fresh and reproducibility matters → marimo. If ecosystem/extensions matter → JupyterLab.

请参阅上面的决策清单。如果是从零开始且可复现性很重要，选择 marimo；如果 extensions/生态系统很重要，选择 JupyterLab。

Step 2: Set up the environment

第 2 步：搭建环境

python

undefined

python

undefined

Cell 1: Environment setup (run first)

Set random seeds for reproducibility

import numpy as np import random

np.random.seed(42) random.seed(42)

import numpy as np import random

np.random.seed(42) random.seed(42)

For torch users:

import torch

torch.manual_seed(42)

undefined

undefined

Step 3: Pin dependencies

第 3 步：固定依赖版本

Create

requirements.txt

environment.yml

text

undefined

创建

requirements.txt

或

environment.yml

：

text

undefined

requirements.txt

pandas==2.1.0 numpy==1.24.0 matplotlib==3.7.0


Or use modern tools:

```bash

pandas==2.1.0 numpy==1.24.0 matplotlib==3.7.0


或者使用现代工具：

```bash

With uv

uv pip freeze > requirements.txt

With poetry

poetry export -f requirements.txt > requirements.txt

undefined

poetry export -f requirements.txt > requirements.txt

undefined

Step 4: Structure for readability

第 4 步：为了可读性组织结构

markdown

undefined

markdown

undefined

Title: Clear project/question description

Setup

Imports and configuration

Data Loading

Load and validate data

Analysis

Subsection per question/hypothesis
Clear markdown explanations
Visualizations with interpretations

Subsection per question/hypothesis
Clear markdown explanations
Visualizations with interpretations

Conclusions

Key findings and next steps

undefined

Key findings and next steps

undefined

Step 5: Never hardcode secrets

第 5 步：绝不硬编码 secrets

python

undefined

python

undefined

✅ Use environment variables

import os

api_key = os.environ.get("OPENAI_API_KEY")

import os

api_key = os.environ.get("OPENAI_API_KEY")

❌ Never do this

api_key = "sk-abc123..."

undefined

api_key = "sk-abc123..."

undefined

Step 6: Clean outputs before git (Jupyter)

第 6 步：提交到 Git 前清理输出（Jupyter）

bash

undefined

bash

undefined

Install nbstripout

pip install nbstripout nbstripout --install

Or use pre-commit

pip install pre-commit pre-commit install

undefined

pip install pre-commit pre-commit install

undefined

Validation and feedback loop

验证与反馈循环

Self-check questions

自检问题

Before considering a notebook "done":

Can someone else run this from a fresh environment?
Are all random seeds set?
Are dependencies pinned (requirements.txt or similar)?
Are secrets loaded from environment variables?
Are cells organized logically (not execution-order dependent)?
Are helper functions extracted to
```
.py
```
files if >30 lines?
Are outputs stripped before committing (if using Jupyter)?

在将 notebook 视为“完成”之前：

其他人能否在全新环境中运行它？
是否设置了所有随机种子？
是否固定了依赖版本（requirements.txt 或类似文件）？
是否从环境变量加载 secrets？
cells 是否按逻辑组织（而非依赖执行顺序）？
如果 helper functions 超过 30 行，是否已提取到
```
.py
```
文件？
如果使用 Jupyter，是否已在提交前清除输出？

Testing notebook code

测试 Notebook 代码

See

../analyzing-data/references/notebook-testing.md

for:

Unit tests for notebook code
nbval for output validation
Papermill for parameterized execution

有关以下内容，请参阅

../analyzing-data/references/notebook-testing.md

：

notebook 代码的单元测试
使用 nbval 进行输出验证
使用 Papermill 进行参数化执行

Progressive disclosure

渐进式披露

Core references

核心参考

```
references/jupyter-guide.md
```
— Jupyter/JupyterLab deep dive: magic commands, widgets, extensions, kernel management
```
references/marimo-guide.md
```
— marimo deep dive: reactive execution, UI components, migration from Jupyter
```
references/reproducibility-patterns.md
```
— Environment management, dependency pinning, nbstripout, secrets handling

```
references/jupyter-guide.md
```
— Jupyter/JupyterLab 深入介绍：magic commands、widgets、extensions、kernel 管理
```
references/marimo-guide.md
```
— marimo 深入介绍：reactive execution、UI components、从 Jupyter 迁移
```
references/reproducibility-patterns.md
```
— 环境管理、依赖版本固定、nbstripout、secrets 处理

Related references (in other skills)

External resources

外部资源

Common anti-patterns

常见反模式

❌ Running cells out of order (Jupyter) → Use "Run All" to verify, or switch to marimo
❌ Giant cells with mixed concerns → One concept per cell, <50 lines
❌ Hardcoded file paths → Use relative paths or environment variables
❌ Hardcoded secrets → Load from environment
❌ Committing large output files → Use .gitignore, data/ folder, or strip outputs
❌ Inline data → Use data/ folder or external sources
❌ No markdown explanations → Every code block deserves context

❌ 乱序运行 cells（Jupyter）→ 使用“Run All”进行验证，或切换到 marimo
❌ 巨型 cell 混合多个关注点 → 每个 cell 只处理一个概念，并控制在 50 行以内
❌ 硬编码文件路径 → 使用相对路径或环境变量
❌ 硬编码 secrets → 从环境加载
❌ 提交大型输出文件 → 使用 .gitignore、data/ 文件夹，或清除输出
❌ 内嵌数据 → 使用 data/ 文件夹或外部数据源
❌ 缺少 markdown 说明 → 每个 code block 都应有上下文说明

Quick commands reference

快速命令参考

Jupyter

bash

undefined

bash

undefined

Start JupyterLab

jupyter lab

Convert notebook

jupyter nbconvert notebook.ipynb --to html jupyter nbconvert notebook.ipynb --to script

List kernels

jupyter kernelspec list

Install kernel for virtual environment

python -m ipykernel install --user --name=myenv

undefined

python -m ipykernel install --user --name=myenv

undefined

marimo

bash

undefined

bash

undefined

Create/edit a notebook

marimo edit notebook.py

Run as app (read-only)

marimo run notebook.py

Convert from Jupyter

marimo convert notebook.ipynb -o notebook.py

Export to HTML

marimo export html notebook.py -o notebook.html

undefined

marimo export html notebook.py -o notebook.html

undefined

Environment validation

环境验证

python

undefined

python

undefined

Check installed versions

import pandas as pd import numpy as np

print(f"pandas: {pd.version}") print(f"numpy: {np.version}")

undefined

import pandas as pd import numpy as np

print(f"pandas: {pd.version}") print(f"numpy: {np.version}")

undefined

Related skills

Skill	Relationship	When to use
`analyzing-data`	Complementary	EDA patterns, profiling, statistical tests—use with notebooks
`building-data-apps`	Distinct boundary	Building stakeholder-facing dashboards—not this skill
`evaluating-ml-models`	Complementary	Cross-validation, metrics, experiment tracking
`engineering-ml-features`	Complementary	Feature engineering patterns and transformations

Skill	关系	何时使用
`analyzing-data`	互补	EDA 模式、profiling、statistical tests——与 notebook 配合使用
`building-data-apps`	边界不同	构建面向利益相关者的 dashboard——不使用此 skill
`evaluating-ml-models`	互补	Cross-validation、metrics、experiment tracking
`engineering-ml-features`	互补	Feature engineering 模式和转换

Migration notes

迁移说明

This skill replaces

data-science-notebooks

with the following changes:

Removed
```
dependsOn
```
from frontmatter (non-standard field)
Added explicit when-to-use and when-not-to-use sections
Split content into focused reference files
Clear boundary documentation vs
```
building-data-apps
```
Progressive disclosure with direct file paths (no
```
@skill
```
hybrid syntax)

此 skill 替代

data-science-notebooks

，并包含以下变更：

从 frontmatter 中移除了
```
dependsOn
```
（非标准字段）
新增了明确的“何时使用”和“何时不应使用”章节
将内容拆分为聚焦的 reference 文件
明确记录了与
```
building-data-apps
```
的边界
采用渐进式披露，并提供直接文件路径（不使用
```
@skill
```
混合语法）

working-in-notebooks

Original

Translation

Working in Notebooks

在 Notebook 中工作

When to use this skill

何时使用此 skill

When NOT to use this skill

何时不应使用此 skill

Quick boundary check

快速边界判断

Tool selection guide

工具选型指南

Quick decision checklist

快速决策清单

Tool comparison

工具对比

Core workflow: Creating a reproducible notebook

核心工作流：创建可复现的 Notebook

Step 1: Choose your tool

第 1 步：选择工具

Step 2: Set up the environment

第 2 步：搭建环境

Cell 1: Environment setup (run first)

Cell 1: Environment setup (run first)

Set random seeds for reproducibility

Set random seeds for reproducibility

For torch users:

For torch users:

import torch

import torch

torch.manual_seed(42)

torch.manual_seed(42)

Step 3: Pin dependencies

第 3 步：固定依赖版本

requirements.txt

requirements.txt

With uv

With uv

With poetry

With poetry

Step 4: Structure for readability

第 4 步：为了可读性组织结构

Title: Clear project/question description

Title: Clear project/question description

Setup

Setup

Data Loading

Data Loading

Analysis

Analysis

Conclusions

Conclusions

Step 5: Never hardcode secrets

第 5 步：绝不硬编码 secrets

✅ Use environment variables

✅ Use environment variables

❌ Never do this

❌ Never do this

Step 6: Clean outputs before git (Jupyter)

第 6 步：提交到 Git 前清理输出（Jupyter）

Install nbstripout

Install nbstripout

Or use pre-commit

Or use pre-commit

Validation and feedback loop

验证与反馈循环

Self-check questions

自检问题

Testing notebook code

测试 Notebook 代码

Progressive disclosure

渐进式披露

Core references

核心参考

Related references (in other skills)

相关参考（位于其他 skill 中）

External resources

外部资源

Common anti-patterns