% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/outliers.R
\name{outliers}
\alias{outliers}
\alias{hb_transform}
\title{Outlier detection for price relatives}
\usage{
outliers(
  x,
  upper,
  lower = upper,
  method = c("quartile", "resistant-fences", "kimber", "robust-z", "tukey"),
  scale = 0,
  quantile_type = 7
)

hb_transform(x)
}
\arguments{
\item{x}{\verb{[numeric > 0]} A numeric vector, usually of price relatives.
These can be made with, e.g., \code{\link[=back_period]{back_period()}}.}

\item{upper, lower}{\verb{[numeric(1) > 0]} A number giving the upper and lower
cutoffs for
each element of \code{x}. By default the lower cutoff is the same as the upper
cutoff}

\item{method}{\verb{[character(1)]} The outlier detection method, one of
\code{"quartile"} (the default), \code{"resistant-fences"}, \code{"kimber"}, \code{"robust-z"},
or \code{"tukey"}.}

\item{scale}{\verb{[0 <= numeric(1) <= 1]} A number between 0 and 1 giving the
scale factor for the
median to establish the minimum dispersion between quartiles for each
element of \code{x}. The default does not set a minimum dispersion.}

\item{quantile_type}{\verb{[integer(1)]} See \code{\link[=quantile]{quantile()}}.}
}
\value{
A logical vector, the same length as \code{x}, that is \code{TRUE} if the
corresponding element of \code{x} is identified as an outlier,
\code{FALSE} otherwise.
}
\description{
Standard cutoff-based methods for detecting outliers with price relatives.
}
\details{
This function constructs an interval of the form \eqn{[b_l(x) -
c_l \times l(x), b_u(x) + c_u \times u(x)]}{[bl(x) - cl * l(x), bu(x) + cu *
u(x)]} and assigns a value in \code{x} as \code{TRUE} if that value does not
belong to the interval, \code{FALSE} otherwise. The different methods differ in
how they construct the values \eqn{b_l(x)}{bl(x)}, \eqn{b_u(x)}{bu(x)},
\eqn{l(x)}, and \eqn{u(x)}. Any missing values in \code{x} are ignored when
calculating the interval, but will return \code{NA}.

The quartile method and Tukey algorithm are described in paragraphs 5.113 to
5.135 of the CPI manual (2020).
The resistant fences method is an alternative to the quartile method, and is
described by Rais (2008) and Hutton (2008). The Kimber method is yet another
alternative. Quantile-based methods often
identify price relatives as outliers because the distribution is
concentrated around 1; setting \code{scale > 0} puts a floor on the minimum
dispersion between quantiles as a fraction of the median. See the references
for more details.\tabular{lllll}{
    \tab \eqn{b_l(x)}{bl(x)} \tab \eqn{b_u(x)}{bu(x)} \tab \eqn{l(x)} \tab \eqn{u(x)} \cr
   Quartile \tab \eqn{Q_2(x)} \tab \eqn{Q_2(x)} \tab \eqn{Q_2(x) - Q_1(x)} \tab \eqn{Q_3(x) - Q_2(x)} \cr
   Resistant fences \tab \eqn{Q_1(x)} \tab \eqn{Q_3(x)} \tab \eqn{Q_3(x) - Q_1(x)} \tab \eqn{Q_3(x) - Q_1(x)} \cr
   Kimber \tab \eqn{Q_1(x)} \tab \eqn{Q_3(x)} \tab \eqn{Q_2(x) - Q_1(x)} \tab \eqn{Q_3(x) - Q_2(x)} \cr
}


The robust Z-score is the usual method to identify relatives in the
(asymmetric) tails of the distribution, simply replacing the mean with the
median, and the standard deviation with the median absolute deviation.

These methods often assume that price relatives are symmetrically
distributed (if not Gaussian). As the distribution of price relatives often
has a long right tail, the natural logarithm can be used to transform price
relative before identifying outliers (sometimes under the assumption that
price relatives are distributed log-normal). The Hidiroglou-Berthelot
transformation is another approach, described in the CPI manual (par.
5.124). (Sometimes the transformed price relatives are multiplied by
\eqn{\max(p_1, p_0)^u}{max(p1, p0)^u}, for some
\eqn{0 \le u \le 1}{0 <= u <= 1}, so that products with a larger price
get flagged as outliers (par. 5.128).)
}
\examples{
x <- c(1, 10, 15, 100)

outliers(x, upper = 2.5, method = "quartile")

# Always identifies fewer outliers than above.
outliers(x, upper = 2.5, method = "resistant-fences")
}
\references{
Hutton, H. (2008). Dynamic outlier detection in price index surveys.
\emph{Proceedings of the Survey Methods Section: Statistical Society of Canada
Annual Meeting}.

IMF, ILO, Eurostat, UNECE, OECD, and World Bank. (2020).
\emph{Consumer Price Index Manual: Concepts and Methods}.
International Monetary Fund.

Rais, S. (2008). Outlier detection for the Consumer Price Index.
\emph{Proceedings of the Survey Methods Section: Statistical Society of Canada
Annual Meeting}.
}
\seealso{
\code{\link[=back_period]{back_period()}} for a simple utility function to turn prices
in a table into price relatives.

The \code{HBmethod()} function in the \pkg{univOutl} package for the
Hidiroglou-Berthelot method for identifying outliers.
}
