jupyter-notebooks

相关技能

当笔记本结果支持某项建议、共同主张或决策时，请使用 $validate-data。

Jupyter Notebooks

创建整洁、可复现的 Jupyter 笔记本，使其易于浏览、重新运行和交接。将笔记本视为面向读者的分析成果，而不是随手记录的草稿。只有在笔记本从头到尾成功执行，或明确说明执行受阻之处并给出复现所需的准确验证步骤后，笔记本工作才算完成。

工作流

1. 锁定笔记本模式和范围。

   确定笔记本是分析报告、实验日志、诊断笔记本、数据质量检查、市场规模测算、模型探索、教程，还是报告的配套材料。明确读者、决策、预期交接内容、所需输入，以及任务要求新建笔记本还是针对现有笔记本进行定向编辑。

2. 使用适合笔记本的工具进行检查或搭建框架。

   优先使用 JupyterLab、nbformat、nbclient 或现有的脚手架工具，而不是直接编辑原始 JSON。编辑现有笔记本时，应保留其原有意图，并尽量减少 JSON 改动。除非能明显改善从上到下的叙述逻辑，否则不要调整单元格顺序。如果不得不编辑原始 JSON，请在完成前验证笔记本结构。

3. 根据所选模式组织笔记本。

   对于分析类笔记本，默认采用以下结构：

   1. ## tl;dr
   2. ## Context & Methods
   3. ## Data
   4. ## Results
   5. ## Takeaways

   查看执行输出后再撰写 tl;dr 和要点。使用具体的观测值、明显模式、行或图表，而不是假设。当假设会影响正确性时，在 Context & Methods 中加入 ### Key Assumptions 小节。

   对于教程或演练，将同样的原则调整为教学流程：

   1. ## Goal
   2. ## Setup
   3. ## Steps
   4. ## Checks
   5. ## Next Steps

4. 梳理清晰的数据与计算流程。

   将设置、导入、参数、数据加载、数据准备、计算、可视化和解读分开。如果笔记本同时使用 SQL 和 Python，除非有明确理由，否则应将复杂 SQL 放在 SQL 单元格或单独的查询文件中，而不是嵌入大型 Python 字符串。使用描述性变量名，并确保每个代码单元格专注于一个步骤。

5. 有意识地选择数据源。

   笔记本需要表格数据时，先使用 ~~structured_data 确认表的选择、架构、分区筛选条件、样本行和查询提交策略。有相关连接器时，使用对应的数据源连接器；必要时再改用导出文件或粘贴的 SQL。需要检查数据新鲜度或血缘关系时，使用 ~~operations_logs。对于支持分析的任何已执行结果，都应在笔记本上下文中记录查询永久链接、请求 ID、源路径、仪表板链接、提取名称或其他源材料。重型查询应设置筛选条件和范围限制，避免将笔记本变成对实时数据源的大范围扫描。

6. 确保单元格清晰且内容有界。

   在大多数代码单元格前添加简洁的 Markdown 标题。标题应简短且以行动为导向，例如 ### 1. Load Data、### 2. Validate Inputs 或 ### 3. Plot Results。优先使用多个简短单元格，而不是一个混合多种用途的大单元格。文字说明应简短：解释目的、假设和预期结果，而非逐行讲解代码。多个表格或图表应拆分到不同单元格中，不要将所有输出都堆在一个单元格里。

7. 撰写结论前验证结果。

   检查关键数字、图表和要点是否与执行输出一致。限制原始调试输出、过大的表格和嘈杂的日志。如果结果出人意料，应先进行局部合理性检查、查看少量样本，或与可信数据源核对，再将其纳入摘要。

8. 执行笔记本并记录验证状态。

   环境允许时，从上到下运行笔记本：

   python -m jupyter nbconvert --execute --to notebook --inplace path/to/notebook.ipynb
   

   必要时进行可选的本地设置：

   uv pip install jupyterlab nbformat nbclient ipykernel
   

   如果无法执行，请明确说明，并提供在本地验证所需的准确命令、缺失依赖项、凭据、数据访问权限、内核或环境步骤。

标准

笔记本结构

• 确保读者在开始乱序执行单元格之前，按从上到下的顺序阅读时能清楚理解内容。
• 将执行摘要内容放在顶部，但应在检查已执行的结果后再撰写。
• 确保笔记本各部分与笔记本模式一致：分析、实验、诊断、教程或交接材料。
• 确保各部分标题、图表标题、标签和文件名足够清晰，便于交接。
• 重构时保留现有笔记本的意图；默认应改进结构，而不是彻底重写。

可复现性

• 将参数、日期范围、筛选条件、群组、假设和来源引用放在笔记本顶部附近，清晰可见。
• 记录足够的来源上下文，让其他读者能够追溯分析：查询永久链接、请求 ID、表名、来源路径、电子表格工作表、仪表板链接、提取版本或输入文件位置。
• 尽可能确保计算具有确定性。避免隐藏状态、手动编辑的中间值、乱序依赖和未说明的缓存输出。
• 如果笔记本依赖非标准软件包、内核、凭据或本地文件，优先使用明确的环境设置单元格或说明。
• 如果任务要求提供可运行的产物，则执行笔记本。对于运行成功的情况，最终回复中无需单独添加常规验证部分；如果存在执行缺口、部分执行或未运行的笔记本，则应说明原因，因为这些因素会影响用户对产物的信任。

代码与数据规范

• 将数据准备与呈现分开。
• 让复杂 SQL 易于阅读，并用一行注释说明其目标。
• 数据准备完成后，再使用 Python 进行绘图和轻量级数据整理。
• 使用描述性变量名，在面向读者的笔记本中避免使用缩写临时名称。
• 控制输出规模。优先使用小型预览表、抽样行、明确的限制条件和重点图表，而不是原始数据转储。
• 避免扫描范围过大的实时数据源。根据需要按分区、群组或时间范围筛选查询。

分析质量

• 明确说明会影响结果解读的假设。
• 通过已执行输出中的具体数字、行、图表或可见模式来支撑结论。
• 不要将未经执行或验证的计算结果写入 tl;dr。
• 标注注意事项、未完成的检查、缺少的来源访问权限和已知的验证缺口。
• 对意外结果、影响重大的主张或面向利益相关方的结论进行合理性检查。

验证清单

• 笔记本模式所要求的章节顺序已就位。
• 笔记本运行时没有错误，或已明确说明执行失败。
• 预期位置存在输出，且内容没有被原始调试信息占据。
• tl;dr、结果和结论与已执行单元格一致。
• 来源引用以及查询或产物链接均予以保留。
• 表格和图表均有标签、规模受控且易于解读。
• 最终回复包含笔记本路径和验证状态。