Package 'obr'

Title: Access 'Office for Budget Responsibility' Data
Description: Provides clean, tidy access to data published by the 'Office for Budget Responsibility' ('OBR'), the UK's independent fiscal watchdog. Covers the Public Finances Databank (outturn for PSNB, PSND, receipts, and expenditure since 1946), the Historical Official Forecasts Database (every 'OBR' forecast since 2010), the Economic and Fiscal Outlook detailed forecast tables (five-year projections from the latest Budget), the Welfare Trends Report (incapacity benefit spending and caseloads), and the Fiscal Risks and Sustainability Report (50-year state pension projections). All returned objects carry provenance metadata recording the source URL, publication vintage, retrieval time, and file fingerprint, so analyses can be audited and reproduced. Data is downloaded from the 'OBR' on first use and cached locally for subsequent calls. Data is sourced from the 'OBR' website <https://obr.uk>.
Authors: Charles Coverdale [aut, cre]
Maintainer: Charles Coverdale <[email protected]>
License: MIT + file LICENSE
Version: 0.5.0
Built: 2026-05-12 09:51:07 UTC
Source: https://github.com/charlescoverdale/obr

Help Index

Subset an obr_tbl, preserving provenance

Description

Standard data.frame subsetting drops the obr_tbl class. This method preserves it (and the provenance attributes) when the result is still a data.frame.

Usage

## S3 method for class 'obr_tbl'
x[...]

Arguments

x

An obr_tbl.
...

Subsetting arguments passed to [⁠[.data.frame⁠].

Value

An obr_tbl if the subset is two-dimensional, otherwise the underlying vector.

Coerce an obr_tbl to a plain data.frame

Description

Strips the provenance attributes and the obr_tbl class so the result interacts smoothly with packages that dispatch on data.frame directly.

Usage

## S3 method for class 'obr_tbl'
as.data.frame(x, ...)

Arguments

x

An obr_tbl.
...

Unused.

Value

A plain data.frame with no provenance.

Clear cached OBR files

Description

Deletes all files downloaded and cached by the obr package. The next function call will re-download fresh data from the OBR website.

Usage

clear_cache()

Value

Invisibly returns NULL.

Examples

op <- options(obr.cache_dir = tempdir())
clear_cache()
options(op)

Get EFO economy projections

Description

Downloads (and caches) the OBR Economic and Fiscal Outlook Detailed Forecast Tables - Economy file and returns quarterly economic projections for a chosen measure in tidy long format.

Usage

get_efo_economy(
  measure = c("inflation", "labour", "output_gap"),
  refresh = FALSE,
  vintage = NULL
)

Arguments

measure

Character. Which economy table to return. One of "inflation", "labour", or "output_gap". Defaults to "inflation".
refresh

Logical. If TRUE, re-download even if a cached copy exists. Defaults to FALSE.
vintage

Optional EFO vintage label such as "October 2024". If supplied, the function downloads the file for that specific EFO. If NULL (the default), the function uses any vintage set via obr_pin(), or falls back to the latest live EFO via the dynamic URL resolver.

Details

Data run from 2008 Q1 through the current forecast horizon. Use list_efo_economy_measures() to see all available measures.

Value

An obr_tbl with the standard v0.4.0 schema (columns: period, period_type, series, metric_type, value, unit):

period

Calendar quarter, e.g. "2025Q1" (character)

period_type

Always "quarter" for this function (character)

series

Variable name, e.g. "CPI" (character)

metric_type

One of "index", "yoy_pct", "pct", "level", classified from the series name. This is the v0.4.0 fix for the v0.3.x issue where, e.g., CPI Index values and CPI YoY values shared a single value column with no machine-readable distinction.

value

Numeric value in units described by unit

unit

One of "index", "pct", etc., paired with metric_type

See Also

Other EFO: get_efo_fiscal(), get_efo_table(), list_efo_economy_measures(), obr_efo_catalogue()

Examples

op <- options(obr.cache_dir = tempdir())
inf <- get_efo_economy("inflation")
inf[inf$series == "CPI", ]

lab <- get_efo_economy("labour")

# Compare CPI projections from two different EFOs
inf_oct24 <- get_efo_economy("inflation", vintage = "October 2024")
inf_mar26 <- get_efo_economy("inflation", vintage = "March 2026")
options(op)

Get EFO fiscal projections (net borrowing components)

Description

Downloads (and caches) the OBR Economic and Fiscal Outlook Detailed Forecast Tables - Aggregates file and returns the components of net borrowing (Table 6.5) in tidy long format.

Usage

get_efo_fiscal(refresh = FALSE, vintage = NULL)

Arguments

refresh

Logical. If TRUE, re-download even if a cached copy exists. Defaults to FALSE.
vintage

Optional EFO vintage label such as "October 2024". If supplied, the function downloads the file for that specific EFO. If NULL (the default), the function uses any vintage set via obr_pin(), or falls back to the latest live EFO via the dynamic URL resolver. See obr_efo_vintages() for the full list of supported vintages.

Details

Covers the five-year forecast horizon published at the most recent fiscal event. Key series include current receipts, current expenditure, depreciation, net investment, and net borrowing (PSNB). The exact vintage is recorded in the returned object's provenance attribute and visible in the printed header.

Value

An obr_tbl with the standard v0.4.0 schema (columns: period, period_type, series, metric_type, value, unit):

period

Fiscal year being forecast, e.g. "2025-26" (character)

period_type

Always "fiscal_year" for this function (character)

series

Component name, e.g. "Net borrowing" (character)

metric_type

Always "level" for this function (character)

value

Projected value (numeric)

unit

Always "gbp_bn" for this function (character)

See Also

Other EFO: get_efo_economy(), get_efo_table(), list_efo_economy_measures(), obr_efo_catalogue()

Examples

op <- options(obr.cache_dir = tempdir())
efo <- get_efo_fiscal()
efo[efo$series == "Net borrowing", ]
obr_provenance(efo)$vintage

# Pin to a specific EFO for reproducibility
october_2024 <- get_efo_fiscal(vintage = "October 2024")
options(op)

Get any EFO detailed-forecast table by id

Description

Generic fetcher that takes an EFO table identifier (e.g. "6.5", "1.7", "4.1") and returns the parsed contents in the standard v0.4.0 schema. Use obr_efo_catalogue() to discover which tables are available.

Usage

get_efo_table(table_id, vintage = NULL, refresh = FALSE)

Arguments

table_id

Character. The EFO table identifier, e.g. "6.5", "1.7", "6.13". See obr_efo_catalogue() for the full list.
vintage

Optional EFO vintage label (e.g. "October 2024"). If NULL, uses any pin set via obr_pin() or falls back to the latest live EFO.
refresh

Logical. If TRUE, re-download even if a cached copy exists. Defaults to FALSE.

Details

Internally, this function looks up table_id in the catalogue, fetches the right workbook (Aggregates or Economy), dispatches to a layout- specific parser, and tags every row with metric_type and unit according to the catalogue's defaults plus per-row classification.

Coverage today: 17 fiscal Aggregates tables + 22 macro Economy tables. One sheet (6.11 PSND year-on-year changes) is a cross-reference to a previous EFO and returns NULL with a warning rather than data; OBR itself directs users to the previous EFO for that table.

Headline functions get_efo_fiscal() and get_efo_economy() are kept as thin wrappers over this dispatcher.

Value

An obr_tbl with the standard v0.4.0 schema columns (period, period_type, series, metric_type, value, unit). Returns NULL (with a warning) for cross-reference sheets.

See Also

Other EFO: get_efo_economy(), get_efo_fiscal(), list_efo_economy_measures(), obr_efo_catalogue()

Examples

op <- options(obr.cache_dir = tempdir())

# Net borrowing components (same data as get_efo_fiscal())
get_efo_table("6.5")

# CPI category inflation by year
get_efo_table("1.19")

# Composition of public sector net debt
get_efo_table("6.13")

# Pin to a specific vintage
get_efo_table("6.5", vintage = "October 2024")

options(op)

Get Total Managed Expenditure

Description

Downloads (and caches) the OBR Public Finances Databank and returns annual Total Managed Expenditure (TME) in £ billion. TME is the broadest measure of UK government spending.

Usage

get_expenditure(refresh = FALSE)

Arguments

refresh

Logical. If TRUE, re-download even if a cached copy exists. Defaults to FALSE.

Value

An obr_tbl with the standard v0.4.0 schema. series is "TME", metric_type is "level", unit is "gbp_bn". See get_public_finances() for column definitions.

See Also

Other public finances: get_psnb(), get_psnd(), get_public_finances(), get_receipts()

Examples

op <- options(obr.cache_dir = tempdir())
tme <- get_expenditure()
tail(tme)
options(op)

Get OBR forecast revisions

Description

Downloads (and caches) the OBR Forecast Revisions Database, which decomposes each EFO-to-EFO revision in the headline Public Sector Net Borrowing forecast into three top-level components - policy, classifications and one-offs, and underlying (economic determinants) - with sub-components for each.

Usage

get_forecast_revisions(unit = c("gbp_bn", "pct_gdp"), refresh = FALSE)

Arguments

unit

Character. Either "gbp_bn" (GBP billion, the default) or "pct_gdp" (per cent of GDP).
refresh

Logical. If TRUE, re-download even if a cached copy exists. Defaults to FALSE.

Details

This is the dataset behind the "what changed?" attribution charts in OBR fiscal commentary and IFS Green Budget chapters.

Value

An obr_tbl with columns:

forecast_date

Forecast vintage, e.g. "November 2024" (character).

component

Revision component. Top-level rows are "Total", "Policy", "Classifications and one-offs", and "Underlying". Sub-components carry the OBR's "of which: ..." labels (character).

fiscal_year

Fiscal year being revised, e.g. "2024-25" (character).

value

Revision value, in GBP billion or per cent of GDP per unit (numeric). A positive value indicates an upward revision to PSNB.

See Also

Other forecasts: get_forecasts(), list_forecast_series(), obr_actual_vs_forecast(), obr_compare_vintages(), obr_forecast_panel()

Examples

op <- options(obr.cache_dir = tempdir())
rev <- get_forecast_revisions()
# Top-level revisions only
rev[rev$component %in% c("Total", "Policy",
                         "Classifications and one-offs", "Underlying"), ]
options(op)

Get OBR forecast history for a fiscal series

Description

Downloads (and caches) the OBR Historical Official Forecasts Database and returns a tidy long-format data frame showing every forecast the OBR has ever published for a given series. Each row is one forecast for one fiscal year, made at one fiscal event.

Usage

get_forecasts(series = "PSNB", refresh = FALSE)

Arguments

series

Character. The series to return. Use list_forecast_series() to see all options. Defaults to "PSNB" (Public Sector Net Borrowing in £ billion).
refresh

Logical. If TRUE, re-download even if a cached copy exists. Defaults to FALSE.

Details

This is useful for visualising how OBR forecasts have evolved over time, and for comparing forecasts against outturns. The vintage of the underlying database is recorded in the returned object's provenance.

Value

An obr_tbl with the standard v0.4.0 schema plus a forecast_date column (so each row identifies one fiscal-year value at one fiscal event):

forecast_date

When the forecast was published, e.g. "March 2024"

period

Fiscal year being forecast, e.g. "2024-25"

period_type

Always "fiscal_year"

series

Series name as supplied (character)

metric_type

One of "level", "pct", "yoy_pct", set per series. CPI / GDP / real_GDP are "yoy_pct" (rates of change); PSNB / receipts / expenditure are "level"; the ⁠_pct⁠ variants and PSND are "pct" (% of GDP).

value

Numeric forecast value in the unit described by unit

unit

"gbp_bn" for level series, "pct" for percentage series

See Also

Other forecasts: get_forecast_revisions(), list_forecast_series(), obr_actual_vs_forecast(), obr_compare_vintages(), obr_forecast_panel()

Examples

op <- options(obr.cache_dir = tempdir())
get_forecasts("PSNB")

psnb <- get_forecasts("PSNB")
psnb[psnb$period == "2024-25", ]
options(op)

Get incapacity benefit caseloads

Description

Downloads (and caches) the OBR Welfare Trends Report charts and tables workbook and returns the combined incapacity benefit caseload since 2008-09, in both absolute terms (thousands of claimants) and as a share of the working-age population.

Usage

get_incapacity_caseloads(refresh = FALSE)

Arguments

refresh

Logical. If TRUE, re-download even if a cached copy exists. Defaults to FALSE.

Value

An obr_tbl with the standard v0.4.0 schema. The two series ("Claimants" and "Share of working age population") carry different units: claimants are in thousands and the share is a percentage. After calling, the caller may want to overwrite unit to "count_k" for the claimants series, since the heuristic classifier cannot infer the "thousands" denomination from the series name alone.

See Also

Other welfare: get_incapacity_spending(), get_welfare_spending()

Examples

op <- options(obr.cache_dir = tempdir())
cases <- get_incapacity_caseloads()
cases[cases$series == "Claimants", ]
options(op)

Get incapacity benefits spending by type

Description

Downloads (and caches) the OBR Welfare Trends Report charts and tables workbook and returns annual spending on each incapacity benefit as a share of GDP, from 1978-79 to the current forecast horizon.

Usage

get_incapacity_spending(refresh = FALSE)

Arguments

refresh

Logical. If TRUE, re-download even if a cached copy exists. Defaults to FALSE.

Details

Series include: Invalidity Benefit, Incapacity Benefit, Employment and Support Allowance (ESA), Sickness Benefit, and Severe Disablement Allowance.

Value

An obr_tbl with the standard v0.4.0 schema. series is the benefit name, values are spending as a percentage of GDP, metric_type is "pct", unit is "pct". See get_public_finances() for full column docs.

See Also

Other welfare: get_incapacity_caseloads(), get_welfare_spending()

Examples

op <- options(obr.cache_dir = tempdir())
ib <- get_incapacity_spending()
unique(ib$series)
options(op)

Get long-run state pension spending projections

Description

Downloads (and caches) the OBR Fiscal Risks and Sustainability Report executive summary charts and tables workbook and returns 50-year projections for state pension spending as a share of GDP, under alternative demographic and triple-lock uprating scenarios.

Usage

get_pension_projections(refresh = FALSE)

Arguments

refresh

Logical. If TRUE, re-download even if a cached copy exists. Defaults to FALSE.

Details

This data is unique to the Fiscal Risks and Sustainability Report and is not available in any other OBR publication. It illustrates how ageing demographics and pension uprating rules interact to determine the long-run cost of the state pension. The exact vintage is recorded in the returned object's provenance.

Value

An obr_tbl with the standard v0.4.0 schema plus a scenario_type column to group scenarios:

period

Fiscal year, e.g. "2030-31" (character)

period_type

Always "fiscal_year"

series

Scenario name, e.g. "Central projection", "Higher life expectancy" (character)

metric_type

Always "pct"

value

State pension spending as a percentage of GDP (numeric)

unit

Always "pct"

scenario_type

Either "Demographic scenarios" or "Triple lock scenarios" (character)

Examples

op <- options(obr.cache_dir = tempdir())
proj <- get_pension_projections()

central <- proj[proj$scenario_type == "Demographic scenarios" &
                proj$series == "Central projection", ]
tail(central, 10)

dem <- proj[proj$scenario_type == "Demographic scenarios", ]
options(op)

Get OBR policy measures by fiscal event

Description

Downloads (and caches) the OBR Policy Measures Database, a single workbook that lists every tax or spending measure scored at a UK fiscal event, with the Exchequer effect in GBP million for each year of the forecast horizon. Tax measures cover 1970 to date; spending measures cover 2010 to date.

Usage

get_policy_measures(
  type = c("tax", "spending"),
  search = NULL,
  since = NULL,
  refresh = FALSE
)

Arguments

type

Character vector. Which measures to return: "tax", "spending", or both (the default).
search

Optional character. A regular expression used to filter measure and head (case-insensitive). For example, search = "alcohol" keeps any measure whose description or head mentions alcohol.
since

Optional fiscal-year cut-off (e.g. "2020-21"). Rows whose fiscal_year is earlier are dropped.
refresh

Logical. If TRUE, re-download even if a cached copy exists. Defaults to FALSE.

Details

This is the only programmatic access to the PMD: the OBR otherwise distributes it as a single Excel file.

Value

An obr_tbl with columns:

event

Fiscal event that scored the measure, e.g. "Budget 2024" (character)

measure

Plain-English description of the measure (character)

head

Tax head (for tax measures) or spending head (character)

fiscal_year

Fiscal year being scored, e.g. "2024-25" (character)

value_mn

Exchequer effect in GBP million. For tax measures, a positive value raises revenue; for spending measures, a positive value increases spending (numeric)

See Also

Other policy measures: policy_measures_summary()

Examples

op <- options(obr.cache_dir = tempdir())

# The OBR CDN occasionally rate-limits or returns 403 to repeated
# requests. tryCatch so the example degrades gracefully if that happens
# during the CRAN check.
oct24 <- tryCatch(get_policy_measures(),
                  error = function(e) NULL)
if (!is.null(oct24)) {
  head(oct24[grepl("2024", oct24$event) &
             oct24$fiscal_year == "2025-26", ])

  # All alcohol-duty measures since 2010
  tryCatch(
    get_policy_measures(type = "tax", search = "alcohol",
                        since = "2010-11"),
    error = function(e) NULL
  )
}

options(op)

Get Public Sector Net Borrowing (PSNB)

Description

Downloads (and caches) the OBR Public Finances Databank and returns annual Public Sector Net Borrowing in £ billion. A positive value means the government is borrowing (deficit); a negative value means a surplus.

Usage

get_psnb(refresh = FALSE)

Arguments

refresh

Logical. If TRUE, re-download even if a cached copy exists. Defaults to FALSE.

Value

An obr_tbl with the standard v0.4.0 schema. series is "PSNB", metric_type is "level", unit is "gbp_bn". See get_public_finances() for column definitions.

See Also

Other public finances: get_expenditure(), get_psnd(), get_public_finances(), get_receipts()

Examples

op <- options(obr.cache_dir = tempdir())
psnb <- get_psnb()
tail(psnb)
options(op)

Get Public Sector Net Debt (PSND)

Description

Downloads (and caches) the OBR Public Finances Databank and returns annual Public Sector Net Debt in £ billion.

Usage

get_psnd(refresh = FALSE)

Arguments

refresh

Logical. If TRUE, re-download even if a cached copy exists. Defaults to FALSE.

Value

An obr_tbl with the standard v0.4.0 schema. series is "PSND", metric_type is "level", unit is "gbp_bn". See get_public_finances() for column definitions.

See Also

Other public finances: get_expenditure(), get_psnb(), get_public_finances(), get_receipts()

Examples

op <- options(obr.cache_dir = tempdir())
psnd <- get_psnd()
tail(psnd)
options(op)

Get all Public Finances Databank aggregates

Description

Downloads (and caches) the OBR Public Finances Databank and returns all aggregate fiscal series in tidy long format. Covers outturn from 1946-47 and OBR projections through the current forecast horizon.

Usage

get_public_finances(refresh = FALSE)

Arguments

refresh

Logical. If TRUE, re-download even if a cached copy exists. Defaults to FALSE.

Details

Series include: Public sector net borrowing, Public sector net debt, Total managed expenditure, Public sector current receipts, Nominal GDP, GDP deflator, and more.

Value

An obr_tbl (a data.frame with attached provenance) with the standard v0.4.0 schema (columns: period, period_type, series, metric_type, value, unit):

period

Fiscal year (character, e.g. "2024-25")

period_type

Always "fiscal_year" for this function

series

Series name (character)

metric_type

Usually "level"; ratio or index series get a more specific value derived from the series name

value

Numeric value in units described by unit

unit

Usually "gbp_bn"; ratios and indices override

Use obr_provenance() to extract source URL, vintage, and retrieval time.

See Also

Other public finances: get_expenditure(), get_psnb(), get_psnd(), get_receipts()

Examples

op <- options(obr.cache_dir = tempdir())
pf <- get_public_finances()
unique(pf$series)
obr_provenance(pf)
options(op)

Get public sector receipts by tax type

Description

Downloads (and caches) the OBR Public Finances Databank and returns public sector current receipts broken down by individual tax type, in tidy long format. Coverage begins in 1999-00.

Usage

get_receipts(refresh = FALSE)

Arguments

refresh

Logical. If TRUE, re-download even if a cached copy exists. Defaults to FALSE.

Value

An obr_tbl with the standard v0.4.0 schema (columns: period, period_type, series, metric_type, value, unit). series is the tax or receipt category, metric_type is "level", unit is "gbp_bn". See get_public_finances() for full column docs.

See Also

Other public finances: get_expenditure(), get_psnb(), get_psnd(), get_public_finances()

Examples

op <- options(obr.cache_dir = tempdir())
receipts <- get_receipts()
receipts[grepl("income tax", receipts$series, ignore.case = TRUE), ]
options(op)

Get working-age welfare spending

Description

Downloads (and caches) the OBR Welfare Trends Report charts and tables workbook and returns annual working-age welfare spending as a share of GDP, split into incapacity-related and non-incapacity spending.

Usage

get_welfare_spending(refresh = FALSE)

Arguments

refresh

Logical. If TRUE, re-download even if a cached copy exists. Defaults to FALSE.

Details

Data cover fiscal years from 1978-79 through the current forecast horizon. The exact vintage is recorded in the returned object's provenance.

Value

An obr_tbl with the standard v0.4.0 schema (columns: period, period_type, series, metric_type, value, unit). Values are spending as a percentage of GDP; metric_type is "pct", unit is "pct".

See Also

Other welfare: get_incapacity_caseloads(), get_incapacity_spending()

Examples

op <- options(obr.cache_dir = tempdir())
welfare <- get_welfare_spending()
welfare[welfare$series == "Working-age incapacity benefits spending" &
        welfare$period >= "2000-01", ]
options(op)

List available EFO economy measures

Description

Returns a data frame of the economy measures available via get_efo_economy(), showing the measure name to pass and a short description of what each covers.

Usage

list_efo_economy_measures()

Value

A data frame with columns measure, sheet, and description.

See Also

Other EFO: get_efo_economy(), get_efo_fiscal(), get_efo_table(), obr_efo_catalogue()

Examples

list_efo_economy_measures()

List available forecast series

Description

Returns a data frame showing the series names accepted by get_forecasts(), the corresponding Excel sheet in the OBR Historical Official Forecasts Database, and a plain-English description.

Usage

list_forecast_series()

Value

A data frame with columns series, sheet, and description.

See Also

Other forecasts: get_forecast_revisions(), get_forecasts(), obr_actual_vs_forecast(), obr_compare_vintages(), obr_forecast_panel()

Examples

list_forecast_series()

Pair OBR forecasts with PFD outturn

Description

Joins the long-format Historical Forecasts Database for a given series against the Public Finances Databank outturn for the same series. Returns one row per (forecast vintage, fiscal year) where both an OBR forecast value and an ONS outturn value exist, with the forecast error (value_forecast - value_actual) computed.

Usage

obr_actual_vs_forecast(
  series = c("PSNB", "PSND", "expenditure"),
  refresh = FALSE
)

Arguments

series

Forecast series. One of "PSNB", "PSND", "expenditure". Defaults to "PSNB".
refresh

Logical. If TRUE, re-download underlying files.

Details

Useful for forecast-evaluation studies, similar in shape to the OBR's own Forecast Evaluation Report decomposition.

Currently supports series for which a clean gbp_bn outturn function exists in this package: "PSNB", "PSND", "expenditure". Other series (CPI, GDP, percentages of GDP) need outturn from external packages and will error.

Value

An obr_tbl with columns forecast_date, period (fiscal year being forecast), period_type, series, unit, value_forecast (from HFD), value_actual (from PFD outturn), and error (value_forecast - value_actual). Provenance points at the HFD; the PFD source URL is recorded in notes.

See Also

Other forecasts: get_forecast_revisions(), get_forecasts(), list_forecast_series(), obr_compare_vintages(), obr_forecast_panel()

Examples

op <- options(obr.cache_dir = tempdir())
eval <- obr_actual_vs_forecast("PSNB")

# 1-year-ahead forecast errors only:
# take the forecast vintage closest to the start of each fiscal year
eval2425 <- eval[eval$period == "2024-25", ]
eval2425[order(eval2425$forecast_date), ]
options(op)

Find the OBR publication that was current on a given date

Description

Returns the most recent EFO that had been published on or before date. Useful for reproducing analyses as they would have looked at a given point in time, before subsequent forecast revisions.

Usage

obr_as_of(date, publication = "EFO")

Arguments

date

A Date, or anything coercible to one (e.g. "2024-11-15").
publication

Currently only "EFO" is supported.

Value

A length-one character vector containing the vintage label, e.g. "October 2024".

See Also

Other vintage: obr_efo_vintages(), obr_pin(), obr_pinned(), obr_unpin()

Examples

obr_as_of("2024-11-15")
obr_as_of(Sys.Date())

Compare two EFO vintages

Description

Pulls the same EFO table from two vintages and returns a tidy diff with a revision column (value_b - value_a). Useful for quantifying how the OBR's view changed between fiscal events.

Usage

obr_compare_vintages(
  vintage_a,
  vintage_b,
  what = c("fiscal", "inflation", "labour", "output_gap"),
  refresh = FALSE
)

Arguments

vintage_a, vintage_b

EFO vintage labels (e.g. "October 2024", "March 2026"). Use obr_efo_vintages() to see all valid labels.
what

Which EFO table to compare. One of "fiscal" (Table 6.5 aggregates, the default), "inflation" (sheet 1.7), "labour" (sheet 1.6), or "output_gap" (sheet 1.14).
refresh

Logical. If TRUE, re-download even if cached files exist. Defaults to FALSE.

Details

Rows are the inner join of the two vintages on the schema keys (period, period_type, series, metric_type, unit). Periods or series that are present in only one vintage are silently dropped. If you need to see what was added or removed between vintages, compare obr_efo_vintages() row counts or call the underlying functions directly with each vintage and setdiff() on the keys.

Calling the function with vintage_a == vintage_b is allowed and returns an all-zero revision column. There is no special handling beyond that.

Value

An obr_tbl with the standard v0.4.0 schema columns (period, period_type, series, metric_type, unit) plus value_a, value_b, and revision (value_b - value_a). Provenance points at the second vintage; the first vintage URL is recorded in the notes field.

See Also

Other forecasts: get_forecast_revisions(), get_forecasts(), list_forecast_series(), obr_actual_vs_forecast(), obr_forecast_panel()

Examples

op <- options(obr.cache_dir = tempdir())
diff <- obr_compare_vintages("October 2024", "March 2026")
diff[diff$series == "Net borrowing", ]

# Compare the inflation forecast across two vintages
inf_diff <- obr_compare_vintages("October 2024", "March 2026",
                                 what = "inflation")
options(op)

List the EFO detailed-forecast tables this package can fetch

Description

Returns a data frame describing every Detailed Forecast Table in the OBR Economic and Fiscal Outlook (Aggregates and Economy workbooks) that get_efo_table() knows how to parse.

Usage

obr_efo_catalogue()

Details

Use this catalogue to discover which tables are available, what each contains, and the default metric_type / unit get_efo_table() will attach. Pass any table_id to get_efo_table().

Coverage: 17 fiscal aggregates tables (Section 6) plus 22 macro economy tables (Section 1). One sheet (6.11) is currently a cross-reference to a previous EFO and returns NULL with a warning rather than data.

Value

A data frame with columns:

table_id

The EFO table identifier (e.g. "6.5", "1.7").

file

Which EFO workbook the table sits in: "aggregates" or "economy".

section

Theme tag (e.g. "GDP", "Labour", "Debt").

title

Human-readable title taken from the OBR contents page.

layout

Layout family the parser uses: "quarterly_wide", "quarterly_single", "annual_year_wide", "fiscal_year_wide", or "cross_reference".

default_metric_type

Default metric_type applied to series whose name does not signal otherwise. NA lets the heuristic decide per row.

default_unit

Default unit for the same.

See Also

Other EFO: get_efo_economy(), get_efo_fiscal(), get_efo_table(), list_efo_economy_measures()

Examples

head(obr_efo_catalogue())

# All tables in the Debt section
cat <- obr_efo_catalogue()
cat[cat$section == "Debt", c("table_id", "title")]

List known OBR Economic and Fiscal Outlook vintages

Description

Returns a data frame of every EFO published since the OBR was created in June 2010, with publication dates and the URL slug used in the OBR's download links. Use this to look up which vintages can be pinned via obr_pin() or passed to ⁠vintage =⁠ arguments on get_efo_fiscal() and get_efo_economy().

Usage

obr_efo_vintages()

Value

A data frame with columns:

publication

Always "EFO".

vintage

Vintage label, e.g. "March 2026".

date

Publication date of the EFO (Date).

slug

URL slug used by the OBR for that vintage's download pages.

See Also

Other vintage: obr_as_of(), obr_pin(), obr_pinned(), obr_unpin()

Examples

head(obr_efo_vintages())
tail(obr_efo_vintages(), 5)

Get the current UK fiscal rules

Description

Returns a data frame describing the Charter for Budget Responsibility fiscal rules currently in force, as encoded in the package at the time of release. Numerical headroom against each rule is not shipped as a constant because it is updated at every fiscal event and would go stale within months; users should derive headroom from the current EFO output of get_efo_fiscal(), or consult the OBR's EFO press release for the relevant vintage.

Usage

obr_fiscal_rules()

Details

The current Charter (Autumn 2024, with an Autumn 2025 update) sets three numerical rules:

  • Stability rule: current budget in balance or surplus by the target year. The target year is the 5th forecast year and rolls to the 3rd forecast year from 2026-27 onwards.

  • Investment rule: Public Sector Net Financial Liabilities (PSNFL) as a share of GDP falling year-on-year by the target year.

  • Welfare cap: AME-capped welfare spending below the statutory cap level by the target year.

The Budget Responsibility Act 2024 also adds a non-numerical fiscal lock requiring an OBR forecast for any fiscally significant measure.

Value

A data frame with columns:

rule

Short rule code: "stability", "investment", "welfare_cap".

metric

The metric the rule binds on.

target_description

Plain-English target.

target_year_rule

How the target year is set under the Charter.

direction_of_pass

Sign convention for headroom.

source_charter

Charter version that defines the rule.

source_act

Act of Parliament backing the rule.

Examples

obr_fiscal_rules()

Build a wide real-time panel of OBR forecasts

Description

Takes the long-format Historical Forecasts Database output of get_forecasts() and pivots it to a wide panel with one row per forecast vintage (e.g. "March 2024") and one column per fiscal year being forecast (e.g. "2024-25"). The first column is the forecast vintage; remaining columns are numeric forecast values.

Usage

obr_forecast_panel(
  series = "PSNB",
  refresh = FALSE,
  order_chronologically = TRUE
)

Arguments

series

Character. Series to return; see list_forecast_series(). Defaults to "PSNB".
refresh

Logical. If TRUE, re-download the underlying database.
order_chronologically

Logical. If TRUE (the default), rows are ordered from earliest to latest forecast vintage. If FALSE, rows appear in the order returned by get_forecasts().

Details

This format mirrors how the OBR's own Historical Forecasts Database is laid out and how forecast-error studies (e.g. the OBR's own Forecast Evaluation Report) decompose performance: each row is one forecast published at a fiscal event, each column is the target year being forecast, and the diagonal-like structure lets you read the h-step ahead forecast for any vintage.

Value

An obr_tbl whose first column (forecast_date) is character and whose remaining columns are numeric forecast values, one per fiscal year. Provenance is inherited from the underlying call to get_forecasts() and a notes field describes the panel.

See Also

Other forecasts: get_forecast_revisions(), get_forecasts(), list_forecast_series(), obr_actual_vs_forecast(), obr_compare_vintages()

Examples

op <- options(obr.cache_dir = tempdir())
panel <- obr_forecast_panel("PSNB")
# PSNB forecast for 2024-25 across every vintage
panel[, c("forecast_date", "2024-25")]
options(op)

Pin a session-wide OBR EFO vintage

Description

Sets the EFO vintage that get_efo_fiscal() and get_efo_economy() will use when called without an explicit ⁠vintage =⁠ argument. The pin is stored as the option obr.efo_vintage and lasts for the R session unless overwritten or removed via obr_unpin().

Usage

obr_pin(vintage = NULL)

Arguments

vintage

Vintage label such as "October 2024". See obr_efo_vintages() for the full list. If NULL, this function clears the pin (equivalent to calling obr_unpin()).

Value

Invisibly returns the pinned vintage string, or NULL after clearing.

See Also

Other vintage: obr_as_of(), obr_efo_vintages(), obr_pinned(), obr_unpin()

Examples

op <- options(obr.cache_dir = tempdir())
obr_pin("October 2024")
obr_pinned()
obr_unpin()
options(op)

Show the currently pinned OBR EFO vintage

Description

Returns the vintage string currently active via obr_pin(), or NULL if no pin is set.

Usage

obr_pinned()

Value

Either a length-one character vector or NULL.

See Also

Other vintage: obr_as_of(), obr_efo_vintages(), obr_pin(), obr_unpin()

Examples

obr_pinned()

Extract OBR provenance metadata

Description

Returns the provenance list attached to an obr_tbl: the OBR publication it came from, the publication vintage, the source URL, retrieval time, file fingerprint, and package version.

Usage

obr_provenance(x)

Arguments

x

An obr_tbl (or any object; returns NULL if none attached).

Value

A named list of provenance fields, or NULL if no provenance is attached. Fields:

publication

Short code: "PFD", "HFD", "EFO", "WTR", "FSR", "PMD".

vintage

Publication vintage label, e.g. "March 2026".

source_url

Canonical OBR download URL the data came from.

retrieved

POSIXct timestamp of when the file was downloaded or last validated in the cache.

file_md5

MD5 fingerprint of the underlying spreadsheet.

package_version

obr package version that produced the object.

notes

Optional free-text notes, or NULL.

Examples

op <- options(obr.cache_dir = tempdir())
psnb <- get_psnb()
obr_provenance(psnb)
options(op)

Clear the pinned OBR EFO vintage

Description

Removes any pin set by obr_pin(). After unpinning, get_efo_fiscal() and get_efo_economy() revert to resolving the most recent live EFO via the dynamic URL resolver.

Usage

obr_unpin()

Value

Invisibly returns the previously pinned vintage (or NULL if no pin was set).

See Also

Other vintage: obr_as_of(), obr_efo_vintages(), obr_pin(), obr_pinned()

Examples

op <- options(obr.cache_dir = tempdir())
obr_pin("March 2025")
obr_unpin()
options(op)

Summarise policy measures by fiscal event

Description

Aggregates the measures returned by get_policy_measures() to give the net Exchequer effect (positive = revenue-raising / spending-reducing for tax, spending-increasing for spending) by fiscal event and fiscal year.

Usage

policy_measures_summary(x)

Arguments

x

An obr_tbl returned by get_policy_measures().

Value

An obr_tbl with columns:

type

"tax" or "spending"

event

Fiscal event

fiscal_year

Fiscal year

value_mn

Sum of the Exchequer effect across all measures scored at that event, in GBP million

Provenance is preserved.

See Also

Other policy measures: get_policy_measures()

Examples

op <- options(obr.cache_dir = tempdir())
pm <- get_policy_measures(type = "tax", since = "2024-25")
policy_measures_summary(pm)
options(op)

Print an obr_tbl

Description

Prints the data with a provenance header that names the OBR publication, vintage, source URL, retrieval time, and underlying file fingerprint.

Usage

## S3 method for class 'obr_tbl'
print(x, n = 10L, ...)

Arguments

x

An obr_tbl object.
n

Number of rows to display (default 10).
...

Further arguments passed to print.data.frame().

Value

The input, returned invisibly.

Summary of an obr_tbl

Description

Returns the full provenance card and a structural summary of the data.

Usage

## S3 method for class 'obr_tbl'
summary(object, ...)

Arguments

object

An obr_tbl object.
...

Unused.

Value

Invisibly returns the provenance list.