nhse-rap-cookiecutter

NHS RAP Cookiecutter Template

A Cookiecutter template for creating standardised NHS England Reproducible Analytical Pipeline (RAP) projects.

Introduction

This template provides a standardised project structure for developing Reproducible Analytical Pipelines within NHS England. It includes pre-configured tooling for testing, linting, documentation, and dependency management following modern Python development practices.

What is RAP?

Reproducible Analytical Pipelines (RAP) is a set of tools, principles, and techniques to help you improve your analytical processes. With RAP, you leverage open-source tools to make your work more efficient, more reusable, and less error-prone.

The core RAP principles from the NHS RAP Community of Practice are:

Principle	Description
Automation	Minimise manual, error-prone steps through automation
Modular, reusable code	Write code in independent, loosely-coupled functions
Transparency	Publish code openly under appropriate licences
Open-source tools	Use Python, R, and other freely available languages
Version control	Use Git to track changes to code
Good coding practices	Follow standards like PEP8, use clear documentation
Testing	Implement automated tests for reliability
Peer review	Review code collaboratively to ensure quality

Learn more about RAP at the NHS RAP Community of Practice website.

Installation

This template requires Python 3.10 to 3.13. This package is not published to PyPI, so install directly from GitHub:

pipx (recommended for CLI tools):

pipx install git+https://github.com/nhsengland/nhse-rap-cookiecutter.git

See the pipx documentation for installation instructions.

uv:

uv tool install git+https://github.com/nhsengland/nhse-rap-cookiecutter.git

See the uv documentation for installation instructions.

pip:

pip install git+https://github.com/nhsengland/nhse-rap-cookiecutter.git

Quick Start

Generate a new project using the CLI tool:

nhs-rap-template

Or use the official cookiecutter command:

cookiecutter gh:nhsengland/nhse-rap-cookiecutter

Configuration Options

The template prompts for the following information:

Category	Option	Description	Choices
Project	project_name	Human-readable project name	Text
	repo_name	Repository name (default: lowercase project_name with underscores)	Text
	module_name	Python module name (default: repo_name with dashes converted to underscores)	Text
	description	Brief project description	Text
	author_name	Your full name	Text
	author_email	Your email address	Text
	organization_name	Your organisation name (default: NHS England)	Text
	team_name	Your team name	Text
	team_email	Team contact email	Text
	git_hosting_platform	Git hosting platform	github, gitlab, azure_devops, other
	repository_url	Repository URL (can override default)	Text
Python	python_version_number	Minimum Python version	3.10, 3.11, 3.12, 3.13
	environment_manager	Virtual environment tool	uv, venv, conda
Options	include_code_scaffold	Include example code modules	Yes, No
	layout	Package layout (flat = package at root, src = package under src/)	flat, src
	linting_and_formatting	Code quality tools	ruff, flake8+black+isort
	open_source_license	Project licence	MIT, Apache-2.0, GPL-3.0, No license file
	docs	Documentation tool	mkdocs, none

Note: All generated projects include core Python packages (pandas, numpy, matplotlib, seaborn, jupyter, etc.) and development tools (pytest, pre-commit, linting) by default. The dependency file format (pyproject.toml or environment.yml) is determined automatically based on your environment manager choice.

Generated Project Structure

your-project/
├── .github/
│   └── workflows/       # GitHub Actions CI (tests, lint, gitleaks, docs)
├── data/
│   ├── external/        # Data from third-party sources
│   ├── interim/         # Intermediate transformed data
│   ├── processed/       # Final canonical datasets
│   └── raw/             # Original immutable data
├── docs/                # MkDocs documentation with NHS styling
├── models/              # Trained models and predictions
├── notebooks/           # Jupyter notebooks for exploration
├── references/          # Data dictionaries and documentation
├── reports/
│   └── figures/         # Generated graphics
├── scripts/             # Setup and utility scripts
│   └── setup_repository.py  # Automated repository setup
├── tests/
│   ├── unittests/       # Unit tests (pytest)
│   └── e2e/             # End-to-end integration tests
├── your_module/         # Source code package (flat layout; or src/your_module/ with the src layout)
│   ├── __init__.py
│   ├── config.py        # Configuration management
│   ├── dataset.py       # Data loading and processing
│   ├── features.py      # Feature engineering
│   ├── plots.py         # Visualisation functions
│   └── modeling/
│       ├── train.py     # Model training
│       └── predict.py   # Model inference
├── .env                 # Environment variables (not tracked in git)
├── .pre-commit-config.yaml  # Pre-commit hooks configuration
├── badges.toml          # Optional project badges
├── CODE_OF_CONDUCT.md   # Community guidelines
├── LICENSE              # Project license
├── LICENSE-OGL          # Open Government License for docs
├── Makefile             # Convenience commands
├── mkdocs.yml           # Documentation configuration
├── OPEN_CODE_CHECKLIST.md  # NHS England standards for publishing code
├── README.md
├── pyproject.toml       # Project configuration and dependencies
└── setup.cfg            # Legacy tool configuration (flake8 only)

Key Features

Open Code Checklist

All generated projects include an Open Code Checklist (OPEN_CODE_CHECKLIST.md) to ensure compliance with NHS England standards before publishing code. The checklist covers:

• Licensing and documentation requirements
• Security checks for sensitive data, credentials, and git history
• Third-party tool compliance with NCSC guidelines
• Code quality and testing standards
• RAP assessment criteria

The checklist is also integrated into the project documentation for easy reference during development.

GitHub Actions CI/CD

For projects hosted on GitHub, the template generates a small, KISS set of workflows in .github/workflows/:

• tests.yml – runs the pytest suite on every push and pull request to main
• lint.yml – checks code style with your chosen linter (ruff, or flake8 + black + isort)
• gitleaks.yml – scans the repository for committed secrets
• docs.yml – builds and deploys the MkDocs site to GitHub Pages (only when docs are enabled)

The workflows adapt to your chosen environment manager (uv, venv, or conda), and matching status badges are added to the project README. For non-GitHub hosting (GitLab, Azure DevOps, etc.) the .github/ directory is omitted.

Project Layout

The template supports two package layouts via the layout prompt:

• flat (default) – the importable package sits at the project root (your_module/). This matches the Cookiecutter Data Science style.
• src – the importable package sits under a top-level src/ directory (src/your_module/), aligned with the NHS RAP community package template. The src layout helps avoid accidentally importing the package from the working directory instead of the installed version.

The import name (import your_module) is identical for both layouts, so usage, tests, and documentation are unaffected by the choice.

Using the Generated Project

After generating a project, use the automated setup script:

cd your-project-name
make setup

The setup script will:

• Initialize git repository with default branch
• Configure git remote with your repository URL
• Set up your Python environment (uv, venv, or conda)
• Install all project dependencies
• Install pre-commit hooks
• Create an initial commit

Alternatively, you can set up manually:

cd your-project-name
uv sync                      # Set up environment
uv run pre-commit install    # Install pre-commit hooks
make test                    # Run tests
make docs                    # Build documentation

Documentation

Full documentation: https://nhsengland.github.io/nhse-rap-cookiecutter

Development

See CONTRIBUTING.md for development setup and contribution guidelines.

uv run pytest tests/ -v                                              # Run tests
uv run pytest tests/ --cov=nhse_rap_cookiecutter --cov-report=term   # With coverage
uv run ruff format . && uv run ruff check .                                    # Format and lint
make docs-serve                                                                # Serve docs with live reload

Licence

Unless stated otherwise, the codebase is released under the MIT Licence. This covers both the codebase and any sample code in the documentation.

HTML and Markdown documentation is © Crown copyright and available under the terms of the Open Government 3.0 licence.

Acknowledgements

This template is based on Cookiecutter Data Science, adapted for NHS England RAP standards and modern Python tooling.