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. workflow for workflow files and scripts.
10. .gitignore for temporary and binary files to be ignored by git (LaTeX, Python, Jupyter, data files, etc.)

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 — direnv configuration for automatic venv activation

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. VS Code settings (.vscode/settings.json) enable format on save.

Pre-commit hooks

Install hooks to auto-run ruff and tests before commits:

uv add --dev pre-commit
uv run pre-commit install

For AI coding agents

Use the following instructions to initialize.

Commands:

• uv sync — install dependencies
• uv run pytest — run tests
• uv run ruff check . — lint
• uv run ruff format . — format
• make all — run Snakemake pipeline

Conventions:

• Write clean code accompanied by well-designed tests.
• Use type hints for all function signatures.
• Import project code as from project_name import ....
• Put reusable code in src/, not in notebooks or workflow scripts.
• Timestamp experiment folders: YYYYMMDD_description.