用 cookiecutter 创建新项目

生信菜鸟团

发布于 2021-10-12 15:40:07

1.5K0

发布于 2021-10-12 15:40:07

谈及数据分析，我们一般会联想到数据的分析结果和可视化，光鲜亮丽的结果固然重要，但要知道这些结果归根到底都是由代码产生的，而代码质量的评判标准即是数据代码的正确性和可重复性。虽然我们都知道，一份漂亮的研究结果通常是分散且偶然探索结果的集合。研究的过程往往并非一帆风顺，那些失败的探索性试验也都是结果的一部分。所以这也会导致项目结构变得复杂冗余，难以追溯。

因此，最好的办法是，我们从一开始就从一个干净、合乎逻辑的文件管理结构进行我们的项目，并一以贯之。使用标准化结构无论是对他人还是对自己都是有相当好处的。

对他人有好处

定义明确的项目结构意味着别人可以很容易理解你的分析内容，无需翻阅所有文件即可找到想要的代码。

•更轻松地与合作；•从你的分析中学习；•对分析的结论更具信心

对自己有好处

你是否尝试过复现几个月前甚至几年前做的分析，很多时候面对混乱的代码逻辑，我们自己往往也会知难而退吧。

所以良好的数据结构和详细的文档可以帮助你快速回顾之前的研究和代码。

用 cookiecutter 创建新项目

那么有没有什么快速的方法可以以一套约定俗成（或自定义）的范式来生成一套完整的项目文件模板呢？cookiecutter 就是不二之选，我们可以很轻松的在 GitHub 上找到成千上万的模板，通过模板即可一行代码创建新项目。

安装 cookiecutters

pip install cookiecutter

cookiecutter[1] 就是一个 Python 包，因此用 Python 的手段即可直接安装。

对于非 Python 系的同学来说，也可以使用包管理器的方式安装。

# For Mac
brew install cookiecutter
# For Debian/Ubuntu
sudo apt install cookiecutter

用 cookiecutter 创建项目

这里我们以 GitHub 中的 cookiecutter-data-science 模板为例（https://github.com/drivendata/cookiecutter-data-science），这个模板可以一键创建数据分析所需的项目结构。

我们可以在 Github 中搜索到超过 4000 个 cookiecutter 模板（搜索 cookiecutter 关键词）。例如，当我们需要找开发 Python 包的模板时，可以使用 cookiecutter-pypackage 作为模板。这些模板也包含着作者各自对该领域的理解，虽然未必适用于所有人，但对于菜鸟来说，这无疑是一种学习前人经验的绝佳方式。

一行代码生成项目结构

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

在项目生成过程中，会产生一些提示，需要输入对应信息，填写项目名、包名什么的等等。

查看项目结构：

├── 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           <- Make this project pip installable with `pip install -e`
├── 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.readthedocs.io

更多关于 cookiecutter-data-science 模板的内容可参阅官方文档：http://drivendata.github.io/cookiecutter-data-science/

用 cookiecutter 组织生物信息学项目

下面以"A Quick Guide to Organizing Computational Biology Projects[2]" 这篇文章所提到的结构做一个简单的示例，我们将演示如何创建一个自定义的 cookiecutter 项目模板。

根目录下包含五个子文件夹。分别为：

•数据(data)：储存所有的 raw data 数据（测序数据）；•结果(results)：存储每一步分析得到的结果文件；•编写的代码(src)：存储分析过程中用到的代码；•工具(tool)：存储一些这个项目使用到的特定工具；•文件(doc)：存放发表文章所需的所有图和表。

这里建议的结构并非适合所有人，这里仅以该例作为演示，大家也可根据自己的喜好自定义。

mkdir new_project
cd new_project

现在我们将创建与上图相同的目录结构，这里的文件名需要加上模板标签。这些标签将在 cookiecutter.json 文件中用到。

mkdir {{cookiecutter.project_name}}
cd {{cookiecutter.project_name}}
mkdir {{cookiecutter.documentation}}
mkdir {{cookiecutter.data}}
mkdir {{cookiecutter.source}}
mkdir {{cookiecutter.bin}}
mkdir {{cookiecutter.results}}

我们通常也会在每个项目目录中添加一个 README 文件，对项目进行概括描述（这里直接下载了一个模板）。

wget https://gist.githubusercontent.com/PurpleBooth/109311bb0361f32d87a2/raw/824da51d0763e6855c338cc8107b2ff890e7dd43/README-Template.md -O tmp.md
cat tmp.md | sed 's/Project Title/{{cookiecutter.project_name}}/' > {{cookiecutter.README}}.md
rm -f tmp.md

最后，在 new_project 目录下创建 cookiecutter.json文件，内容如下：

{
    "project_name": "new_project",
    "documentation": "doc",
    "data": "data",
    "source": "src",
    "bin": "bin",
    "results": "results",
    "README": "README"
}

至此，我们已经构建了一个简单的生物信息学项目模板，我们可以看一下 new_project 目录的结构：

tree --charset unicode new_project/
new_project/
|-- cookiecutter.json
`-- {{cookiecutter.project_name}}
    |-- {{cookiecutter.README}}.md
    |-- {{cookiecutter.bin}}
    |-- {{cookiecutter.data}}
    |-- {{cookiecutter.documentation}}
    |-- {{cookiecutter.results}}
    `-- {{cookiecutter.source}}
 
6 directories, 2 files

直接用 cookiecutter 即可调用我们新创建的项目模板，生成新的项目 msms：

cookiecutter new_project/
project_name [new_project]: msms
documentation [doc]: 
data [data]: 
source [src]: 
bin [bin]: 
results [results]: 
README [README]: 
 
tree --charset unicode msms/
msms/
|-- README.md
|-- bin
|-- data
|-- doc
|-- results
`-- src
 
5 directories, 1 file
 
head -1 msms/README.md 
# msms

以上即是一个简单的管理生信项目的例子。更多关于创建 cookiecutter 模板的教程可参阅官方文档：cookiecutter.readthedocs.io

总结

cookiecutter 是一个简单好用的项目结构生成引擎，并且已经有很多各种类型的开源模板，涵盖方方面面。它可以极大地节约项目初始化的重复劳动，提高代码的可重复性，也可以帮助新人养成良好习惯，学习前人经验。

参考

•https://cookiecutter.readthedocs.io/en/1.7.3/first_steps.html•http://drivendata.github.io/cookiecutter-data-science/•https://note.qidong.name/2018/10/cookiecutter/•https://davetang.org/muse/2018/02/09/organising-computational-biology-projects-cookiecutter/