% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/emean.R
\name{emean}
\alias{emean}
\title{Extended mean}
\usage{
emean(x, y, order = c(0, 1), tol = .Machine$double.eps^0.5)
}
\arguments{
\item{x, y}{\verb{[numeric > 0]} A strictly positive numeric vector.}

\item{order}{\verb{[numeric(2)]} A pair of finite numbers giving the order of the
extended mean.
The default calculates the ordinary logarithmic mean. Setting either the
first or second element to 1 gives the generalized logarithmic mean.}

\item{tol}{\verb{[numeric > 0]} The tolerance used to determine if \code{x == y}.
The default value is the same as \code{\link[=all.equal]{all.equal()}}.}
}
\value{
A numeric vector, the same length as
\code{max(length(x), length(y))}, giving the component-wise extended mean
of \code{x} and \code{y}.
}
\description{
Calculate the component-wise extended mean.
}
\details{
The extended mean is also called the difference mean, Stolarsky mean, or
extended mean-value mean; see Bullen (2003, p. 393) for details.

Both \code{x} and \code{y} should be strictly positive. This is not enforced, but the
results may not make sense when the extended mean is not defined. The usual
recycling rules apply when \code{x} and \code{y} are not the same length.

By definition, the extended mean of \code{x}
and \code{y} is \code{x} when \code{x == y}. The \code{tol} argument is used
to test equality by checking if \code{abs(x - y) <= tol}.  In some cases it's
useful to multiply
\code{tol} by a scale factor, such as \code{max(abs(x), abs(y))}. This often
doesn't matter when making price indexes, however, as \code{x} and \code{y}
are usually around 1.
}
\examples{
x <- 8:5
y <- 1:4

# The arithmetic and geometric means are special cases of the
# generalized logarithmic mean.
all.equal(emean(x, y, c(2, 1)), (x + y) / 2)
all.equal(emean(x, y, c(-1, 1)), sqrt(x * y))

# The harmonic mean cannot be expressed as a logarithmic mean, but can
# be expressed as an extended mean.
all.equal(emean(x, y, c(-2, -1)), 2 / (1 / x + 1 / y))

# The quadratic mean is also a type of extended mean.
all.equal(emean(x, y, c(2, 4)), sqrt(x^2 / 2 + y^2 / 2))

# As are heronian and centroidal means.
all.equal(
  emean(x, y, c(0.5, 1.5)),
  (x + sqrt(x * y) + y) / 3
)
all.equal(
  emean(x, y, c(2, 3)),
  2 / 3 * (x^2 + x * y + y^2) / (x + y)
)
}
\references{
Bullen, P. S. (2003). \emph{Handbook of Means and Their Inequalities}.
Springer Science+Business Media.
}
\seealso{
Other math functions:
\code{\link[=gmean]{gmean()}},
\code{\link[=nested_gmean]{nested_gmean()}},
\code{\link[=scale_weights]{scale_weights()}},
\code{\link[=transmute_weights]{transmute_weights()}},
\code{\link[=transmute_weights2]{transmute_weights2()}},
\code{\link[=update_weights]{update_weights()}}
}
\concept{math functions}
