お悩み

主に機械学習プロジェクトのフォルダ管理において...

自分は把握していても、GitHub等で外部に公開する際、第三者にとっては一目でわかってもらえるフォルダ構成になっていない（可読性の問題）。
テンプレートなんて特に考えず、プロジェクト毎に違うフォルダ構成をとってしまっている（統一性/汎用性の問題）。
上記故に、更新データや新しいモデルで学習する際、（何かしら工夫しないと）フォルダが混合して機械学習で得られた結果と学習データの対応が取れなかったりする（再現性（？）の問題）。

解決策

色々調べて見た結果、Cookiecutter というプロジェクトテンプレートを作成するコマンドラインユーティリティがかなり使えそうでした。

Cookiecutter creates projects from project templates, e.g. Python package projects.

以下、こちらのインストラクションに従ってプロジェクトを作成しました。

インストール環境

$ sw_vers
ProductName:    Mac OS X
ProductVersion: 10.14
BuildVersion:   18A391
$ python -V
Python 3.7.4
$ pip -V
pip 19.2.3 from /Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/pip (python 3.7)

インストール方法

インストールはpipで簡単にできます。

$ pip install cookiecutter
$ cookiecutter --version
Cookiecutter 1.6.0 from /Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages (Python 3.7)

テンプレートのダウンロード

今回はPythonの機械学習プロジェクト向けのテンプレートである Data Science Cookiecutter をダウンロードしました。
とりあえずホーム下に適当なディレクトリを作成して実行しました。

$ mkdir ~/test_cc
$ ~/test_cc
$ cookiecutter https://github.com/drivendata/cookiecutter-data-science
You've downloaded /Users/YOUR_NAME/.cookiecutters/cookiecutter-data-science before. Is it okay to delete and re-download it? [yes]: yes
project_name [project_name]: ml_project
repo_name [ml_project]: 
author_name [Your name (or your organization/company/team)]: mj
description [A short description of the project.]: templates for ml project       
Select open_source_license:
1 - MIT
2 - BSD-3-Clause
3 - No license file
Choose from 1, 2, 3 (1, 2, 3) [1]: 1
s3_bucket [[OPTIONAL] your-bucket-for-syncing-data (do not include 's3://')]: 
aws_profile [default]: 
Select python_interpreter:
1 - python3
2 - python
Choose from 1, 2 (1, 2) [1]: 1
$ ls
ml_project/

上記のようにcookiecutter https://github.com/drivendata/cookiecutter-data-science のコマンドを実行すると、プロジェクト作成のための質問を受けますので淡々と答えていきます。
最終的に上記の質問のproject_nameで回答したml_project/というディレクトリが作成されました。

作成されたディレクトリの中身

$ ls ml_project 
LICENSE              models/              setup.py
Makefile             notebooks/           src/
README.md            references/          test_environment.py
data/                reports/             tox.ini
docs/                requirements.txt

最初から色々入ってます。

フォルダ構成の説明

詳しくはこちらにも記載してあるのですが、ダウンロードされたテンプレートには下記の様に詳細な説明が加えられたマークダウンファイル: README.mdが最初から存在しています。

README.md

ml_project
==============================

templates for ml project

Project Organization
------------

    ├── LICENSE
    ├── Makefile           <- Makefile with commands like `make data` or `make train`
    ├── README.md          <- The top-level README for developers using this project.
    ├── data
    │   ├── external       <- Data from third party sources.
    │   ├── interim        <- Intermediate data that has been transformed.
    │   ├── processed      <- The final, canonical data sets for modeling.
    │   └── raw            <- The original, immutable data dump.
    │
    ├── docs               <- A default Sphinx project; see sphinx-doc.org for details
    │
    ├── models             <- Trained and serialized models, model predictions, or model summaries
    │
    ├── notebooks          <- Jupyter notebooks. Naming convention is a number (for ordering),
    │                         the creator's initials, and a short `-` delimited description, e.g.
    │                         `1.0-jqp-initial-data-exploration`.
    │
    ├── references         <- Data dictionaries, manuals, and all other explanatory materials.
    │
    ├── reports            <- Generated analysis as HTML, PDF, LaTeX, etc.
    │   └── figures        <- Generated graphics and figures to be used in reporting
    │
    ├── requirements.txt   <- The requirements file for reproducing the analysis environment, e.g.
    │                         generated with `pip freeze > requirements.txt`
    │
    ├── setup.py           <- makes project pip installable (pip install -e .) so src can be imported
    ├── src                <- Source code for use in this project.
    │   ├── __init__.py    <- Makes src a Python module
    │   │
    │   ├── data           <- Scripts to download or generate data
    │   │   └── make_dataset.py
    │   │
    │   ├── features       <- Scripts to turn raw data into features for modeling
    │   │   └── build_features.py
    │   │
    │   ├── models         <- Scripts to train models and then use trained models to make
    │   │   │                 predictions
    │   │   ├── predict_model.py
    │   │   └── train_model.py
    │   │
    │   └── visualization  <- Scripts to create exploratory and results oriented visualizations
    │       └── visualize.py
    │
    └── tox.ini            <- tox file with settings for running tox; see tox.testrun.org


--------

<p><small>Project based on the <a target="_blank" href="https://drivendata.github.io/cookiecutter-data-science/">cookiecutter data science project template</a>. #cookiecutterdatascience</small></p>

ご覧の様にフォルダが綺麗に小分けされており、どこに何のファイルを置くか明記されています、優秀です。
これをベースにフォルダ構成の説明（必要に応じて自分でアレンジ）をする事で、GitHub上で公開しても一目でフォルダ構成が把握してもらえる（編集側としてもとても便利です）のでとても助かります（何よりこういうのは私自身のタスク/データ管理のための勉強にもなります）。

※ Cookiecutter によると、解析にはPythonに限らず他言語でも使用可能との事ですが、上記のインストールを行った場合、デフォルトでいくつかPythonコードを置いてくれてます（e.g. srcフォルダー内の.pyスクリプト）。

With this in mind, we've created a data science cookiecutter template for projects in Python. Your analysis doesn't have to be in Python, but the template does provide some Python boilerplate that you'd want to remove (in the src folder for example, and the Sphinx documentation skeleton in docs).

もっと周知されてもいいはず

まじでこの世の全ての機械学習プロジェクトのフォルダ構成に悩む方々に教えてあげたいんだが、Cookiecutter とかいう全ての人間を虜にするプロジェクトテンプレートがある。
フォルダ構成が最初からほぼ最適化されていて、汎用性も高いからぜひ全国のデータ分析を愛する者たち、データ管理を憎む者たち、全ての機械学習関係者に伝われ

参考

Cookiecutter

これでもう悩まない！機械学習のためのフォルダ構成テンプレートを使おう。

お悩み