% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/headroom.R
\name{obr_headroom}
\alias{obr_headroom}
\title{Compute the stability-rule margin from the EFO forecast}
\usage{
obr_headroom(vintage = NULL, target_year = NULL, refresh = FALSE)
}
\arguments{
\item{vintage}{Optional EFO vintage label such as \code{"March 2026"}. If
\code{NULL} (the default), uses any pin set via \code{\link[=obr_pin]{obr_pin()}} or the latest
live EFO.}

\item{target_year}{Optional fiscal-year string (e.g. \code{"2029-30"}). If
supplied, an \code{is_target_year} column flags that year.}

\item{refresh}{Logical. If \code{TRUE}, re-download even if a cached copy
exists. Defaults to \code{FALSE}.}
}
\value{
An \code{obr_tbl} with the standard schema columns (\code{period},
\code{period_type}, \code{series}, \code{metric_type}, \code{value}, \code{unit}), where \code{series}
is \code{"Current budget surplus"} and \code{value} is in GBP billion (positive =
surplus = headroom under the stability rule). If \code{target_year} is
supplied, an additional logical \code{is_target_year} column is included.
}
\description{
Returns the current budget surplus for every year of an EFO forecast,
derived from Table 6.5 (Components of net borrowing). Under the Charter
for Budget Responsibility's stability rule the current budget must be in
balance or surplus by the target year, so the value in the target year
is the margin, or "headroom", against the rule: positive means the rule
is met with room to spare, negative means it is missed.
}
\details{
The value returned is \verb{-1 *} the published "Current budget deficit"
series, i.e. a surplus is positive. Pass \code{target_year} to flag the year
the rule currently bites on; the function does not guess it, because the
Charter's target-year convention changes over time (see
\code{\link[=obr_fiscal_rules]{obr_fiscal_rules()}} for the rules as encoded at release).

Note the OBR's own published headroom figure at a fiscal event can
differ slightly from the Table 6.5 arithmetic (rounding, and any
rule-specific adjustments described in the EFO text). Treat this as the
published forecast path for the rule metric, not a reproduction of the
OBR's press-notice headroom number.
}
\examples{
\donttest{
op <- options(obr.cache_dir = tempdir())

hr <- tryCatch(obr_headroom(), error = function(e) NULL)
if (!is.null(hr)) hr

# Flag the target year and read off the margin
hr <- tryCatch(obr_headroom(target_year = "2029-30"),
               error = function(e) NULL)
if (!is.null(hr)) hr[hr$is_target_year, ]

options(op)
}

}
\seealso{
Other fiscal rules: 
\code{\link{obr_fiscal_rules}()}
}
\concept{fiscal rules}
