選自arXiv
作者：Adam Rule、Amanda Birmingham等
機器之心編譯
參與：韓放、路
你真的是 Jupyter Notebook 高手嗎，真的能將代碼和文檔打造成鐵桶一般的整體嗎？
Jupyter Notebook 是一個非常常用的代碼編輯器，它非常適合做數據分析與代碼展示，很多雲服務也採用它作為代碼編輯器。此外，因為用這種編輯器看代碼比較輕鬆，文檔描述和輸出效果也能進一步幫助理解，很多研究者都會採用 Jupyter 作為解釋研究實現的工具。
如果 Jupyter Notebook 寫的好，那麼研究實現及復現就更優美，如果再放到 Colab 等具有免費算力的工具上，那就比較完美了。
在機器之心之前介紹過的文章中，我們關注 Jupyter Notebook 的炫酷插件與主題風格，更強調工具本身的使用姿態。而一篇發在 arXiv 上的文章介紹了什麼是展示實現代碼的十大簡單規則，我該又該如何利用它們構建 Jupyter 項目。這對於研究者和希望展示項目實現的開發者而言非常重要，我們可以像說故事一樣介紹我們的實現。
論文連結：https://arxiv.org/pdf/1810.08055.pdf
下面，我們就以展示可復現性研究成果為目標，看看 Jupyter 要怎樣寫才比較合理。
Jupyter Notebook 與研究的可復現性
可復現性（Reproducibility）需要提供研究所用數據、軟體、依賴項和計算環境（如硬體或雲配置）的人類可讀和機器可讀的描述，以及介紹如何組合以上所有部分的文檔。
之前分析人員通常將這些信息保存在單獨的數據、分析、結果、配置和注釋文件中（這些文件通常很難組合和共享），不過他們越來越多地使用計算型 notebook（如 Jupyter Notebooks 和 R Notebooks），在單個交互式和可移植文檔中組合可執行代碼、渲染可視化效果和描述性文本。
Jupyter Notebooks 大大降低了可復現性的困難，它使科學家能夠輕鬆地編寫混合了代碼、結果和文本的共享計算敘述，從而支持可復現性研究。然而，像 Jupyter Notebook 這樣的計算型 notebook 並沒有解決實現可復現性的所有障礙，而且它們還引入了另一些獨特的挑戰，其中部分挑戰源於它們的交互性。
考慮到在 Jupyter Notebooks 上發布可復現研究的技術和社會障礙，來自加州大學聖地牙哥分校和伯克利分校的研究者編制了一套規則、提示、工具和示例 notebook。這套規則專注於 Jupyter Notebooks，不過也適用於其他混合了實時代碼和敘述性描述的文檔。
下圖 1 展示了在 notebook 開發周期不同階段所應用的規則。
圖 1：將十個簡單規則應用於創建 Jupyter Notebooks 的工作流。從上到下，該圖描述了開發一個記錄詳盡、功能良好、用於可復現性研究的 Jupyter Notebooks 所需的三個不同的階段。
規則 1：為觀眾講故事
使用 Jupyter Notebooks 的一個主要好處是，它能將解釋性文本與代碼和結果交織在一起，創建計算性敘述 [8]。不要只保留零星的筆記，而是用解釋性文字講述一個引人入勝的故事，故事的開頭介紹主題，中間介紹步驟，結尾解釋結果。不僅要描述你做了什麼，還要描述為什麼要這樣做、這些步驟是如何連接的，以及它們意味著什麼。
如何講述這個故事將取決於你的觀眾。你打算和實驗室的非技術同事、另一個實驗室的分析師、某一期刊的讀者還是公眾分享你的 notebook？你可能需要為每一類觀眾提供不同種類和級別的解釋。
規則 2：記錄過程，而不僅僅是結果
計算型 notebook 的交互特性使得嘗試和對比不同方法或參數更加快速和容易，以至於我們在執行這些交互式調研時往往無法將其記錄下來。因此，這個建議變得更加重要：確保記錄下所有的探索，甚至那些導致進入死胡同的探索！這些將幫助你記住做了什麼和為什麼做。
許多 notebook 用戶等到分析結束、得到了可靠結果後，才添加這樣的解釋性文字。不要等，到那時你可能已經忘記了為什麼選擇某個特定參數值、從哪裡複製了一段代碼，或者中間結果的有趣之處是什麼。如果你沒有時間全面記錄你此刻正在做什麼或在想什麼，那麼留下簡短的描述性筆記來提醒自己，在可以停下時抓緊把這些內容添加上。
規則 3：添加分割，使步驟更清晰
notebook 是一個交互式的環境，所以它很容易編寫和運行單行單元格。這有利於實驗，但會讓 notebook 凌亂不堪，充滿難以理解的短小片段。那麼，嘗試讓 notebook 中的每個單元格執行一個有意義的分析步驟，並且該步驟可以根據單元格中的代碼或周圍的 markdown 描述很容易地理解。
按單元格模塊化代碼，並在單元格上方用 markdown 標記。將每個單元格想像為一個段落、擁有一個函數或完成一個任務（例如，創建一個繪圖）。避免長單元格（任何超過 100 行或一頁的內容都太長了）。在代碼注釋中放入低級文檔。使用描述性的 markdown header 將 notebook 分區，使其可以輕鬆導航和添加目錄。將長 notebook 拆分為一系列 notebook，並保留一個 top-level index notebook，其中包含指向各個 notebook 的連結。
規則 4：模塊化代碼
避免重複代碼總是很好的做法，但是在 notebook 中，複製一個單元格、調整幾行、將生成的代碼粘貼到新單元格或其他 notebook 中並再次運行是特別容易的。這種試驗形式很方便，但如果你想更改複製的代碼的功能或修復其中的 bug，就會使 notebook 難以閱讀，並且幾乎不可能進行維護。因此你可以將要複製和重用的代碼包裝在一個函數中，這樣就可以根據需要從任意多個單元格中調用該函數。如果你要在其他項目或 notebook 中重用代碼，請考慮將其轉換為模塊、包或庫，並遵循良好的軟體開發實踐（如單元測試）。
模塊化不僅節省空間，支持維護，調試方便，還使增加交互性變得更加簡單。
規則 5：記錄依賴項
未來重新生成分析時，不僅需要訪問代碼，還需要訪問依賴項。計算科學的最佳實踐是，從一開始就使用諸如 conda 的 environment.yml 或 pip 的 requirements.txt 之類的工具明確地管理依賴項，以列出所有相關的依賴項（包括它們的軟體版本）。始終在這些依賴項創建的環境中工作，以確保不添加未記錄的依賴項。
在 notebook 中，你可以使用 notebook 的擴展（如 watermark）顯式列印依賴項。列出 notebook 中關鍵依賴項的版本（最好列在最下方），如果 notebook 與環境隔離使用，那麼這將保證 notebook 中仍然包含關鍵信息，從而幫助讀者複製結果。
規則 6：使用版本控制
版本控制是 notebook 使用的一個重要輔助工具，因為 notebook 的交互特性使其很容易意外地更改或刪除重要內容。此外，由於 notebook 中包含代碼，代碼不可避免會有 bug，因此確定 bug 引入與修復的時間（及其可能影響的分析）是科學計算中的一項關鍵能力。
但是，請注意，Jupyter Notebook 將每個單元格的代碼和特定且廣泛的元數據存儲為 JSON 格式的文本文件。版本控制系統比較這些 JSON 文件中的差異，而不是用戶友好型 notebook GUI（圖形用戶界面）中的差異。
規則 7：構建 pipeline
記錄初步探索性研究的 notebook 很少能被廣泛推廣，但一旦確定了某種穩定的分析方法，設計良好的 notebook 就可以通過 pipeline 推廣到其他任務中，從而使用不同的輸入數據和參數很容易地重複分析。記住這一點，從一開始就設計你的 notebook，以允許將來重新調整用途。把關鍵變量聲明（尤其是在進行新的分析時會改變的變量）放在 notebook 的頂部，而不是埋在中間的某個地方。直接在 notebook 中執行準備步驟，如數據清理，並儘可能避免手動幹預。
規則 8：分享和解釋數據
如果底層數據被鎖定，那麼訪問清晰注釋的 notebook 對可復現性也幾乎沒有用處。努力使你的數據或數據樣本與 notebook 一起公開。notebook 可以很容易地提供輸入數據和上遊處理步驟的描述，這對於解釋結果至關重要。
理想情況下，你可以在 notebook 中共享整個數據集。我們認識到許多數據集太大或太敏感，無法以這種方式共享。在這些情況下，考慮將大型和複雜的數據集分解為多個層次，這樣即使原始數據太大，無法與已發布的 notebook 一起共享，或者受到隱私或其他訪問問題的限制，也不會影響到可復現性。
規則 9：允許閱讀、運行和探索 notebook
如果你遵循了前面的規則，那麼你的 notebook 應該能夠捕獲整個過程並易於閱讀。但是其他人如何訪問、運行和探索它們呢？你可以通過多種方式支持他人重用你的 notebook。首先，將 notebook 存儲到一個具備清晰 README 文件的公共代碼庫中。
除了允許重用之外，你還要考慮如何利用 notebook 的獨特結構來支持閱讀和探索。至少，將所有 notebook 的靜態 HTML/PDF 版本存儲在出版物附帶代碼庫的最終版本中。
規則 10：促進可復現和開放的研究
顯然，僅使用計算型 notebook 並不能保證研究的可復現。如果 notebook 的便利性和交互性讓你滿意，那你可以採取下一步行動，在實驗室或工作場所宣傳其可復現性。讓實驗室的同事試著運行你的 notebook，然後聽他們解釋在什麼地方出了問題。也試著運行他們的 notebook，讓他們知道你是否遇到了障礙。
將可復現性作為研究小組所有計算工作的關鍵要素，而不是在分析完成後才執行，或被期刊或評審人員要求後才思考。