十大至簡規則，用Jupyter Notebook寫程式碼應該這樣來

（點選上方快速關註並設定為星標，一起學Python）

來自：機器之心    作者：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 essay-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，讓他們知道你是否遇到了障礙。

將可復現性作為研究小組所有計算工作的關鍵要素，而不是在分析完成後才執行，或被期刊或評審人員要求後才思考。