選自arXiv

作者：Adam Rule、Amanda Birmingham等

機(jī)器之心編譯

參與：韓放、路

你真的是 Jupyter Notebook 高手嗎，真的能將代碼和文檔打造成鐵桶一般的整體嗎？

Jupyter Notebook 是一個非常常用的代碼編輯器，它非常適合做數(shù)據(jù)分析與代碼展示，很多云服務(wù)也采用它作為代碼編輯器。此外，因為用這種編輯器看代碼比較輕松，文檔描述和輸出效果也能進(jìn)一步幫助理解，很多研究者都會采用 Jupyter 作為解釋研究實現(xiàn)的工具。

如果 Jupyter Notebook 寫的好，那么研究實現(xiàn)及復(fù)現(xiàn)就更優(yōu)美，如果再放到 Colab 等具有免費(fèi)算力的工具上，那就比較完美了。

在機(jī)器之心之前介紹過的文章中，我們關(guān)注 Jupyter Notebook 的炫酷插件與主題風(fēng)格，更強(qiáng)調(diào)工具本身的使用姿態(tài)。而一篇發(fā)在 arXiv 上的文章介紹了什么是展示實現(xiàn)代碼的十大簡單規(guī)則，我該又該如何利用它們構(gòu)建 Jupyter 項目。這對于研究者和希望展示項目實現(xiàn)的開發(fā)者而言非常重要，我們可以像說故事一樣介紹我們的實現(xiàn)。

論文鏈接：https://arxiv.org/pdf/1810.08055.pdf

下面，我們就以展示可復(fù)現(xiàn)性研究成果為目標(biāo)，看看 Jupyter 要怎樣寫才比較合理。

Jupyter Notebook 與研究的可復(fù)現(xiàn)性

可復(fù)現(xiàn)性（Reproducibility）需要提供研究所用數(shù)據(jù)、軟件、依賴項和計算環(huán)境（如硬件或云配置）的人類可讀和機(jī)器可讀的描述，以及介紹如何組合以上所有部分的文檔。

之前分析人員通常將這些信息保存在單獨(dú)的數(shù)據(jù)、分析、結(jié)果、配置和注釋文件中（這些文件通常很難組合和共享），不過他們越來越多地使用計算型 notebook（如 Jupyter Notebooks 和 R Notebooks），在單個交互式和可移植文檔中組合可執(zhí)行代碼、渲染可視化效果和描述性文本。

Jupyter Notebooks 大大降低了可復(fù)現(xiàn)性的困難，它使科學(xué)家能夠輕松地編寫混合了代碼、結(jié)果和文本的共享計算敘述，從而支持可復(fù)現(xiàn)性研究。然而，像 Jupyter Notebook 這樣的計算型 notebook 并沒有解決實現(xiàn)可復(fù)現(xiàn)性的所有障礙，而且它們還引入了另一些獨(dú)特的挑戰(zhàn)，其中部分挑戰(zhàn)源于它們的交互性。

考慮到在 Jupyter Notebooks 上發(fā)布可復(fù)現(xiàn)研究的技術(shù)和社會障礙，來自加州大學(xué)圣地亞哥分校和伯克利分校的研究者編制了一套規(guī)則、提示、工具和示例 notebook。這套規(guī)則專注于 Jupyter Notebooks，不過也適用于其他混合了實時代碼和敘述性描述的文檔。

下圖 1 展示了在 notebook 開發(fā)周期不同階段所應(yīng)用的規(guī)則。

圖 1：將十個簡單規(guī)則應(yīng)用于創(chuàng)建 Jupyter Notebooks 的工作流。從上到下，該圖描述了開發(fā)一個記錄詳盡、功能良好、用于可復(fù)現(xiàn)性研究的 Jupyter Notebooks 所需的三個不同的階段。

規(guī)則 1：為觀眾講故事

使用 Jupyter Notebooks 的一個主要好處是，它能將解釋性文本與代碼和結(jié)果交織在一起，創(chuàng)建計算性敘述 [8]。不要只保留零星的筆記，而是用解釋性文字講述一個引人入勝的故事，故事的開頭介紹主題，中間介紹步驟，結(jié)尾解釋結(jié)果。不僅要描述你做了什么，還要描述為什么要這樣做、這些步驟是如何連接的，以及它們意味著什么。

如何講述這個故事將取決于你的觀眾。你打算和實驗室的非技術(shù)同事、另一個實驗室的分析師、某一期刊的讀者還是公眾分享你的 notebook？你可能需要為每一類觀眾提供不同種類和級別的解釋。

規(guī)則 2：記錄過程，而不僅僅是結(jié)果

計算型 notebook 的交互特性使得嘗試和對比不同方法或參數(shù)更加快速和容易，以至于我們在執(zhí)行這些交互式調(diào)研時往往無法將其記錄下來。因此，這個建議變得更加重要：確保記錄下所有的探索，甚至那些導(dǎo)致進(jìn)入死胡同的探索！這些將幫助你記住做了什么和為什么做。

許多 notebook 用戶等到分析結(jié)束、得到了可靠結(jié)果后，才添加這樣的解釋性文字。不要等，到那時你可能已經(jīng)忘記了為什么選擇某個特定參數(shù)值、從哪里復(fù)制了一段代碼，或者中間結(jié)果的有趣之處是什么。如果你沒有時間全面記錄你此刻正在做什么或在想什么，那么留下簡短的描述性筆記來提醒自己，在可以停下時抓緊把這些內(nèi)容添加上。

規(guī)則 3：添加分割，使步驟更清晰

notebook 是一個交互式的環(huán)境，所以它很容易編寫和運(yùn)行單行單元格。這有利于實驗，但會讓 notebook 凌亂不堪，充滿難以理解的短小片段。那么，嘗試讓 notebook 中的每個單元格執(zhí)行一個有意義的分析步驟，并且該步驟可以根據(jù)單元格中的代碼或周圍的 markdown 描述很容易地理解。

按單元格模塊化代碼，并在單元格上方用 markdown 標(biāo)記。將每個單元格想象為一個段落、擁有一個函數(shù)或完成一個任務(wù)（例如，創(chuàng)建一個繪圖）。避免長單元格（任何超過 100 行或一頁的內(nèi)容都太長了）。在代碼注釋中放入低級文檔。使用描述性的 markdown header 將 notebook 分區(qū)，使其可以輕松導(dǎo)航和添加目錄。將長 notebook 拆分為一系列 notebook，并保留一個 top-level index notebook，其中包含指向各個 notebook 的鏈接。

規(guī)則 4：模塊化代碼

避免重復(fù)代碼總是很好的做法，但是在 notebook 中，復(fù)制一個單元格、調(diào)整幾行、將生成的代碼粘貼到新單元格或其他 notebook 中并再次運(yùn)行是特別容易的。這種試驗形式很方便，但如果你想更改復(fù)制的代碼的功能或修復(fù)其中的 bug，就會使 notebook 難以閱讀，并且?guī)缀醪豢赡苓M(jìn)行維護(hù)。因此你可以將要復(fù)制和重用的代碼包裝在一個函數(shù)中，這樣就可以根據(jù)需要從任意多個單元格中調(diào)用該函數(shù)。如果你要在其他項目或 notebook 中重用代碼，請考慮將其轉(zhuǎn)換為模塊、包或庫，并遵循良好的軟件開發(fā)實踐（如單元測試）。

模塊化不僅節(jié)省空間，支持維護(hù)，調(diào)試方便，還使增加交互性變得更加簡單。

規(guī)則 5：記錄依賴項

未來重新生成分析時，不僅需要訪問代碼，還需要訪問依賴項。計算科學(xué)的最佳實踐是，從一開始就使用諸如 conda 的 environment.yml 或 pip 的 requirements.txt 之類的工具明確地管理依賴項，以列出所有相關(guān)的依賴項（包括它們的軟件版本）。始終在這些依賴項創(chuàng)建的環(huán)境中工作，以確保不添加未記錄的依賴項。

在 notebook 中，你可以使用 notebook 的擴(kuò)展（如 watermark）顯式打印依賴項。列出 notebook 中關(guān)鍵依賴項的版本（最好列在最下方），如果 notebook 與環(huán)境隔離使用，那么這將保證 notebook 中仍然包含關(guān)鍵信息，從而幫助讀者復(fù)制結(jié)果。

規(guī)則 6：使用版本控制

版本控制是 notebook 使用的一個重要輔助工具，因為 notebook 的交互特性使其很容易意外地更改或刪除重要內(nèi)容。此外，由于 notebook 中包含代碼，代碼不可避免會有 bug，因此確定 bug 引入與修復(fù)的時間（及其可能影響的分析）是科學(xué)計算中的一項關(guān)鍵能力。

但是，請注意，Jupyter Notebook 將每個單元格的代碼和特定且廣泛的元數(shù)據(jù)存儲為 JSON 格式的文本文件。版本控制系統(tǒng)比較這些 JSON 文件中的差異，而不是用戶友好型 notebook GUI（圖形用戶界面）中的差異。

規(guī)則 7：構(gòu)建 pipeline

記錄初步探索性研究的 notebook 很少能被廣泛推廣，但一旦確定了某種穩(wěn)定的分析方法，設(shè)計良好的 notebook 就可以通過 pipeline 推廣到其他任務(wù)中，從而使用不同的輸入數(shù)據(jù)和參數(shù)很容易地重復(fù)分析。記住這一點，從一開始就設(shè)計你的 notebook，以允許將來重新調(diào)整用途。把關(guān)鍵變量聲明（尤其是在進(jìn)行新的分析時會改變的變量）放在 notebook 的頂部，而不是埋在中間的某個地方。直接在 notebook 中執(zhí)行準(zhǔn)備步驟，如數(shù)據(jù)清理，并盡可能避免手動干預(yù)。

規(guī)則 8：分享和解釋數(shù)據(jù)

如果底層數(shù)據(jù)被鎖定，那么訪問清晰注釋的 notebook 對可復(fù)現(xiàn)性也幾乎沒有用處。努力使你的數(shù)據(jù)或數(shù)據(jù)樣本與 notebook 一起公開。notebook 可以很容易地提供輸入數(shù)據(jù)和上游處理步驟的描述，這對于解釋結(jié)果至關(guān)重要。

理想情況下，你可以在 notebook 中共享整個數(shù)據(jù)集。我們認(rèn)識到許多數(shù)據(jù)集太大或太敏感，無法以這種方式共享。在這些情況下，考慮將大型和復(fù)雜的數(shù)據(jù)集分解為多個層次，這樣即使原始數(shù)據(jù)太大，無法與已發(fā)布的 notebook 一起共享，或者受到隱私或其他訪問問題的限制，也不會影響到可復(fù)現(xiàn)性。

規(guī)則 9：允許閱讀、運(yùn)行和探索 notebook

如果你遵循了前面的規(guī)則，那么你的 notebook 應(yīng)該能夠捕獲整個過程并易于閱讀。但是其他人如何訪問、運(yùn)行和探索它們呢？你可以通過多種方式支持他人重用你的 notebook。首先，將 notebook 存儲到一個具備清晰 README 文件的公共代碼庫中。

除了允許重用之外，你還要考慮如何利用 notebook 的獨(dú)特結(jié)構(gòu)來支持閱讀和探索。至少，將所有 notebook 的靜態(tài) HTML/PDF 版本存儲在出版物附帶代碼庫的最終版本中。

規(guī)則 10：促進(jìn)可復(fù)現(xiàn)和開放的研究

顯然，僅使用計算型 notebook 并不能保證研究的可復(fù)現(xiàn)。如果 notebook 的便利性和交互性讓你滿意，那你可以采取下一步行動，在實驗室或工作場所宣傳其可復(fù)現(xiàn)性。讓實驗室的同事試著運(yùn)行你的 notebook，然后聽他們解釋在什么地方出了問題。也試著運(yùn)行他們的 notebook，讓他們知道你是否遇到了障礙。

將可復(fù)現(xiàn)性作為研究小組所有計算工作的關(guān)鍵要素，而不是在分析完成后才執(zhí)行，或被期刊或評審人員要求后才思考。