# Getting started with greenbook

    library(greenbook)

## Why greenbook

`greenbook` provides cost-benefit analysis primitives from the HM Treasury Green Book. The v0.1.0 release covers the discounting MVP: kinked STPR, discount factors, NPV, equivalent annual cost, and GDP-deflator rebasing.

All bundled parameter tables carry vintage metadata. Inspect with:

    gb_data_versions()
    #>         dataset
    #> 1 stpr_schedule
    #> 2  gdp_deflator
    #> 3 optimism_bias
    #> 4          metb
    #> 5        wellby
    #> 6           vpf
    #> 7          qaly
    #> 8 carbon_values
    #>                                                                                                                              source
    #> 1                                                         HM Treasury Green Book 2022 Annex A6 / supplementary discounting guidance
    #> 2 HM Treasury, GDP deflators at market prices (December 2025 Quarterly National Accounts release, calendar-year series, 2024 = 100)
    #> 3                                                HM Treasury Supplementary Green Book Guidance: Optimism Bias (Mott MacDonald 2002)
    #> 4                                                  HM Treasury Green Book 2022 chapter on real terms and Marginal Excess Tax Burden
    #> 5                                                                                  HMT Wellbeing Guidance for Appraisal (July 2021)
    #> 6           DfT Transport Analysis Guidance (TAG) data book v2.03FC (December 2025), Table A4.1.1, WTP element for fatal casualties
    #> 7                                                                      DHSC Supplementary Green Book Guidance + NICE HTA thresholds
    #> 8                          DESNZ Valuation of Energy Use and GHG Emissions for Appraisal (November 2023), Data Tables 1-19, Table 3
    #>   last_updated
    #> 1   2026-04-26
    #> 2   2026-04-26
    #> 3   2026-04-26
    #> 4   2026-04-26
    #> 5   2026-04-26
    #> 6   2026-04-26
    #> 7   2026-04-26
    #> 8   2026-04-26
    #>                                                                                                                                                                              notes
    #> 1                          Kinked STPR: 3.5/3.0/2.5/2.0/1.5/1.0 percent across bands at 30/75/125/200/300 years. Health and catastrophic-risk variants per supplementary guidance.
    #> 2 Outturn 1990-2024 from CGDP_Deflators_Qtrly_National_Accounts_December_2025_update.xlsx. Forecast years can be added via inflateR or the Spring Statement supplementary release.
    #> 3                                                                Indicative upper bounds for capex and duration uplift across six project categories. Values unchanged since 2003.
    #> 4                                                               Uplift on revenue raised through distortionary taxation. 20 percent in 2018 onwards (was 30 percent historically).
    #> 5                                                           WELLBY central value GBP 13000 in 2019 prices (low/central/high range). Convert to other base years via gb_deflator().
    #> 6                                               Anchor 2023 = GBP 2,474,341 (WTP component). Other years derived by 2 percent annual real GDP per head growth per TAG methodology.
    #> 7                                                            GBP 70k per QALY in 2024 prices for cross-government appraisal. NICE thresholds GBP 20k-30k retained for HTA context.
    #> 8                                     Single consolidated series (replacing historical traded / non-traded split). Low / central / high paths 2020-2050 in 2022 prices, GBP/tCO2e.

## The kinked STPR

The Green Book Social Time Preference Rate steps down at 30, 75, 125, 200, and 300 years. `gb_stpr()` returns the rate for any year:

    gb_stpr(c(10, 30, 31, 75, 76, 200, 300))
    #> [1] 0.035 0.035 0.030 0.030 0.025 0.020 0.015

Three variants are supported:

    gb_schedule_table()
    #>   year_from year_to standard health catastrophic
    #> 1         0      30    0.035 0.0150       0.0300
    #> 2        31      75    0.030 0.0129       0.0257
    #> 3        76     125    0.025 0.0107       0.0214
    #> 4       126     200    0.020 0.0086       0.0171
    #> 5       201     300    0.015 0.0064       0.0129
    #> 6       301    1000    0.010 0.0043       0.0086

## Discount factors

`gb_discount_factor()` applies the kinked schedule annually using `prod(1 + r_t)`:

    gb_discount_factor(0:5)
    #> [1] 1.0000000 0.9661836 0.9335107 0.9019427 0.8714422 0.8419732
    gb_discount_factor(c(0, 30, 31, 75, 76))
    #> [1] 1.00000000 0.35627841 0.34590137 0.09421377 0.09191588

The kink is correctly handled across band boundaries:

    df_30 <- gb_discount_factor(30)
    df_31 <- gb_discount_factor(31)
    df_31 / df_30  # 1 / 1.030 = 0.9709, the year-31 single-period factor
    #> [1] 0.9708738

## Net present value

A simple appraisal: capex of GBP 100 in year 0, annual benefits of GBP 30 from year 1 to year 9.

    costs <- c(100, rep(0, 9))
    benefits <- c(0, rep(30, 9))
    appraisal <- gb_npv(benefits - costs, base_year = 2024)
    appraisal
    #>
    #> ── Green Book appraisal ────────────────────────────────────────────────────────
    #> NPV (real, standard schedule): "GBP 128.2"
    #> Horizon: 10 years (year 0 to 9)
    #> Base year: 2024
    #> Vintage: Green Book "2022"

The result is a `gb_appraisal` object with full provenance. Use `summary()` for a more detailed view:

    summary(appraisal)
    #> Green Book appraisal
    #> --------------------
    #> NPV          : GBP 128.2
    #> Schedule     : standard
    #> Horizon      : 10 years (year 0 to 9)
    #> Base year    : 2024
    #> Vintage      : Green Book 2022
    #> Total inflow : GBP 270.0
    #> Total outflow: GBP -100.0

## Equivalent annual net cost

To compare options of different durations, annualise the NPV:

    gb_eanc(appraisal)
    #> [1] 16.8554

## Real-terms rebasing

`gb_real()` converts nominal values at year-of-occurrence prices to real values at a chosen base year:

    gb_real(nominal_values = c(100, 110, 120),
            year = 2020:2022,
            base_year = 2024)
    #> [1] 117.352 128.451 132.596

`gb_rebase()` does the same operation between two real-terms base years:

    gb_rebase(c(100, 200, 300), from = 2020, to = 2024)
    #> [1] 117.3520 234.7040 352.0561

`gb_deflator()` exposes the underlying factor:

    gb_deflator(from = 2020, to = 2024)
    #> [1] 1.17352

## What’s next

v0.2.0 adds optimism bias (Mott MacDonald upper bounds), distributional weights, and Marginal Excess Tax Burden. v0.3.0 ships the valuation library: WELLBY, VPF, QALY, DESNZ carbon values. See the package GitHub repository for the full roadmap.