% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hmrc_income_tax_stats.R
\name{hmrc_income_tax_stats}
\alias{hmrc_income_tax_stats}
\title{Download HMRC Income Tax liabilities by income range}
\source{
\url{https://www.gov.uk/government/statistics/income-tax-liabilities-by-income-range}
}
\usage{
hmrc_income_tax_stats(tax_year = NULL, cache = TRUE)
}
\arguments{
\item{tax_year}{Character vector or \code{NULL} (default = all years). Filter to
specific tax years, e.g. \code{"2023-24"}.}

\item{cache}{Logical. Use cached file if available (default \code{TRUE}).}
}
\value{
An \code{hmrc_tbl} with columns \code{tax_year}, \code{income_range},
\code{income_lower_gbp}, \code{taxpayers_thousands}, \code{total_income_gbp_m},
\code{tax_liability_gbp_m}, \code{average_rate_pct}, \code{average_tax_gbp}.
}
\description{
Downloads and tidies HMRC Table 2.5, which reports the number of Income Tax
payers and their liabilities grouped by total income range, for each
available tax year. Numbers of taxpayers are in thousands; amounts are in
millions of pounds unless otherwise noted. Published annually in May/June.
}
\details{
The earliest tax year with outturn data is based on the Survey of Personal
Incomes; later years are projected estimates. Values suppressed for small
sample sizes are returned as \code{NA}.
}
\examples{
\donttest{
op <- options(hmrc.cache_dir = tempdir())
hmrc_income_tax_stats()
hmrc_income_tax_stats(tax_year = "2023-24")
options(op)
}

}
\seealso{
Other data fetchers: 
\code{\link{hmrc_capital_gains}()},
\code{\link{hmrc_corporation_tax}()},
\code{\link{hmrc_creative_industries}()},
\code{\link{hmrc_fuel_duties}()},
\code{\link{hmrc_inheritance_tax}()},
\code{\link{hmrc_patent_box}()},
\code{\link{hmrc_property_transactions}()},
\code{\link{hmrc_rd_credits}()},
\code{\link{hmrc_stamp_duty}()},
\code{\link{hmrc_tax_gap}()},
\code{\link{hmrc_tax_receipts}()},
\code{\link{hmrc_tobacco_duties}()},
\code{\link{hmrc_vat}()}
}
\concept{data fetchers}
