手把手教你組織數據科學項目！

作者：kdnuggets

翻譯：和中華

校對：丁楠雅

本文約4200字，建議閱讀10分鐘。

本文介紹了一個工具可以幫助迅速構建一個標準但靈活的數據科學項目結構，便於實施和分享數據科學工作。

由DrivenData提供

為什麼要重視項目結構？

說起數據分析，我們往往會想到報告結果、深入見解或可視化。通常這些最終結果佔據了主要地位，所以人們很容易專註於讓結果看起來漂亮而忽略了生成它們的代碼質量。但是，這些最終結果都是以編程方式創建的，所以代碼質量仍然很重要！此處我們討論的不是代碼縮進或格式標準，數據科學的代碼質量的最終標準是正確性和可再現性(reproducibility)。

眾所周知，好的分析通常是隨意和偶然探索的結果。各種沒得到結果的探索性實驗和快速測試都是通往好結果道路上的一部分，並且沒有靈丹妙藥可以將數據探索轉變為簡單的線性過程。

一旦開始一個項目，就很難再去思考代碼結構和項目布局了。所以最好從一個乾淨、合乎邏輯的結構開始並一以貫之。我們認為使用這樣的標準化設置是非常有好處的。原因如下：

其他人會感謝你

定義明確的標準項目結構意味著新手無需研究大量文檔就可以理解一項分析。這也意味著他們不一定非得閱讀100％的代碼才知道去哪裡找特定的內容。

組織良好的代碼往往能做到自我記錄(self-documenting)，組織結構本身可以在無需太多開銷的情況下為你的代碼提供上下文。人們會因此感謝你，因為他們可以：

更輕鬆地與你在此分析中合作

從你對流程和領域的分析中學習

對分析得到的結論充滿信心

你可以在任何主流的Web開發框架（如Django或Ruby on Rails）中找到這方面的好例子。在創建一個新的Rails項目之前，沒有人會去思考要在哪個位置放什麼，他們只是運行rails new來獲得像其他人一樣的標準項目骨架（skeleton）。由於該默認結構在大多數項目中都是合乎邏輯且合理的，因此從未見過該特定項目的人也可以容易地找到各種部件。

另一個很好的例子是類Unix系統的文件系統層次結構標準（Filesystem Hierarchy Standard）。/ etc目錄有非常特定的目的，就像/ tmp文件夾一樣，每個人（或多或少）都同意遵守該約定。這意味著Red Hat用戶和Ubuntu用戶都知道在哪裡查找某些類型的文件，即使他們使用的是對方的系統或者其他任何符合該標準的系統！

理想情況下，當同事打開您的數據科學項目時，也應該如此。

你會感謝自己

在開始之前，是否應該主動把X列加入到數據中？還是說其中某個notebook可以完成這一步？

想一想，在運行繪圖代碼之前我們必須首先運行哪個notebook：它是「過程數據」還是「乾淨數據」？

地理圖形中所用的shapefiles是從哪下載的？

等類似問題

這些問題讓人頭疼，並且是無組織項目的癥狀。良好的項目結構應該讓人很容易回到舊時的工作，例如分離關注點，將分析抽象為DAG，以及版本控制等實踐。

沒有任何約束

不贊同某些默認文件夾名稱？正在做一個不標準且與當前結構不完全匹配的項目？更願意使用與（少數）默認包不同的包？

去吧！這是一種輕量級結構，旨在成為許多項目的良好起點。正如PEP 8所說：

項目內部的一致性更為重要。一個模塊或功能內部的一致性是最重要的。...但是，要知道何時不一致，有時風格指南建議並不適用。如有疑問，請用你的最佳判斷。查看其他示例並確定最佳效果。並且不要猶豫去提問！

開始

我們為Python項目創建了一個數據科學cookiecutter模板。您的分析不一定要在Python中，但模板確實提供了一些Python樣板，您可能想要刪除它們（例如，在src文件夾中，以及docs中的Sphinx文檔框架）。

需求

Python 2.7 或 3.5

cookiecutter Python package>= 1.4.0: pip install cookiecutter

開始一個新項目

啟動新項目只需在命令行中運行如下命令。無需先創建目錄，cookiecutter將為您完成。

cookiecutter

https://github.com/drivendata/cookiecutter-data-science

示例

https://www.kdnuggets.com/2018/07/cookiecutter-data-science-organize-data-project.html

目錄結構

├── LICENSE

├── Makefile

├── README.md

├── data

│ ├── external

│ ├── interim

│ ├── processed

│ └── raw

│

├── docs

│

├── models

│

├── notebooks

│ the creator"s initials, and a short `-` delimited description, e.g.

│ `1.0-jqp-initial-data-exploration`.

│

├── references

│

├── reports

│ └── figures

│

├── requirements.txt

│ generated with `pip freeze > requirements.txt`

│

├── src

│ ├── __init__.py

│ │

│ ├── data

│ │ └── make_dataset.py

│ │

│ ├── features

│ │ └── build_features.py

│ │

│ ├── models

│ │ │ predictions

│ │ ├── predict_model.py

│ │ └── train_model.py

│ │

│ └── visualization

│ └── visualize.py

│

觀點

項目結構中隱含著一些觀點，這些觀點源於我們在數據科學項目合作時可行的和不可行的工作經驗。一些觀點是關於工作流程的，一些是關於提高效率的工具的。以下是該項目所依據的一些信念，如果您有想法，請提供或分享。

數據是不可變的

不要編輯原始數據，尤其不要手動編輯，也不要在Excel中編輯。不要覆蓋原始數據。不要保存多個版本的原始數據。將數據（及其格式）視為不可變的。你編寫的代碼應該讓原始數據通過分析流程管道並得到最終分析。沒必要每次想要創建一個新計算時都運行所有步驟（請參閱Analysis是DAG），但是任何人都應該能夠僅使用src中的代碼和data /raw中的數據來重現分析結果。

此外，如果數據是不可變的，則它不需要像代碼那樣進行源代碼控制。因此，默認情況下，data文件夾包含在.gitignore文件中。如果你有少量很少會被更改的數據，你可能希望將數據包含在repo中。目前Github會警告文件是否超過50MB並且拒絕超過100MB的文件。用於存儲/同步大型數據的一些其他方案包括同步工具（例如，s3cmd的AWS S3，Git Large File Storage，Git Annex和dat）。目前默認情況下，我們請求一個S3 bucket並使用AWS CLI將data文件夾中的數據與伺服器同步。

Notebooks用於探索和交流

Jupyter notebook,Beaker notebook,Zeppelin和其他互動式編程工具對於探索性數據分析（EDA）來說是非常高效的。然而，這些工具對重現分析而言效果較差。 當我們在工作中使用notebook時，我們經常細分notebook的文件夾。例如，notebook/exploration包括初始探索，而notebook/report包含更漂亮的工作，並可以作為html格式導出到report目錄。

由於notebooks挑戰了源代碼控制的目標（例如，json的差異通常不是人類可讀的，並且幾乎不可能合併），我們不建議直接在Jupyter notebooks上與其他人合作。為了有效的使用notebooks，這裡有兩個建議：

遵守一種命名習慣，可以展現作者以及所做分析的順序。我們使用這種格式: --.ipynb(例如，0.3-bull-visualize-distribution.ipynb)。

重構某些好的部分。完成相同任務的代碼不要寫在多個notebook中。如果是一個數據預處理任務，放入處理管道並把代碼寫在src/data/make_dataset.py中，並且從data/interim中載入數據。如果是有用的工具代碼,重構到src中。

譯者註：用文本編輯器打開jupyter notebook的文件，可以看到其本質上是一個json格式的文件，所以這裡作者說很難使用Git去diff或merge不同版本的notebook代碼，不過目前已有工具致力於解決這個問題，例如nbdime。

默認情況我們把項目轉換成一個python包(見setup.py文件)。你可以導入自己的代碼，並且在notebook中使用，方法如下：

# OPTIONAL: Load the "autoreload" extension so that code can change

%load_ext autoreload

# OPTIONAL: always reload modules so that as you change code in src, it gets loaded

%autoreload 2

from src.data import make_dataset

分析就是DAG

在分析中，你常常會有一些運行時間很長的步驟，比如預處理數據或者訓練模型。如果這些步驟已經運行過了（並且你已經將輸出保存在了某處，例如data/interim目錄），那你肯定不想每次都等待它們重新運行。我們更喜歡用make來管理彼此依賴的步驟，尤其是運行時間很長的步驟。Make是基於Unix的平台上的常用工具（可用於Windows）。遵守make官方文檔,Makefile conventions和portability guide將幫助確保你的Makefile在各個系統中有效工作。這是一些入門示例。許多從事數據工作的人都使用make作為他們的首選工具，其中就包括Mike Bostock。

還有其他用來管理使用Python而不是DSL（領域特定語言）編寫的DAGs的工具（例如，Paver，Luigi，Airflow，Snakemake，Ruffus或Joblib）。如果它們更適合您的分析，請隨意使用。

從環境開始構建

重現某個分析的第一步通常是重現它運行的計算環境。你需要相同的工具，相同的庫和相同的版本，以使一切都很好地協同工作。

一個有效的方法是使用virtualenv（我們建議使用virtualenvwrapper來管理virtualenvs）。通過列舉repo中的所有需求（我們包含一個requirements.txt文件），你可以輕鬆跟蹤用於重現分析所需的包。以下是一個不錯的工作流程：

運行mkvirtualenv創建新項目

pip install分析所需的包

運行pip freeze > requirements.txt以確定用於重現分析的確切包版本

如果你發現需要安裝其他軟體包，請再次運行pip freeze > requirements.txt並將更改提交到版本控制。

如果你對重新創建環境有更複雜的要求，請考慮基於虛擬機的方法，如Docker或Vagrant。這兩個工具都使用基於文本的格式（分別為Dockerfile和Vagrantfile），你可以輕鬆添加到源代碼控制中，以描述如何創建滿足需求的虛擬機。

密碼和配置不要加入版本控制

你肯定不想在Github上泄露你的AWS密鑰或Postgres用戶名和密碼。不再贅述，請看關於這一點的Twelve Factor App。這是一種方法：

將您的機密和配置變數存儲在一個特殊文件中

在項目根目錄中創建一個.env文件。感謝.gitignore，永遠不要把該文件提交到版本控制repo中。以下是一個例子：

# example .env file

DATABASE_URL=postgres://username:password@localhost:5432/dbname

AWS_ACCESS_KEY=myaccesskey

AWS_SECRET_ACCESS_KEY=mysecretkey

OTHER_VARIABLE=something

使用包自動載入這些變數

如果查看src / data / make_dataset.py中的存根腳本，它使用了一個名為python-dotenv的包將此文件中的所有條目作為環境變數載入，以便可以使用os.environ.get訪問它們。這是一個改編自python-dotenv文檔的示例片段：

# src/data/dotenv_example.py

import os

from dotenv import load_dotenv, find_dotenv

# find .env automagically by walking up directories until it"s found

dotenv_path = find_dotenv()

# load up the entries as environment variables

load_dotenv(dotenv_path)

AWS CLI配置

當使用Amazon S3存儲數據時，有一個簡單的方法來管理AWS訪問，即把訪問keys設置為環境變數。但是在一台機器上管理多個keys（例如，同時有多個項目）時，最好還是使用一個憑證文件（credentials file），通常放在~/.aws/credentials，該文件看起來像這樣：

[default]

aws_access_key_id=myaccesskey

aws_secret_access_key=mysecretkey

[another_project]

aws_access_key_id=myprojectaccesskey

aws_secret_access_key=myprojectsecretkey

你可以在初始化項目時添加名稱。假設未設置合適的環境變數，則使用默認的配置。

保守地更改默認文件夾結構

為了使這種結構廣泛適用於不同類型的項目，我們認為最好的方法是對於你自己的項目而言，你可以自由更改文件夾，但在改變用於所有項目的默認結構時要保守。

我們專門為添加，刪減，重命名或移動文件夾的問題創建了一個文件夾布局標籤。 更一般地說，我們還創建了一個需求討論標籤，用於在實施之前應該進行仔細討論和廣泛支持的問題。

貢獻

Cookiecutter數據科學項目有點武斷，但不怕出錯。最佳實踐總在改變，工具一直在發展，我們從中吸取了教訓。該項目的目標是使啟動、構建和共享一個分析更加容易。我們鼓勵提出請求和提交問題。我們很想知道什麼對你有用，什麼沒用。

如果你使用Cookiecutter數據科學項目，請鏈接回此頁面或給我們一個贊，並讓我們知道！

相關項目和參考鏈接

項目結構和可再現性更多地在R研究社區中被討論。以下是一些項目和博客文章，如果你使用R工作則可能會幫到你。

Project Template- An R data analysis template

"Designing projects" on Nice R Code

"My research workflow" on Carlboettifer.info

"A Quick Guide to Organizing Computational Biology Projects" in PLOS Computational Biology

最後，非常感謝Cookiecutter項目（github），它幫助我們花更少的時間思考和編寫樣板文件，從而花更多的時間去完成工作。

原文標題：

Cookiecutter Data Science: How to Organize Your Data Science Project

鏈接：

https://www.kdnuggets.com/2018/07/cookiecutter-data-science-organize-data-project.html

譯者簡介

和中華，留德軟體工程碩士。由於對機器學習感興趣，碩士論文選擇了利用遺傳演算法思想改進傳統kmeans。目前在杭州進行大數據相關實踐。加入數據派THU希望為IT同行們盡自己一份綿薄之力，也希望結交許多志趣相投的小夥伴。

翻譯組招募信息

工作內容：需要一顆細緻的心，將選取好的外文文章翻譯成流暢的中文。如果你是數據科學/統計學/計算機類的留學生，或在海外從事相關工作，或對自己外語水平有信心的朋友歡迎加入翻譯小組。

你能得到：定期的翻譯培訓提高志願者的翻譯水平，提高對於數據科學前沿的認知，海外的朋友可以和國內技術應用發展保持聯繫，THU數據派產學研的背景為志願者帶來好的發展機遇。

其他福利：來自於名企的數據科學工作者，北大清華以及海外等名校學生他們都將成為你在翻譯小組的夥伴。

點擊文末「閱讀原文」加入數據派團隊~

轉載須知

如需轉載，請在開篇顯著位置註明作者和出處（轉自：數據派ID：datapi），並在文章結尾放置數據派醒目二維碼。有原創標識文章，請發送【文章名稱-待授權公眾號名稱及ID】至聯繫郵箱，申請白名單授權並按要求編輯。

發布後請將鏈接反饋至聯繫郵箱（見下方）。未經許可的轉載以及改編者，我們將依法追究其法律責任。

點擊「閱讀原文」擁抱組織

喜歡這篇文章嗎？立刻分享出去讓更多人知道吧！