greenbook: HM Treasury Green Book Cost-Benefit Analysis Primitives

Description

Implements cost-benefit analysis primitives from HM Treasury Green Book guidance: the kinked Social Time Preference Rate (STPR), discount factors, net present value, equivalent annual cost, and GDP-deflator rebasing. Pure computation, no network access. Bundled parameter tables carry vintage metadata for reproducibility.

Author(s)

Maintainer: Charles Coverdale charles.f.coverdale@gmail.com

See Also

Useful links:

• https://github.com/charlescoverdale/greenbook

• Report bugs at https://github.com/charlescoverdale/greenbook/issues

Apply an optimism bias uplift to a cost stream

Description

Applies an OB uplift, optionally with a mitigation factor that represents progress on risk identification and management: cost_with_ob = cost_baseline * (1 + ob_pct * (1 - mitigation)).

Usage

gb_apply_ob(values, ob_pct, mitigation = 0)

Arguments

Value

A numeric vector the same length as values, with the uplift applied.

References

HM Treasury (2003). Supplementary Green Book Guidance: Optimism Bias, Annex A2 on mitigation factors.

See Also

gb_optimism_bias(), gb_appraise().

Other optimism bias: gb_categories(), gb_optimism_bias()

Examples

costs <- c(100, 50, 50)
ob <- gb_optimism_bias("non_standard_buildings")
gb_apply_ob(costs, ob)
gb_apply_ob(costs, ob, mitigation = 0.5)

Full Green Book appraisal in one call

Description

Runs an end-to-end appraisal: optionally applies optimism bias to costs, optionally applies METB, computes NPV under the kinked STPR, and returns BCR alongside provenance.

Usage

gb_appraise(
  costs,
  benefits,
  years = NULL,
  schedule = "standard",
  ob = NULL,
  ob_dimension = "capex",
  ob_mitigation = 0,
  metb = FALSE,
  metb_rate = 0.2,
  base_year = NULL,
  vintage = "2022"
)

Arguments

Value

A gb_appraisal object with extra fields bcr, pv_costs, pv_benefits, costs, benefits, optimism_bias, metb_applied.

References

HM Treasury (2026). The Green Book: Central Government Guidance on Appraisal and Evaluation.

See Also

gb_npv(), gb_optimism_bias(), gb_metb(), gb_dist_weighted_npv().

Other appraisal: gb_compare(), gb_economic_case(), gb_place_based(), gb_progression(), gb_risk_register(), gb_sensitivity_ob(), gb_validate()

Examples

costs <- c(100, 50, 50, 0, 0, 0, 0, 0, 0, 0)
benefits <- c(0, 0, 0, 30, 30, 30, 30, 30, 30, 30)
app <- gb_appraise(costs, benefits, ob = "non_standard_buildings",
                   ob_mitigation = 0.5, base_year = 2024)
app

Net present value of an emissions path

Description

Multiplies an emissions vector (tCO2e per year) by the DESNZ carbon value at each year, then discounts under the kinked STPR. Returns a gb_appraisal object.

Usage

gb_carbon_npv(
  emissions,
  years,
  scenario = "central",
  schedule = "standard",
  base_year = NULL,
  sign = "cost"
)

Arguments

Value

A gb_appraisal object.

References

DESNZ (2023). Valuation of Energy Use and Greenhouse Gas Emissions for Appraisal (November 2023). HM Treasury (2022). The Green Book, on environmental valuation.

See Also

gb_carbon_value(), gb_npv().

Other carbon: gb_carbon_value()

Examples

# 100 tCO2e emitted each year from 2024 to 2030
emissions <- rep(100, 7)
years <- 2024:2030
gb_carbon_npv(emissions, years, base_year = 2024)

DESNZ carbon value for appraisal

Description

Returns the DESNZ Carbon Value for Appraisal in GBP per tonne of CO2-equivalent at the published 2022 base-year prices, from the November 2023 valuation. Three scenarios: low, central, high.

Usage

gb_carbon_value(year, scenario = "central", base_year = NULL)

Arguments

Details

DESNZ moved to a single consolidated series in November 2023, superseding the historical traded / non-traded split. Values are in 2022 prices. The November 2023 publication covers 2010 to 2100; the bundled subset is 2020 to 2050.

Value

Numeric vector of GBP per tCO2e values.

References

DESNZ (2023). Valuation of Energy Use and Greenhouse Gas Emissions for Appraisal (November 2023). Data tables 1-19, Table 3.

See Also

gb_carbon_npv().

Other carbon: gb_carbon_npv()

Examples

gb_carbon_value(2024)
gb_carbon_value(2020:2030)
gb_carbon_value(2030, scenario = "high")

Available optimism bias categories

Description

Returns the bundled OB category lookup as a data frame.

Usage

gb_categories()

Value

A data frame with columns category, description, capex_upper, duration_upper.

References

HM Treasury (2003). Supplementary Green Book Guidance: Optimism Bias.

See Also

gb_optimism_bias().

Other optimism bias: gb_apply_ob(), gb_optimism_bias()

Examples

gb_categories()

Compare multiple appraisal options

Description

Builds a side-by-side comparison of two or more gb_appraisal objects. Returns a gb_comparison with a ranked summary table and the preferred option under both NPV and BCR criteria.

Usage

gb_compare(..., by = "npv")

Arguments

Details

Every Green Book economic case must compare at least Do Minimum against one or more Do Something options. gb_compare() standardises the comparison: NPV, BCR, EANC, PV costs, PV benefits, and rank under both NPV and BCR. The summary() method renders a one-page table suitable for a Five Case Model economic case.

Value

A gb_comparison object: a list with class c("gb_comparison", "list") and elements options, summary_table, preferred_npv, preferred_bcr, by.

References

HM Treasury (2022). The Green Book: Central Government Guidance on Appraisal and Evaluation, chapter on options analysis.

See Also

gb_appraise(), gb_economic_case().

Other appraisal: gb_appraise(), gb_economic_case(), gb_place_based(), gb_progression(), gb_risk_register(), gb_sensitivity_ob(), gb_validate()

Examples

do_minimum <- gb_appraise(c(50, 0, 0, 0, 0), c(0, 20, 20, 20, 20))
do_max <- gb_appraise(c(150, 0, 0, 0, 0), c(0, 50, 50, 50, 50))
gb_compare(do_minimum = do_minimum, do_max = do_max)

Cost per unit delivered

Description

Computes a cost-effectiveness ratio: total real cost (PV) per unit of monetised or non-monetised output. Standard cross-scheme comparator used by HM Treasury reviewers.

Usage

gb_cost_per_unit(appraisal, units_delivered, unit = "unit")

Arguments

Value

Numeric scalar: PV cost / units delivered, in GBP per unit.

See Also

gb_appraise().

Other reporting: gb_headline(), gb_to_excel(), gb_to_latex(), gb_to_word()

Examples

app <- gb_appraise(c(100, 0, 0, 0, 0), c(0, 0, 0, 0, 0))
gb_cost_per_unit(app, units_delivered = 50, unit = "QALY")

Vintage of bundled parameter tables

Description

Returns a data frame describing the source and last-updated date of every CSV bundled in ⁠inst/extdata/⁠. Critical for reproducibility: every appraisal can record which vintage of Green Book parameters it used.

Usage

gb_data_versions()

Value

A data frame with columns dataset, source, last_updated, notes.

See Also

gb_schedule_table().

Other lookups: gb_schedule_table()

Examples

gb_data_versions()

GDP deflator factor between two years

Description

Returns the multiplicative factor to convert a value expressed in year from prices to year to prices, using the bundled UK GDP deflator at market prices (ONS series). Multiply a nominal value from year from by this factor to express it in year to.

Usage

gb_deflator(from, to, source = "bundled")

Arguments

Value

A numeric scalar: the deflator factor.

References

Office for National Statistics. GDP deflator at market prices (series YBGB), updated quarterly. HM Treasury publishes the deflator series alongside the OBR forecast.

See Also

gb_real(), gb_rebase().

Other deflator: gb_real(), gb_rebase()

Examples

gb_deflator(from = 2020, to = 2024)

Apply discount factors to a stream

Description

Apply discount factors to a stream

Usage

gb_discount(values, years = seq_along(values) - 1L, schedule = "standard")

Arguments

Value

A numeric vector of discounted (present-value) cashflows.

References

HM Treasury (2022). The Green Book, Annex A6.

See Also

gb_discount_factor(), gb_npv().

Other discounting: gb_discount_factor(), gb_eanc(), gb_npv(), gb_stpr()

Examples

gb_discount(c(0, 100, 100, 100))

Discount factor under the kinked STPR

Description

Returns the present-value discount factor for each year, applying the kinked Social Time Preference Rate schedule annually.

Usage

gb_discount_factor(years, schedule = "standard", base_year = 0L)

Arguments

Details

The discount factor at year t is computed as the reciprocal of the cumulative product of (1 + r_k) for periods ⁠k = 1, ..., t⁠, where r_k is the STPR for year k. This handles the kinked schedule correctly across band transitions (e.g. year 30 to year 31). Within a single band, the closed-form annuity factor (1 - (1 + r)^(-n)) / r agrees with sum(gb_discount_factor(1:n)) to machine precision.

Value

A numeric vector of discount factors. 1 for years == base_year.

References

HM Treasury (2022). The Green Book, Annex A6.

HM Treasury (2003). Green Book Supplementary Guidance: Discounting.

See Also

gb_stpr(), gb_npv(), gb_eanc().

Other discounting: gb_discount(), gb_eanc(), gb_npv(), gb_stpr()

Examples

gb_discount_factor(0:5)
gb_discount_factor(c(0, 30, 31, 75, 76))

Distributional weight for a recipient income

Description

Returns the Green Book distributional weight applied to net benefits accruing to a recipient at income income, relative to a reference income (median by default), under iso-elastic utility:

Usage

gb_dist_weight(income, eta = 1.3, reference = "median", income_data = NULL)

Arguments

Details

w_i = (y_{ref} / y_i) ^ \eta

Default eta = 1.3 per HM Treasury Green Book Annex A3. Higher eta places greater weight on lower-income recipients; sensitivity tests at eta = 0.8 and eta = 2.0 are conventional.

Value

A numeric vector of weights, same length as income.

References

HM Treasury (2022). The Green Book, Annex A3 on distributional analysis.

Acland, D. and Greenberg, D.H. (2024). The Elasticity of Marginal Utility of Income for Distributional Weighting and Social Discounting: A Meta-Analysis. Journal of Benefit-Cost Analysis.

See Also

gb_dist_weighted_npv().

Other distributional: gb_dist_weighted_npv()

Examples

# Weights across deciles of a stylised income distribution
income_deciles <- seq(10000, 100000, length.out = 10)
gb_dist_weight(income_deciles)

Distributionally-weighted net present value

Description

Applies recipient-income distributional weights to a cashflow before discounting under the STPR.

Usage

gb_dist_weighted_npv(
  cashflow,
  recipient_income,
  eta = 1.3,
  schedule = "standard",
  reference = "median",
  income_data = NULL,
  vintage = "2022",
  base_year = NULL
)

Arguments

Value

A gb_appraisal object with extra fields weights, eta, and unweighted_npv.

References

HM Treasury (2022). The Green Book, Annex A3 on distributional analysis.

See Also

gb_dist_weight(), gb_npv().

Other distributional: gb_dist_weight()

Examples

# 5-year benefit stream of GBP 30 going to a low-decile recipient
gb_dist_weighted_npv(
  cashflow = rep(30, 5),
  recipient_income = rep(15000, 5),
  income_data = seq(10000, 100000, length.out = 10)
)

Equivalent annual net cost (or benefit)

Description

Converts a present value to an annualised equivalent over a fixed horizon under the STPR. Used to compare options of different durations.

Usage

gb_eanc(npv, years, schedule = "standard")

Arguments

Value

A numeric scalar: the equivalent annual amount in real terms, base year aligned with the input.

References

HM Treasury (2022). The Green Book, Annex A on appraisal: equivalent annual cost.

See Also

gb_npv(), gb_appraise().

Other discounting: gb_discount(), gb_discount_factor(), gb_npv(), gb_stpr()

Examples

app <- gb_npv(c(-100, 30, 30, 30, 30, 30))
gb_eanc(app)

Render an appraisal as a Five Case Model economic case

Description

Wraps a gb_appraisal with the structural sections HMT business case guidance expects in the Economic Case (the second of the five cases in the Five Case Model: Strategic, Economic, Commercial, Financial, Management).

Usage

gb_economic_case(
  appraisal,
  critical_success_factors = NULL,
  options_considered = NULL,
  non_monetised_impacts = NULL,
  recommendation = NULL,
  vfm_statement = NULL
)

Arguments

Details

The Five Case Model is HM Treasury's standard structure for business cases. The Economic Case is the part where Green Book appraisal sits: monetised costs and benefits, non-monetised impacts, switching values, sensitivity tests, value for money judgment, recommended option. gb_economic_case wraps the appraisal with the sections a reviewer expects to see.

Value

A gb_economic_case object.

References

HM Treasury (2018). Guide to Developing the Project Business Case (Five Case Model).

See Also

gb_appraise(), gb_compare().

Other appraisal: gb_appraise(), gb_compare(), gb_place_based(), gb_progression(), gb_risk_register(), gb_sensitivity_ob(), gb_validate()

Examples

app <- gb_appraise(c(100, 0, 0, 0, 0), c(0, 30, 30, 30, 30))
gb_economic_case(
  app,
  critical_success_factors = c("Strategic fit", "Value for money", "Achievability"),
  options_considered = c("Do nothing", "Do minimum", "Do maximum"),
  recommendation = "Do maximum: positive NPV and BCR > 1.5"
)

One-page headline summary of an appraisal

Description

Returns the headline numbers a Green Book reviewer or steering committee expects: NPV, BCR, EANC, payback period, optimism bias applied, vintage. Suitable for a slide or executive summary.

Usage

gb_headline(appraisal)

Arguments

Value

A gb_headline object with elements npv, bcr, eanc, payback_year, optimism_bias, metb_applied, vintage, base_year, horizon.

See Also

gb_appraise(), gb_to_latex(), gb_to_excel().

Other reporting: gb_cost_per_unit(), gb_to_excel(), gb_to_latex(), gb_to_word()

Examples

app <- gb_appraise(c(100, 0, 0, 0, 0), c(0, 30, 30, 30, 30))
gb_headline(app)

Apply Marginal Excess Tax Burden to public expenditure

Description

Uplifts net public expenditure (or revenue raised) to reflect the welfare cost of distortionary taxation. Default rate is 20 percent per Green Book 2022 / 2026. The historic value (2003) was 30 percent.

Usage

gb_metb(values, rate = 0.2, vintage = NULL)

Arguments

Details

The METB captures the welfare loss arising from raising one extra GBP of revenue through the tax system, beyond the GBP itself. Estimates depend on the elasticity of taxable income, the marginal tax rate, and the distortionary margin. The Green Book reduced the headline value from 30 percent (2003) to 20 percent (2018) in light of post-2008 evidence.

Value

A numeric vector the same length as values, with the METB uplift applied.

References

HM Treasury (2022). The Green Book: Central Government Guidance on Appraisal and Evaluation, chapter on real terms and the marginal excess tax burden.

See Also

gb_appraise().

Examples

gb_metb(c(100, 200))
gb_metb(c(100, 200), vintage = "2003")

Net present value

Description

Computes the net present value of a cashflow stream under the Green Book STPR. Returns a gb_appraisal object carrying the NPV, the input cashflow, the discount factors, the schedule used, and methodology vintage.

Usage

gb_npv(
  cashflow,
  years = NULL,
  schedule = "standard",
  base_year = NULL,
  vintage = "2022"
)

Arguments

Value

A gb_appraisal object: a list with class c("gb_appraisal", "list") and elements npv, cashflow, years, pv, schedule, base_year, vintage.

References

HM Treasury (2022). The Green Book, chapter on appraisal and the Annex on discounting.

See Also

gb_appraise(), gb_eanc(), gb_dist_weighted_npv(), gb_carbon_npv().

Other discounting: gb_discount(), gb_discount_factor(), gb_eanc(), gb_stpr()

Examples

costs    <- c(100, 50, 50, 0, 0, 0, 0, 0, 0, 0)
benefits <- c(0, 0, 0, 30, 30, 30, 30, 30, 30, 30)
gb_npv(benefits - costs)

Optimism bias upper bound for a project category

Description

Returns the indicative upper-bound optimism bias percentage from HM Treasury Supplementary Green Book Guidance: Optimism Bias (Mott MacDonald 2002, Annex A1). The upper bound is the starting value for ex-ante uplift; mitigation factors reduce it as project definition matures through SOC, OBC, and FBC stages.

Usage

gb_optimism_bias(category, dimension = "capex")

Arguments

Value

Numeric scalar: the upper-bound percentage as a decimal (e.g. 0.51 for 51 percent).

References

HM Treasury (2003). Supplementary Green Book Guidance: Optimism Bias.

Mott MacDonald (2002). Review of Large Public Procurement in the UK. Report commissioned by HM Treasury.

See Also

gb_apply_ob(), gb_categories(), gb_appraise().

Other optimism bias: gb_apply_ob(), gb_categories()

Examples

gb_optimism_bias("non_standard_buildings")
gb_optimism_bias("standard_civil_engineering", dimension = "duration")

Aggregate sub-projects into a place-based business case

Description

Combines multiple gb_appraisal objects into a single portfolio appraisal. Introduced in the 2026 Green Book as a recognised business case structure for places (city deals, devolved settlements, regional packages) where individual projects are interdependent.

Usage

gb_place_based(..., place = NULL, synergy = 0)

Arguments

Value

A gb_place_based object with elements projects, place, aggregate_npv, aggregate_bcr, per_project, synergy.

References

HM Treasury (2026). The Green Book, on place-based business cases.

See Also

gb_appraise(), gb_compare().

Other appraisal: gb_appraise(), gb_compare(), gb_economic_case(), gb_progression(), gb_risk_register(), gb_sensitivity_ob(), gb_validate()

Examples

transport <- gb_appraise(c(100, 0, 0, 0, 0), c(0, 30, 30, 30, 30))
housing <- gb_appraise(c(50, 0, 0, 0, 0), c(0, 20, 20, 20, 20))
skills <- gb_appraise(c(20, 20, 0, 0, 0), c(0, 0, 15, 15, 15))
gb_place_based(transport = transport, housing = housing,
               skills = skills, place = "Example City")

Track an appraisal across SOC, OBC, and FBC stages

Description

Builds a gb_progression showing how NPV, BCR, and key parameters evolve across the three Green Book business case stages: Strategic Outline Case (SOC), Outline Business Case (OBC), and Full Business Case (FBC). Useful for both authoring a multi-stage appraisal and reviewing how figures have moved between gateway approvals.

Usage

gb_progression(soc, obc = NULL, fbc = NULL)

Arguments

Details

At each stage, optimism bias mitigation typically increases as project definition firms up. Cost estimates converge towards base-cost reality; benefit estimates may also shift as evidence accumulates. The evolution table makes the trajectory visible.

Value

A gb_progression object with elements stages, evolution (data frame), delta_npv, delta_costs.

References

HM Treasury (2018). Guide to Developing the Project Business Case (Green Book supplementary guidance).

See Also

gb_appraise().

Other appraisal: gb_appraise(), gb_compare(), gb_economic_case(), gb_place_based(), gb_risk_register(), gb_sensitivity_ob(), gb_validate()

Examples

soc <- gb_appraise(c(100, 0, 0, 0, 0), c(0, 30, 30, 30, 30),
                   ob = "non_standard_buildings", ob_mitigation = 0)
obc <- gb_appraise(c(100, 0, 0, 0, 0), c(0, 30, 30, 30, 30),
                   ob = "non_standard_buildings", ob_mitigation = 0.5)
fbc <- gb_appraise(c(100, 0, 0, 0, 0), c(0, 30, 30, 30, 30),
                   ob = "non_standard_buildings", ob_mitigation = 0.9)
gb_progression(soc, obc, fbc)

Value of a Quality-Adjusted Life Year

Description

Returns the QALY value in GBP at the published base year. The DHSC supplementary Green Book guidance specifies GBP 70,000 per QALY in 2024 prices for cross-government appraisal. NICE Health Technology Assessment uses lower thresholds (GBP 20,000 to GBP 30,000 per QALY).

Usage

gb_qaly(qalys, scenario = "dhsc", base_year = NULL)

Arguments

Value

A numeric scalar or vector: monetised value in GBP.

References

DHSC Supplementary Green Book Guidance on health appraisal. NICE methods guides for technology appraisal.

See Also

gb_wellby(), gb_vpf().

Other valuation: gb_vpf(), gb_wellby()

Examples

gb_qaly(1)
gb_qaly(1, scenario = "nice_upper")

Convert nominal values to real

Description

Converts nominal values at year-of-occurrence prices to real values at a chosen base year, using the bundled GDP deflator.

Usage

gb_real(nominal_values, year, base_year, source = "bundled")

Arguments

Value

A numeric vector of real values, in base_year prices.

References

HM Treasury (2022). The Green Book, chapter on real terms and price-base alignment.

See Also

gb_deflator(), gb_rebase().

Other deflator: gb_deflator(), gb_rebase()

Examples

gb_real(nominal_values = c(100, 110, 120),
        year = 2020:2022,
        base_year = 2024)

Rebase a real-terms series to a different base year

Description

Multiplies values currently in from-year real prices by the deflator factor to express them in to-year real prices.

Usage

gb_rebase(values, from, to)

Arguments

Value

A numeric vector of values in to-year real prices.

References

HM Treasury (2022). The Green Book, chapter on real terms and price-base alignment.

See Also

gb_deflator(), gb_real().

Other deflator: gb_deflator(), gb_real()

Examples

gb_rebase(c(100, 200, 300), from = 2020, to = 2024)

Build a risk register with monetised exposure

Description

Creates a gb_risk_register from a data frame of project risks. Computes expected loss per risk (probability times impact) and aggregate exposure. Optionally applied to a gb_appraisal to produce a risk-adjusted NPV.

Usage

gb_risk_register(risks, appraisal = NULL)

Arguments

Details

HM Treasury business case guidance requires a risk register with monetised exposure for the OBC and FBC stages. gb_risk_register standardises the structure: every risk has an id, a probability, a monetary impact, and an expected loss. Aggregation is by category if the column is present.

Value

A gb_risk_register object.

References

HM Treasury (2018). The Orange Book: Management of Risk - Principles and Concepts.

See Also

gb_appraise().

Other appraisal: gb_appraise(), gb_compare(), gb_economic_case(), gb_place_based(), gb_progression(), gb_sensitivity_ob(), gb_validate()

Examples

risks <- data.frame(
  id = c("R1", "R2", "R3"),
  description = c("Planning delay", "Cost overrun", "Lower demand"),
  category = c("schedule", "cost", "demand"),
  probability = c(0.30, 0.50, 0.20),
  impact_gbp = c(2e6, 5e6, 10e6)
)
gb_risk_register(risks)

Tibble of the STPR schedule

Description

Returns the bundled STPR kinked schedule as a data frame: one row per band, columns year_from, year_to, and (depending on schedule) either all three rate variants or just the requested one.

Usage

gb_schedule_table(schedule = NULL)

Arguments

Value

A data frame.

See Also

gb_stpr(), gb_data_versions().

Other lookups: gb_data_versions()

Examples

gb_schedule_table()
gb_schedule_table("health")

Optimism bias sensitivity sweep

Description

Recomputes an appraisal across a vector of optimism bias mitigation factors. Convenience wrapper for the standard HMT OB sensitivity test required at SOC, OBC, and FBC stages.

Usage

gb_sensitivity_ob(
  costs,
  benefits,
  ob,
  mitigations = c(0, 0.25, 0.5, 0.75, 1),
  ...
)

Arguments

Value

A gb_sensitivity_ob object: a list with elements mitigations, npv, bcr, costs_pv.

See Also

gb_appraise(), gb_apply_ob().

Other appraisal: gb_appraise(), gb_compare(), gb_economic_case(), gb_place_based(), gb_progression(), gb_risk_register(), gb_validate()

Examples

costs <- c(100, 50, 50, 0, 0, 0, 0, 0, 0, 0)
benefits <- c(0, 0, 0, 30, 30, 30, 30, 30, 30, 30)
gb_sensitivity_ob(costs, benefits, ob = "non_standard_buildings")

Social Time Preference Rate

Description

Returns the HM Treasury Green Book Social Time Preference Rate (STPR) for a vector of years from a base year. The schedule is kinked: the rate steps down at 30, 75, 125, 200, and 300 years. Three variants are supported.

Usage

gb_stpr(years, schedule = "standard")

Arguments

Details

The STPR is composed of pure time preference plus a wealth-effect adjustment for expected per-capita consumption growth. The kink reflects increasing uncertainty over the constituent parameters at longer horizons.

Value

A numeric vector of discount rates (decimals, e.g. 0.035 for 3.5 percent), one per element of years.

References

HM Treasury (2022). The Green Book: Central Government Guidance on Appraisal and Evaluation, Annex A6.

HM Treasury (2003). Green Book Supplementary Guidance: Discounting.

See Also

gb_discount_factor(), gb_discount(), gb_npv().

Other discounting: gb_discount(), gb_discount_factor(), gb_eanc(), gb_npv()

Examples

gb_stpr(0:5)
gb_stpr(c(10, 30, 31, 75, 76))
gb_stpr(c(10, 30, 31, 75, 76), schedule = "health")

Export an appraisal to Excel

Description

Writes a multi-sheet workbook: summary, cashflow, present values, provenance.

Usage

gb_to_excel(appraisal, file)

Arguments

Details

Requires the openxlsx package (in Suggests). Install with install.packages("openxlsx") if not present.

Value

Invisibly, the file path.

See Also

gb_to_latex(), gb_to_word().

Other reporting: gb_cost_per_unit(), gb_headline(), gb_to_latex(), gb_to_word()

Examples

if (requireNamespace("openxlsx", quietly = TRUE)) {
  app <- gb_appraise(c(100, 0, 0, 0, 0), c(0, 30, 30, 30, 30))
  tmp <- tempfile(fileext = ".xlsx")
  gb_to_excel(app, tmp)
}

Render an appraisal as a LaTeX table

Description

Render an appraisal as a LaTeX table

Usage

gb_to_latex(appraisal, caption = NULL, label = NULL)

Arguments

Value

A character scalar containing a LaTeX tabular environment. Wrap in ⁠\\begin{table}...\\end{table}⁠ for a floating table.

See Also

gb_to_excel().

Other reporting: gb_cost_per_unit(), gb_headline(), gb_to_excel(), gb_to_word()

Examples

app <- gb_appraise(c(100, 0, 0, 0, 0), c(0, 30, 30, 30, 30))
cat(gb_to_latex(app, caption = "Worked example"))

Export an appraisal to Word

Description

Writes a one-page Word document with the appraisal headline and cashflow table.

Usage

gb_to_word(appraisal, file)

Arguments

Details

Requires the officer and flextable packages (both in Suggests).

Value

Invisibly, the file path.

See Also

gb_to_latex(), gb_to_excel().

Other reporting: gb_cost_per_unit(), gb_headline(), gb_to_excel(), gb_to_latex()

Examples

if (requireNamespace("officer", quietly = TRUE) &&
    requireNamespace("flextable", quietly = TRUE)) {
  app <- gb_appraise(c(100, 0, 0, 0, 0), c(0, 30, 30, 30, 30))
  tmp <- tempfile(fileext = ".docx")
  gb_to_word(app, tmp)
}

Lint a Green Book appraisal for common errors

Description

Inspects a gb_appraisal for sign-convention errors, base-year alignment, schedule plausibility, and other common authoring mistakes. Returns a structured report classifying each check as pass, warning, or error.

Usage

gb_validate(appraisal)

Arguments

Details

Checks performed:

• Cashflow length matches years length

• Schedule is one of the valid options

• Base year is plausible (1900 to 2100)

• Vintage matches a recognised Green Book edition

• If costs and benefits are present (from gb_appraise()), costs are non-negative and benefits are non-negative

• NPV is finite (no NaN / Inf)

• PV costs and PV benefits are consistent with NPV

Warnings flag suspicious patterns: missing base year, unusual optimism bias values, METB outside 0 to 50 percent, very long horizons (> 100 years).

Value

A gb_validation object with elements pass, errors, warnings, info, and n_checks.

See Also

gb_appraise().

Other appraisal: gb_appraise(), gb_compare(), gb_economic_case(), gb_place_based(), gb_progression(), gb_risk_register(), gb_sensitivity_ob()

Examples

app <- gb_appraise(c(100, 0, 0, 0, 0), c(0, 30, 30, 30, 30))
gb_validate(app)

Value of Preventing a Fatality

Description

Returns the DfT TAG-published Value of Preventing a Fatality (VPF) in real terms for a given year. The published 2024 value is GBP 2.153 million; the historical 2018 value (DfT TAG) is GBP 1.958 million. Years between bundled publication dates are filled by an annual real uplift of approximately 2 percent (proxy for real GDP per head growth).

Usage

gb_vpf(year = 2024, series = "central")

Arguments

Value

Numeric scalar: the VPF in GBP at year year prices.

References

Department for Transport. Transport Analysis Guidance (TAG) data book.

See Also

gb_wellby(), gb_qaly().

Other valuation: gb_qaly(), gb_wellby()

Examples

gb_vpf()
gb_vpf(2018)

Wellbeing valuation in GBP (WELLBY)

Description

Monetises a life-satisfaction change as Well-being Adjusted Life Years (WELLBYs) per HMT Wellbeing Guidance for Appraisal (July 2021). One WELLBY equals a one-point change in life satisfaction on a 0 to 10 scale, for one person, for one year. The central published unit value is GBP 13,000 in 2019 prices, with a low-high sensitivity of GBP 10,000 to GBP 16,000.

Usage

gb_wellby(
  life_satisfaction_change,
  persons,
  years = 1,
  base_year = NULL,
  scenario = "central"
)

Arguments

Value

A numeric scalar or vector: the WELLBY value in GBP at the requested base year.

References

HM Treasury (2021). Wellbeing Guidance for Appraisal: Supplementary Green Book Guidance.

See Also

gb_vpf(), gb_qaly().

Other valuation: gb_qaly(), gb_vpf()

Examples

# 1-point lift in life satisfaction for 100 people for 5 years
gb_wellby(1, persons = 100, years = 5)
gb_wellby(1, persons = 100, years = 5, scenario = "low")
# Express in 2024 prices
gb_wellby(1, persons = 100, years = 5, base_year = 2024)