greenbook

Cost-benefit analysis primitives from the HM Treasury Green Book, in R.

What is the Green Book?

The Green Book is HM Treasury’s guidance on how to appraise and evaluate proposals involving UK public spending. It sets the rules every central-government department, devolved administration, and arm’s-length body follows when deciding whether a policy, programme, or capital project is worth funding. The latest edition was published in 2026.

The guidance covers six core areas:

• Discounting: the kinked Social Time Preference Rate (STPR), stepping from 3.5 percent for the first 30 years down to 1.0 percent beyond year 300.
• Real-terms appraisal: rebasing nominal cashflows using the GDP deflator at market prices.
• Optimism bias: standard uplifts on capital cost and works-duration estimates, by project category (Mott MacDonald 2002).
• Distributional analysis: iso-elastic weights on net benefits accruing to different income groups.
• Adjustments: the Marginal Excess Tax Burden (METB) on revenue raised through distortionary taxation.
• Monetised valuation: WELLBYs for wellbeing, Value of Preventing a Fatality (VPF) for life-safety, Quality-Adjusted Life Years (QALYs) for health, DESNZ carbon values for emissions.

The Green Book is supplemented by topic-specific guidance from HMT, DESNZ, DfT, and DHSC.

How is it used?

A practitioner appraising a public-spending option typically:

1. Builds a profile of costs and benefits in real terms, by year, in a fixed price base.
2. Discounts each year’s cashflow under the kinked STPR to compute net present value (NPV) and benefit-cost ratio (BCR).
3. Uplifts ex-ante cost estimates by an optimism bias percentage matched to the project category.
4. Applies distributional weights if the option is regressive across income groups.
5. Runs sensitivity tests on the largest assumptions and computes switching values.

Today this is mostly done in spreadsheets, with discount factors and parameter tables hand-typed from PDFs. greenbook puts the same primitives in R so an appraisal becomes code that can be tested, reviewed, and reproduced.

Why this package?

No existing R or Python package implements the Green Book. UK appraisal practitioners hand-roll the same discount factors and parameter lookups every time. The arithmetic is simple but the parameters change: STPR is kinked across six bands, optimism bias has a six-category schedule, DESNZ publishes a carbon path to 2100, METB shifted from 30 to 20 percent in 2018.

greenbook solves three problems:

• Reproducibility: every gb_appraisal carries vintage metadata for the parameter tables it used. gb_data_versions() shows source and last-updated date for every bundled table.
• Auditability: appraisals are code, not spreadsheets. Reviewers can run the tests, inspect the inputs, verify the outputs.
• Maintenance: when HM Treasury updates the Green Book, you bump the package and your existing appraisals stay aligned.

The package is pure computation: no network calls, no API keys. Bundled parameter tables in inst/extdata/ are refreshed via data-raw/ scripts.

Installation

# install.packages("greenbook")  # not yet on CRAN
# Development version:
devtools::install_github("charlescoverdale/greenbook")

Quick start

library(greenbook)

# 10-year cashflow: capex in years 0-2, benefits in years 3-9
costs    <- c(100, 50, 50, 0, 0, 0, 0, 0, 0, 0)
benefits <- c(0, 0, 0, 30, 30, 30, 30, 30, 30, 30)

# One-call full appraisal with optimism bias and METB
app <- gb_appraise(
  costs, benefits,
  ob = "non_standard_buildings", ob_mitigation = 0.5,
  metb = TRUE,
  base_year = 2024
)
summary(app)

# Equivalent annual net benefit
gb_eanc(app)

# Distributional weighting
gb_dist_weighted_npv(
  cashflow = rep(30, 5),
  recipient_income = rep(15000, 5),
  income_data = seq(10000, 100000, length.out = 10)
)

# Carbon emissions
gb_carbon_npv(rep(100, 7), 2024:2030, base_year = 2024)

# Wellbeing
gb_wellby(1, persons = 100, years = 5, base_year = 2024)

# Inspect bundled vintages
gb_data_versions()

Function inventory

Bundled data sources

Every parameter table is sourced from a published HMT, DfT, or DESNZ workbook. gb_data_versions() returns the full provenance.

data-raw/ contains the refresh scripts: each downloads the published workbook, parses the relevant sheet, and rewrites the bundled CSV.

Limitations

• VPF series interpolates between published anchors at 2 percent real GDP per head growth (TAG’s stated methodology). For sub-annual precision consult the TAG data book directly.
• Bundled DESNZ carbon path covers 2020 to 2050. The November 2023 publication extends to 2100; the 2050-2100 portion will be added in a future refresh.
• Long-horizon (50+ year) lower-rate sensitivity awaits the 2026 HMT discount-rate review.

Source documents

• HM Treasury Green Book (2026)
• Supplementary Green Book Guidance: discounting
• Supplementary Green Book Guidance: optimism bias
• Wellbeing Guidance for Appraisal: Supplementary Green Book Guidance, July 2021
• DESNZ Valuation of Energy Use and GHG Emissions for Appraisal, November 2023
• DfT Transport Analysis Guidance (TAG)

Citation

If you use greenbook in published work, please cite via:

citation("greenbook")

The package citation and the underlying HM Treasury Green Book are both returned.

Issues

Report bugs or request features at GitHub Issues.

Keywords

cost-benefit-analysis, appraisal, hm-treasury, green-book, public-policy, economics, discounting, npv, social-time-preference-rate, optimism-bias, distributional-weighting, wellby, value-of-statistical-life, carbon-valuation, desnz