Project template

A simple template for research project repos. You can also use data science and reproducible science cookie cutters.

Project structure

This template contains the following folders and files. See README.md in each folder for more details and guidelines.

1. src for project source code (installed as editable package).
2. tests for unit tests.
3. data for raw & derived datasets.
4. libs for third-party or vendored packages.
5. models for trained models.
6. notebooks for (timestamped) experiment notebooks.
7. paper for manuscripts.
8. results for results (figures, tables, etc.)
9. notes for research notes.
10. workflow for workflow files and scripts.
11. dashboard for the local project status and ownership view.
12. .gitignore for temporary and generated files.

Python environment

This template uses uv for Python environment management. Run the setup script for initial configuration:

./setup.sh          # Install dependencies and configure environment

Key files

• .python-version — specifies the required Python release
• .venv/ — virtual environment directory (created by uv)
• pyproject.toml — project metadata and dependency declarations
• uv.lock — reproducible dependency snapshot (commit to version control)
• .envrc — optional direnv configuration

Common commands

uv add PACKAGE      # Add dependency
uv sync             # Install from lockfile
uv run script.py    # Run script in virtual environment

See Python environment setup for details.

Linting and formatting

ruff is included as a dev dependency. Use make lint to check for issues and make format to auto-format.

Pre-commit hooks

The setup script installs hooks when Git is using the repository's standard hook directory. To run every hook manually:

uv run pre-commit run --all-files

Common project commands

• make check — run formatting, linting, tests, and a workflow dry run
• make all — run the example Snakemake pipeline
• make dashboard — regenerate the local project status dashboard

Project dashboard

Update dashboard/status.toml after meaningful project work, then run make dashboard and open dashboard/index.html. The HTML file is generated locally and is not committed.