drivendataorg/cookiecutter-data-science

What it is

Cookiecutter Data Science (CCDS) is a small command‑line utility that generates a ready‑to‑use project skeleton for data‑science work. It builds on the generic cookiecutter templating tool, but adds a dedicated ccds command and a pre‑designed folder layout that follows best‑practice conventions.

---

Why it matters

• Consistency – Every new project starts with the same logical directory tree (raw data, notebooks, models, docs, etc.), making it easier for teams to jump in and understand each other’s work.
• Reproducibility – The template includes a requirements.txt, Makefile, and pyproject.toml so the environment can be recreated with a single command.
• Speed – Running ccds creates all the boiler‑plate files in seconds, letting you focus on the analysis instead of folder‑setup.
• Extensible – The template is versioned; you can pick a specific tag/branch (e.g., the old v1 layout) or the latest release.

---

How it works

1. Install the package (recommended via pipx):

   pipx install cookiecutter-data-science
   

2. Run the generator:

   ccds            # prompts for project name, module name, license, etc.
   

3. Answer the interactive questions; CCDS writes a directory matching the chosen options.
4. Start coding inside the generated {{ cookiecutter.module_name }} package and use the provided Makefile shortcuts (make data, make train, …) to run common tasks.

---

Key parts of the generated scaffold

Path	Purpose
data/	Sub‑folders for raw, external, interim, and processed data (read‑only raw data encourages provenance).
notebooks/	Jupyter notebooks with a naming convention that orders them and records author initials.
{{ cookiecutter.module_name }}/	Python package containing:

• config.py – central configuration values
• dataset.py – download/generation helpers
• features.py – feature‑engineering utilities
• modeling/ – train.py and predict.py
• plots.py – reusable plotting functions | | models/ | Place for serialized models, predictions, or model summaries. | | docs/ | A starter mkdocs site for project documentation. | | reports/ | Generated analysis outputs (HTML, PDF, LaTeX) and a figures/ sub‑folder. | | Makefile | Convenience commands (make data, make train, make test, etc.). | | pyproject.toml & setup.cfg | Package metadata and linting configuration (e.g., Black, flake8). | | requirements.txt | Pin‑down the exact Python dependencies for reproducibility. |

---

Getting started quickly

# 1. Install the tool (once)
pipx install cookiecutter-data-science

# 2. Create a new project called "my‑analysis"
ccds   # follow the prompts; give "my_analysis" as the module name

# 3. Jump into the new folder and run the first make target
cd my_analysis
make data   # placeholder – you can replace it with your own commands

The generated README.md inside the new folder explains the project‑specific workflow.

---

Extending / contributing

• The repository hosts the template itself and the ccds CLI.
• Development dependencies are listed in dev-requirements.txt.
• Run the test suite with pytest tests.
• Contributions are welcomed; see the online contributing guide.

---

TL;DR

ccds = a one‑command way to spin up a clean, well‑organized data‑science repository that includes everything from data folders to a starter docs site, making collaborative and reproducible work much smoother.