% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/aarr.R
\name{aarr}
\alias{aarr}
\title{Average Annual Rate of Reduction (AARR)}
\usage{
aarr(year, value, method = c("regression", "endpoint"), na.rm = TRUE)
}
\arguments{
\item{year}{Numeric vector of years.}

\item{value}{Numeric vector of indicator values, the same length as
\code{year}. Values must be positive (the computation is on the log
scale); any zero or negative value yields \code{NA_real_} with a
warning.}

\item{method}{Character. \code{"regression"} (default) or \code{"endpoint"}.
See Details.}

\item{na.rm}{Logical. Should pairs with a missing \code{year} or \code{value}
be removed before computation? Default \code{TRUE}. When \code{FALSE}, any
missing element makes the result \code{NA_real_}.}
}
\value{
A numeric scalar: the average annual rate of reduction as a
\emph{fraction} (\code{0.024} = 2.4\% per year). Multiply by 100 to compare
with published WHO / UNICEF tables, which print percentages.
Returns \code{NA_real_} (with a warning) when fewer than two distinct
years remain after \code{NA} handling, when any value is zero or
negative, or when \code{year} or \code{value} contains non-finite values.
}
\description{
Computes the average annual rate of reduction of an indicator over
time — the standard WHO / UNICEF metric for tracking progress in
declining indicators such as maternal, neonatal, and under-five
mortality, stunting prevalence, or premature NCD mortality.
}
\details{
Two estimation methods are offered:
\itemize{
\item \code{"regression"} (default; the UNICEF-recommended approach): an
ordinary least-squares line is fitted to \code{log(value)} against
\code{year}, and the AARR is \code{1 - exp(b)}, where \code{b} is the fitted
slope. All observations contribute, so the estimate is robust to
noise in individual years.
\item \code{"endpoint"}: only the earliest and latest years are used:
\code{1 - (v1 / v0) ^ (1 / (y1 - y0))}, where \code{v0} and \code{v1} are the
values at the earliest year \code{y0} and the latest year \code{y1}.
Intermediate observations are ignored. If several observations
share the earliest or latest year, their mean is used (but see
the note on duplicated years below).
}

\strong{Sign convention.} A \emph{positive} AARR means the indicator is
\emph{declining} (progress, for a mortality-type indicator): \code{0.024}
means an average decline of 2.4\% per year. A \emph{negative} AARR means
the indicator is increasing. Note this is the reverse of a growth
rate.

\strong{Duplicated years} usually mean the data still mix several strata
— for example both sexes plus male / female in \code{dim1}, or several
\code{series} codes in data cleaned by \code{\link[=gho_clean]{gho_clean()}} / \code{\link[=sdg_clean]{sdg_clean()}}.
\code{aarr()} warns and proceeds (the regression pools the strata), but
you almost always want to filter to a single stratum first.

\strong{Relation to published figures.} Published WHO / UNICEF tables
print the AARR as a percentage (\code{4.4} meaning 4.4\% per year);
multiply the value returned by this function by 100 to compare.
Note also that WHO's \emph{Trends in Maternal Mortality} reports print a
continuous-time rate, \code{-log(v1 / v0) / (y1 - y0)} (there called
ARR), which agrees closely but not exactly with the discrete AARR
computed here — small differences from those tables are expected.
}
\examples{
# A perfectly exponential 2.4\%/yr decline recovers exactly 0.024
years  <- 2000:2015
values <- 100 * (1 - 0.024) ^ (years - 2000)
aarr(years, values)                       # 0.024
100 * aarr(years, values)                 # 2.4 — as printed in reports

# Endpoint method uses only the earliest and latest years
aarr(years, values, method = "endpoint")  # also 0.024 here

# An increasing indicator gives a negative AARR
aarr(2010:2020, 50 * 1.01 ^ (0:10))       # about -0.01

# Back-of-envelope projection to 2030 at the observed AARR
r <- aarr(years, values)
values[length(values)] * (1 - r) ^ (2030 - 2015)
}
\seealso{
\code{\link[=geomean]{geomean()}} for ratio-based indicator aggregation.
}
