歡迎光臨
每天分享高質量文章

十大至簡規則,用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,讓他們知道你是否遇到了障礙。

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

已同步到看一看
赞(0)

分享創造快樂