cookiecutter-data-science README

The project's README from github.com/drivendataorg/cookiecutter-data-science. As one markdown file: README.md.

Cookiecutter Data Science

A logical, reasonably standardized but flexible project structure for doing and sharing data science work.

PyPI - Version PyPI - Python Version tests

Cookiecutter Data Science (CCDS) is a tool for setting up a data science project template that incorporates best practices. To learn more about CCDS's philosophy, visit the project homepage.

ℹ️ Cookiecutter Data Science v2 has changed from v1. It now requires installing the new cookiecutter-data-science Python package, which extends the functionality of the cookiecutter templating utility. Use the provided ccds command-line program instead of cookiecutter.

Installation

Cookiecutter Data Science v2 requires Python 3.9+. Since this is a cross-project utility application, we recommend installing it with pipx. Installation command options:

# With pipx from PyPI (recommended)
pipx install cookiecutter-data-science

# With pip from PyPI
pip install cookiecutter-data-science

# With conda from conda-forge (coming soon)
# conda install cookiecutter-data-science -c conda-forge

Starting a new project

To start a new project, run:

ccds

The resulting directory structure

The directory structure of your new project will look something like this (depending on the settings that you choose):

├── LICENSE            <- Open-source license if one is chosen
├── Makefile           <- Makefile with convenience 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 mkdocs project; see www.mkdocs.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`.
│
├── pyproject.toml     <- Project configuration file with package metadata for 
│                         {{ cookiecutter.module_name }} and configuration for tools like black
│
├── 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.cfg          <- Configuration file for flake8
│
└── {{ cookiecutter.module_name }}   <- Source code for use in this project.
    │
    ├── __init__.py             <- Makes {{ cookiecutter.module_name }} a Python module
    │
    ├── config.py               <- Store useful variables and configuration
    │
    ├── dataset.py              <- Scripts to download or generate data
    │
    ├── features.py             <- Code to create features for modeling
    │
    ├── modeling                
    │   ├── __init__.py 
    │   ├── predict.py          <- Code to run model inference with trained models          
    │   └── train.py            <- Code to train models
    │
    └── plots.py                <- Code to create visualizations

Using unreleased changes

By default, ccds will use the project template version that corresponds to the installed ccds package version (e.g., if you have installed ccds v2.0.1, you'll use the v2.0.1 version of the project template by default). To use a specific version of the project template, use the -c/--checkout flag to provide the branch (or tag or commit hash) of the version you'd like to use. For example to use the project template from the master branch:

ccds -c master

Using v1

If you want to use the old v1 project template, you need to have either the cookiecutter-data-science package or cookiecutter package installed. Then, use either command-line program with the -c v1 option:

ccds https://github.com/drivendataorg/cookiecutter-data-science -c v1
# or equivalently
cookiecutter https://github.com/drivendataorg/cookiecutter-data-science -c v1

Contributing

We welcome contributions! See the docs for guidelines.

Installing development requirements

pip install -r dev-requirements.txt

Running the tests

pytest tests

cookiecutter-data-science (drivendataorg/cookiecutter-data-science)

Searching Database…

10.1K ·GitHub
Cookiecutter-data-science
What is this?This is Cookiecutter Data Science (CCDS), a tool that scaffolds new data science projects from a template that bakes in best practices, so every project gets a logical, standardized but flexible structure.
Is this a library my code imports, or a tool I run?A command-line tool, not a library. You install the cookiecutter-data-science Python package and use its ccds program to generate project skeletons — nothing is imported into your code.
How do I get it and start a new project?Install it with pipx — the recommended way for a cross-project CLI utility — then run ccds to create a project; it asks for your settings and generates the folder structure.
Do I need anything installed before running it?Python 3.9 or newer is the hard requirement for v2. pipx, the suggested installer, comes from the Python ecosystem as well.
v2 changed a lot from v1 — can I still get the old template, or pin a specific template version?By default ccds uses the template matching your installed package version. Pass -c/--checkout with a branch, tag, or commit to pick another, or -c v1 to get the old v1 layout.
What does a project generated with ccds actually contain?A ready-made directory structure laid out for data science work. The exact folders depend on the settings you choose during generation, so each project is slightly tailored.
What is the relationship to cookiecutter itself?Cookiecutter is a separate project-templating utility. CCDS v2 ships as its own package, cookiecutter-data-science, which extends cookiecutter's functionality — you run its ccds command instead.
Why bother with a standardized project structure?A logical, reasonably standardized but flexible layout makes data science work easier to do and to share, and keeps projects consistent. The README points to the project homepage for the full philosophy.
What are similar projects?cookiecutter, yeoman, cookiecutter-django, agentic-playwright, dvc, rendercv, rust-clippy, huashu-excel
Which topics is it in?scaffolding, boilerplate, template, best-practices, data-science, utility, command-line-tool, machine-learning, tool, ai, cli, python
Creator
drivendataorg
Size
1.3 MB
Stars
10.1K
Updated
CommitOct 03Releasev2.3.0Jul 24
Age
10y
Commits · 90 Days