% File src/library/Fiscal/vignettes/incometax.Rnw
% Part of the Fiscal package, https://mark-eis.github.io/Fiscal/
% Copyright 2026 Mark Eisler
% Distributed under the MIT License

\documentclass[a4paper]{article}

\usepackage{Rd}
\usepackage{hyperref}

\hypersetup{colorlinks = true, linkcolor = blue, urlcolor = blue}

\setlength{\parindent}{0in}
\setlength{\parskip}{.1in}
\setlength{\textwidth}{140mm}
\setlength{\oddsidemargin}{10mm}

\title{PAYE income tax calculator for England, Northern~Ireland and Wales}
\author{Mark Eisler}
% \VignetteIndexEntry{PAYE income tax calculator for England, Northern~Ireland and Wales}
% \VignettePackage{Fiscal}

\begin{document}

\maketitle

<<echo=FALSE, results=hide>>=
library(Fiscal)
options(width = 80, continue = "  ",
        try.outFile = stdout())
@

<<echo=FALSE, results=hide>>=
prettyL <- function(x) paste0("\U00A3", prettyNum(x, ","))
std_allow <- tax_opts()$std_allow
allow_upper <- tax_opts()$allow_upper
basicband <- tax_opts()$band[1]
higherband <- tax_opts()$band[2]
sumband <- sum(tax_opts()$band)
basicrate <- tax_opts()$rate[1] * 100
higherrate <- tax_opts()$rate[2] * 100
additionalrate <- tax_opts()$rate[3] * 100
@

\tableofcontents 

\section{Introduction}

\code{incometax()} estimates income tax payable on PAYE income in England, Northern Ireland and
Wales, and is intended to replicate the estimates of GOV.UK
\href{https://www.gov.uk/estimate-income-tax}{Estimate your Income Tax for the current year}\footnote{
  \code{incometax()} does not currently calculate \emph{National Insurance} (NI)
  contributions, and should therefore return values equal to the estimates from the GOV.UK website
  with \dQuote{yes} as the answer to the question \sQuote{Are you over the State Pension age?} For
  NI information see:
  \href{https://www.gov.uk/government/publications/rates-and-allowances-national-insurance-contributions/rates-and-allowances-national-insurance-contributions}{Rates and allowances: National Insurance contributions.}}.

Tax is paid on the amount of taxable income remaining after the
\href{https://www.gov.uk/income-tax-rates}{Personal Allowance} has been deducted, and is allocated
among the \emph{basic}, \emph{higher} and \emph{additional} rates. After deduction of the Personal
Allowance, if any (see below): income up to and including the upper limit of the basic rate band
attracts \emph{basic rate} tax; income exceeding the basic rate band by an amount up to and
including the upper limit of the higher rate band attracts \emph{higher rate} tax; and income
exceeding the sum of the basic and higher rate bands attracts \emph{additional rate} tax.

The \href{https://www.gov.uk/income-tax-rates}{standard Personal Allowance} is the amount of annual
taxable income on which there is no tax liability, currently \Sexpr{prettyL(std_allow)}. The
standard Personal Allowance goes down by \pounds1~for every \pounds2 that
\href{https://www.gov.uk/guidance/adjusted-net-income}{adjusted net income} is above an upper
threshold, currently \Sexpr{prettyL(allow_upper)}. This means the standard Personal Allowance is
zero if annual taxable income is \Sexpr{prettyL(allow_upper + std_allow * 2)} or above.

Hence currently in 2026:~--
\begin{itemize}
\item annual taxable income after allowances---e.g., the standard Personal Allowance of
  \Sexpr{prettyL(std_allow)}---up to \Sexpr{prettyL(basicband)} attracts \Sexpr{basicrate}\% basic
    rate income tax\footnote{In practice, an additional \pounds9 annual income is allowed before
      basic and higher rate tax is applied.};
\item annual taxable income after allowances between \Sexpr{prettyL(basicband + 1)} and
  \Sexpr{prettyL(sumband)} attracts\\ \Sexpr{higherrate}\% higher rate income tax---noting that the
  standard Personal Allowance is reduced above \Sexpr{prettyL(allow_upper)};
\item annual taxable income after allowances above \Sexpr{prettyL(sumband)} attracts
  \Sexpr{additionalrate}\% additional rate income tax---noting there is no standard Personal
  Allowance at or above \Sexpr{prettyL(allow_upper + std_allow * 2)}\footnote{In practice,
    an additional \pounds6 annual income is allowed before additional rate tax is applied; the
    additional \pounds6 is decreased by \pounds1 for every further \pounds2 increase in income
    beyond \Sexpr{prettyL(sumband + 7)}.}.
\end{itemize}

See GOV.UK 
\href{https://www.gov.uk/government/publications/rates-and-allowances-income-tax/income-tax-rates-and-allowances-current-and-past#tax-rates-and-bands}{Income Tax rates and allowances: Tax rates and bands}.

A bespoke Personal Allowance may be specified using \code{incometax()} argument \code{allowance}.
When negative, this argument specifies a
\href{https://www.gov.uk/tax-codes/k-in-your-tax-code}{K code pay adjustment}; otherwise, the
standard Personal Allowance will be calculated using \code{pers\_allow(income, opts)}.

\section{Estimating Income Tax}
\subsection{Income up to the Personal Allowance}
Annual income less or equal to the standard Personal Allowance of \Sexpr{prettyL(std_allow)} is not
taxed:~--

<<>>=
incometax(12570)
@

Specifying the standard Personal Allowance explicitly is identical:~--

<<>>=
all.equal(incometax(12570), incometax(12570, 12570))
@

In practice, although shown as "Taxable Income"\footnote{For consistency with GOV.UK
  \href{https://www.gov.uk/estimate-income-tax}{Estimate your Income Tax for the current year}}, an
additional \pounds9 income is allowed before tax is applied:~--

<<>>=
incometax(12579)

all.equal(incometax(12579), incometax(12579, 12570))
@

\subsection{Income above the Personal Allowance}
Annual income above the \Sexpr{prettyL(std_allow)} standard Personal Allowance plus the additional
\pounds9 \\attracts \Sexpr{basicrate}\% basic rate tax. For instance, at an annual income of
\Sexpr{prettyL(std_allow + 9 + 1000)}, while \\"Taxable Income" is shown as \pounds1,009, only
\pounds1,000 is actually taxed:~--
	
<<>>=
incometax(13579)
@

At an annual income of \pounds6,009 and with a bespoke Personal Allowance specified using
\code{allowance = 5000} as the second argument of \code{incometax()}, again while "Taxable Income"
is shown as \pounds1,009, only \pounds1,000 is actually taxed:~--

<<>>=
incometax(6009, 5000)
@

\pagebreak
With no Personal Allowance, an annual income of \pounds1,009 is taxed similarly:~--
 
<<>>=
incometax(1009, 0)
@

Annual income above the Personal Allowance attracts \Sexpr{basicrate}\% basic rate tax up to the
basic rate band limit of \Sexpr{prettyL(basicband)}, at which basic rate tax reaches a maximum of
\Sexpr{prettyL(basicrate * basicband / 100)}:~--

<<>>=
incometax(12579 + 37700)

incometax(5009 + 37700, 5000)

incometax(9 + 37700, 0)
@

\pagebreak
\subsection{Income above the basic rate band}
Annual income above the \Sexpr{prettyL(std_allow)} standard Personal Allowance plus the
\Sexpr{prettyL(basicband)} basic rate band and the additional \pounds9 (total
\Sexpr{prettyL(std_allow + basicband + 9)}) attracts \Sexpr{higherrate}\% higher rate tax. For
instance, at an annual income of \Sexpr{prettyL(std_allow + basicband + 9 + 1000)}, while "Taxable
Income" is shown as \Sexpr{prettyL(basicband + 9 + 1000)}, only \Sexpr{prettyL(basicband + 1000)}
is actually taxed; \Sexpr{prettyL(basicband)} at the \Sexpr{basicrate}\% basic rate and
\pounds{1,000} at the \Sexpr{higherrate}\% higher rate:~--

<<>>=
incometax(51279)
@

An annual income of \Sexpr{prettyL(5000 + basicband + 9 + 1000)} i.e., \pounds1,000 above a bespoke
Personal Allowance of \pounds5,000 plus the \Sexpr{prettyL(basicband)} basic rate band and the
additional \pounds9 (total \Sexpr{prettyL(5000 + basicband + 9)}) similarly attracts
\Sexpr{higherrate}\% higher rate tax; again, while "Taxable Income" is shown as
\Sexpr{prettyL(basicband + 9 + 1000)}, only \Sexpr{prettyL(basicband + 1000)} is actually taxed:~--

<<>>=
incometax(43709, 5000)
@

With no Personal Allowance, an annual income of \Sexpr{prettyL(basicband + 9 + 1000)} is taxed
similarly:~--

<<>>=
incometax(38709, 0)
@

\subsection{Income above the Personal Allowance limit}
The standard Personal Allowance applies to annual income up to an upper limit of
\Sexpr{prettyL(allow_upper)}:~--

<<>>=
incometax(100000)
@

For every \pounds2 of income above this \Sexpr{prettyL(allow_upper)} limit,
the Personal Allowance decreases by~\pounds1:~--

<<>>=
incometax(104000)

incometax(120000)
@

Hence, at an annual income of \Sexpr{prettyL(allow_upper + std_allow * 2)}, Personal Allowance is
zero:~--

<<>>=
incometax(125140)
@

\subsection{Income above the higher rate band}
Annual income more than \pounds6 above the sum of the basic and higher rate bands
(\Sexpr{prettyL(sumband)}), i.e., above \Sexpr{(prettyL(sumband + 6))}, attracts additional rate
tax:~--

<<>>=
incometax(125139 + 6)

incometax(125139 + 6 + 1)
@

The allowance of \pounds6 before additional rate tax is applied goes down by \pounds1 for
every \pounds2 of income beyond \Sexpr{prettyL(sumband + 7)}:~--

<<>>=
incometax(125139 + 4 + 7)
7 * 0.45
@

Annual income more than \pounds18 above \Sexpr{prettyL(sumband)} attracts the full amount of
additional rate tax:~--

<<>>=
incometax(125139 + 19)
19 * 0.45

incometax(125139 + 10000)
@

\subsection{Income with a pay adjustment}
Specifying a \href{https://www.gov.uk/tax-codes/k-in-your-tax-code}{K code pay adjustment}
using a negative value for argument \code{allowance}:~--

<<>>=
incometax(125139, -10000)
@

In this last example the result is equivalent to that obtained by adding the value of the pay
adjustment to argument \code{income} (viz. the penultimate example):~--

<<>>=
all.equal(incometax(125139, -10000), incometax(125139 + 10000), check.attributes = FALSE)
@

However, that equivalence may not always be the case:~--

<<>>=
incometax(100000, -1000)

incometax(100000 + 1000)
@

\section{Calculating a Bespoke Personal Allowance \\or Pay Adjustment}
\subsection{Calculating an \emph{exact} Personal Allowance}
The \emph{exact} Personal Allowance required to recoup a given tax deficit may be calculated using
\code{allowance()} with its third argument \code{round10 = FALSE}. For example, at an annual income
of \pounds10,000 i.e., below the \Sexpr{prettyL(std_allow)} standard Personal Allowance and not
usually attracting any income tax, the Personal Allowance required to recoup a tax deficit of
\pounds600 is:~--

<<>>=
allowance(10000, 600, FALSE)
@

As intended using this Personal Allowance, an \emph{exact} total of \pounds600 income tax is
recouped:~--

<<>>=
incometax(10000, 6991)
@

\subsection{Calculating a \emph{rounded} Personal Allowance}
In practice, this deficit would be recouped through use of a tax code in which the last digit of the
required Personal Allowance is replaced with the letter \textsf{L} e.g., in the previous example
\textsf{699L}; see
\href{https://www.gov.uk/tax-codes/what-your-tax-code-means}{What your tax code means}. The
corresponding Personal Allowance rounded down\footnote{Rounding \emph{down} the Personal Allowance
  ensures recoup of a sum of tax \emph{not less than} that required.} to the nearest \pounds10 is
obtained using \code{allowance()} with its third argument \code{round10 = TRUE} (the~default):~--

<<>>=
allowance(10000, 600)
@

As intended using this Personal Allowance, a total of \emph{at least} \pounds600 income tax is
recouped:~--

<<>>=
incometax(10000, 6990)
@

An annual income of \Sexpr{prettyL(std_allow + 1009)} i.e., \pounds1,009 above the
\Sexpr{prettyL(std_allow)} standard Personal Allowance, usually attracts \pounds200 total income
tax:~--

<<>>=
incometax(13579)
@

At this income, the Personal Allowance required to recoup an \emph{additional} \pounds600 tax\\
deficit is:~--

<<>>=
allowance(13579, 200 + 600)
@

\pagebreak
As intended using this Personal Allowance, a total of \emph{at least} \pounds800 income tax is
recouped i.e., an additional amount of at least \pounds600:~--

<<>>=
incometax(13579, 9570)
@

At the standard Personal Allowance, an annual income of
\Sexpr{prettyL(std_allow + basicband + 1009)} i.e., \pounds1,009 above the basic rate band, usually
attracts \pounds7,940 total income tax:~--

<<>>=
incometax(51279)
@

At this income, the Personal Allowance required to recoup an \emph{additional} \pounds1,200 tax\\
deficit is:~--

<<>>=
allowance(51279, 7940 + 1200)
@

As intended using this Personal Allowance, a total of \emph{at least} \pounds9,140 income tax is
recouped i.e., an additional amount of at least \pounds1,200:~--

<<>>=
incometax(51279, 9570)
@

\pagebreak
\subsection{Calculating a Pay Adjustment}
A tax deficit too large to recoup through a reduction in Personal Allowance may instead be recouped
using a \href{https://www.gov.uk/tax-codes/k-in-your-tax-code}{pay adjustment}. For example, an
annual income of \Sexpr{prettyL(allow_upper + std_allow)}, at which the standard Personal Allowance
decreases by half to \Sexpr{prettyL(std_allow / 2)}, usually attracts a total of
\Sexpr{prettyL(sum(incometax(allow_upper + std_allow)))} income tax:~--

<<>>=
incometax(112570)
@

At this income, even to remove the Personal Allowance entirely would be insufficient to recoup, say,
an \emph{additional} deficit of~\pounds3,500 tax i.e., a total of
\Sexpr{prettyL(sum(incometax(112570), 3500))} income tax:~--

<<>>=
incometax(112570, 0)
@

Consequently, \code{allowance()} returns a negative value, indicating that a pay adjustment is
required instead:~--

<<>>=
allowance(112570, 34970.4 + 3500)
@

Passing a negative value as the second (\code{allowance}) argument of \code{incometax()} signifies a
pay adjustment; taxable income is adjusted to
\Sexpr{prettyL(attr(incometax(allow_upper + std_allow, -2460), "taxable"))} and as intended, a total
of \emph{at least} \Sexpr{prettyL(sum(incometax(112570), 3500))} income tax is recouped i.e., an
additional amount of  at least \pounds3,500:~--

<<>>=
incometax(112570, -2460)
@

\end{document}