Jupyter Notebook 最佳实践

断断续续做过几个数据分析方面的项目，使用的是 Python 爱好者耳熟能详的 Jupyter Notebook。一开始把各种 .ipynb 文件、数据源文件都放在同一个项目目录下，看上去特别杂乱无章，整理的时候也是一团乱麻。

后来在谷歌上找到一篇介绍 Jupyter Notebook 最佳实践的文章，受益匪浅。按照书中所提的建议来组织项目，确实要清晰的多了，而且特别适合团队共同完成数据科学项目。

因此摘录其中的关键点分享出来，希望能帮助到正在学习使用 Jupyter 的朋友。

整体思路

将数据科学项目的 notebook 分为两大类：实验版和交付版，分别进行针对性的管理。

实验版 notebook

参考传统实验室中整理笔记的方法，在使用 Jupyter notebook 时，遵循以下几点：

每个 notebook 都要保留分析历史（和日期）记录
每个 notebook 仅用于开发和实验。
每个 notebook 只有一位作者：标注作者的首字母缩写。
notebook 如果太长，可以进行拆分
如果需要，可以按主题区分 notebook。

交付版 notebook：

可交付版的 notebook 则是打磨完善的版本，并且包含有最终的分析输出。这类 notebook 需要由整个团队来进行管理，而不是交给某一个人。

版本控制

多人协作进行数据分析时，建议采用 Pull Request 的方式提交代码。通过 Git 和 Github 可以很好地实现这点。但是在查看 PR 的时候，审查人需要能给清晰地辨别出 .ipynb 文件的变动。

推荐将 .ipynb 文件转化成 .py 文件后，再进行文件差异对比，可以方便地查看代码的变化。

另外，在审查分析代码时，最好能给直接查看输出的变化。因此推荐保存一份 HTML 版的输出文件。

图1：修改前的拟合情况

图2：修改后的拟合情况

Post-save 钩子

可以通过 post-save 的钩子，很方便地完成上节所说的 .ipynb 文件转换成 .py 文件的工作。只需要按照如下代码所示，修改 ipython 的配置文件即可：

〜/ .ipython / profile_nbserver / ipython_notebook_config.py

添加以下代码：

#如果您想自动保存笔记本的.html和.py版本：modified from：https：//github.com/ipython/ipython/issues/8009
import os
from subprocess import check_call

def post_save（model，os_path，contents_manager）：
    “”“用于将笔记本转换为.py脚本的保存后挂钩”“”
    if model ['type']！='notebook'：
        return # only do this for notebooks
    d，fname = os.path.split（os_path）
    check_call（['ipython'，'nbconvert'，' -  to'，'script'，fname]，cwd = d）
    check_call（['ipython'，'nbconvert'，' -  to'，'html'，fname]，cwd = d）

c.FileContentsManager.post_save_hook = post_save

现在，每次保存到笔记本都会更新名称相同的.py和.html文件。在提交和拉取请求中添加这些，您将从这些文件格式中获益。

完整示例

这是正在进行的项目的目录结构，有一些关于命名文件的明确规则。

示例目录结构：

 - develop＃（实验版 notebook）
  + [ISO 8601日期]  -  [DS-作者首字母简称]  -  [2-4字描述] .ipynb
  + 2015-06-28 -jw-initial-data-clean.html
  + 2015-06-28-jw-initial-data-clean.ipynb
  + 2015-06-28-jw-initial-data-clean.py
  + 2015-07-02-jw-coal-productivity-factors.html
  + 2015-07-02-jw-coal-productivity-factors.ipynb
  + 2015-07-02-jw-coal-productivity-factors.py
 - deliver＃（最终分析，代码，演示文稿等）
  +Coal-mine-productivity.ipynb
  +Coal-mine-productivity.html
  + Coal-mine-productivity.py
- figures
  + 2015-07-16-jw-production-vs-hours -working.png
 -  src＃（模块和脚本）
  + init.py
  + load_coal_data.py
  + figures＃（数字和图表）
  + production-vs-number-employees.png
  + production-vs-hours-working.png
 - data（备份 - 与版本控制分开）
  + coal_prod_cleaned.csv