Cookiecutter 数据科学

一个逻辑清晰、合理标准化但又灵活的数据科学项目结构，用于开展和分享数据科学工作。

Cookiecutter 数据科学 (CCDS) 是一个用于搭建包含最佳实践的数据科学项目模板的工具。如需了解更多关于 CCDS 的理念，请访问 项目主页。

ℹ️ Cookiecutter 数据科学 v2 相较于 v1 有所变化。现在需要安装新的 cookiecutter-data-science Python 包，该包扩展了 cookiecutter 模板工具的功能。请使用提供的 ccds 命令行程序，而非 cookiecutter。

安装

Cookiecutter 数据科学 v2 需要 Python 3.9+。由于这是一个跨项目的实用工具应用，我们建议使用 pipx 进行安装。安装命令选项如下：

# 使用 pipx 从 PyPI 安装（推荐）
pipx install cookiecutter-data-science

# 使用 pip 从 PyPI 安装
pip install cookiecutter-data-science

# 使用 conda 从 conda-forge 安装（即将推出）
# conda install cookiecutter-data-science -c conda-forge

开始一个新项目

要开始一个新项目，运行以下命令：

ccds

生成的目录结构

您新项目的目录结构大致如下（具体取决于您选择的设置）：

├── LICENSE            <- 如果选择了开源许可证，则包含许可证文件
├── Makefile           <- 包含便捷命令的 Makefile，例如 `make data` 或 `make train`
├── README.md          <- 面向开发者的顶级 README 文件。
├── data
│   ├── external       <- 来自第三方的数据。
│   ├── interim        <- 经过转换的中间数据。
│   ├── processed      <- 用于建模的最终规范数据集。
│   └── raw            <- 原始的不可变数据备份。
│
├── docs               <- 默认的 mkdocs 项目；详情请参阅 www.mkdocs.org
│
├── models             <- 训练好的序列化模型、模型预测或模型摘要
│
├── notebooks          <- Jupyter 笔记本。命名规则为序号（用于排序）、创建者首字母缩写以及简短的连字符分隔描述，例如 `1.0-jqp-initial-data-exploration`。
│
├── pyproject.toml     <- 项目配置文件，包含 {{ cookiecutter.module_name }} 的包元数据以及 black 等工具的配置
│
├── references         <- 数据字典、手册及其他所有说明性资料。
│
├── reports            <- 生成的分析报告，格式为 HTML、PDF、LaTeX 等。
│   └── figures        <- 用于报告中的图表和图形
│
├── requirements.txt   <- 用于重现分析环境的需求文件，例如通过 `pip freeze > requirements.txt` 生成
│
├── setup.cfg          <- flake8 的配置文件
│
└── {{ cookiecutter.module_name }}   <- 用于本项目的源代码。
    │
    ├── __init__.py             <- 使 {{ cookiecutter.module_name }} 成为一个 Python 模块
    │
    ├── config.py               <- 存储有用的变量和配置
    │
    ├── dataset.py              <- 用于下载或生成数据的脚本
    │
    ├── features.py             <- 用于创建建模特征的代码
    │
    ├── modeling                
    │   ├── __init__.py 
    │   ├── predict.py          <- 使用训练好的模型进行推理的代码          
    │   └── train.py            <- 用于训练模型的代码
    │
    └── plots.py                <- 用于创建可视化图表的代码   

使用未发布的更改

默认情况下，ccds 将使用与已安装的 ccds 包版本相对应的 项目模板 版本（例如，如果您安装了 ccds v2.0.1，则默认会使用 v2.0.1 版本的项目模板）。若要使用特定版本的项目模板，可以使用 -c/--checkout 标志来指定您希望使用的分支、标签或提交哈希。例如，要使用 master 分支上的项目模板：

ccds -c master

使用 v1 版本

如果您想使用旧版 v1 项目模板，需要先安装 cookiecutter-data-science 包或 cookiecutter 包。然后，使用任一命令行程序并添加 -c v1 选项：

ccds https://github.com/drivendataorg/cookiecutter-data-science -c v1
# 或等效地
cookiecutter https://github.com/drivendataorg/cookiecutter-data-science -c v1

贡献

我们欢迎贡献！请参阅文档以获取指南。

安装开发依赖

pip install -r dev-requirements.txt

运行测试

pytest tests

Cookiecutter Data Science 快速上手指南

Cookiecutter Data Science (CCDS) 是一个用于创建数据科学项目模板的工具，它提供了一套逻辑清晰、标准化且灵活的项目结构，帮助开发者遵循最佳实践。

环境准备

• 操作系统：Linux / macOS / Windows (需配置相应环境)
• Python 版本：Python 3.9 或更高版本
• 前置依赖：
  • 推荐安装 pipx 以隔离工具环境（可选，但强烈推荐）
  • 若未使用 pipx，需确保 pip 可用

💡 国内加速建议：如果下载速度慢，可配置国内镜像源。

• pip 临时使用清华源：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <package>
• pipx 设置镜像：pipx install --pip-args '--index-url https://pypi.tuna.tsinghua.edu.cn/simple' <package>

安装步骤

推荐使用 pipx 进行全局安装，避免污染项目依赖：

# 方式一：使用 pipx 安装（推荐）
pipx install cookiecutter-data-science

# 方式二：使用 pip 安装
pip install cookiecutter-data-science

⚠️ 注意：CCDS v2 版本已不再直接使用 cookiecutter 命令启动模板，请使用新提供的 ccds 命令行工具。

基本使用

安装完成后，在终端运行以下命令即可开始创建新项目：

ccds

运行后，程序将交互式引导你输入项目名称、模块名称、作者信息等。配置完成后，会自动生成如下标准目录结构：

├── LICENSE            <- 开源许可证文件
├── Makefile           <- 包含便捷命令（如 make data, make train）
├── README.md          <- 项目说明文档
├── data
│   ├── external       <- 第三方数据
│   ├── interim        <- 中间处理数据
│   ├── processed      <- 最终用于建模的标准数据
│   └── raw            <- 原始不可变数据
├── docs               <- 文档项目 (默认 mkdocs)
├── models             <- 训练好的模型及预测结果
├── notebooks          <- Jupyter  notebooks (命名规范：序号 - 作者缩写 - 描述)
├── pyproject.toml     <- 项目配置与元数据
├── references         <- 数据字典与参考资料
├── reports            <- 生成的分析报告
│   └── figures        <- 报告所需的图表
├── requirements.txt   <- 环境依赖列表
├── setup.cfg          <- 代码检查工具配置
└── <module_name>      <- 项目源代码目录
    ├── __init__.py
    ├── config.py      <- 配置变量
    ├── dataset.py     <- 数据下载与生成脚本
    ├── features.py    <- 特征工程代码
    ├── modeling       
    │   ├── train.py   <- 模型训练
    │   └── predict.py <- 模型推理
    └── plots.py       <- 可视化代码

创建完成后，进入项目目录即可开始开发工作。