1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/weightedMean.R
3\name{weightedMean}
4\alias{weightedMean}
5\title{Weighted Arithmetic Mean}
6\usage{
7weightedMean(x, w = NULL, idxs = NULL, na.rm = FALSE, refine = FALSE, ...)
8}
9\arguments{
10\item{x}{An NxK \code{\link[base]{matrix}} or, if \code{dim.} is specified,
11an N * K \code{\link[base]{vector}}.}
12
13\item{w}{a vector of weights the same length as \code{x} giving the weights
14to use for each element of \code{x}. Negative weights are treated as zero
15weights. Default value is equal weight to all values.
16If a missing-value weight exists, the result is always a missing value.}
17
18\item{idxs}{A \code{\link[base]{vector}} indicating subset of elements to
19operate over. If \code{\link[base]{NULL}}, no subsetting is done.}
20
21\item{na.rm}{If \code{\link[base:logical]{TRUE}}, missing values are
22excluded.}
23
24\item{refine}{If \code{\link[base:logical]{TRUE}} and \code{x} is
25\code{\link[base]{numeric}}, then extra effort is used to calculate the
26average with greater numerical precision, otherwise not.}
27
28\item{...}{Not used.}
29}
30\value{
31Returns a \code{\link[base]{numeric}} scalar.  If \code{x} is of
32zero length, then \code{NaN} is returned, which is consistent with
33\code{\link[base]{mean}}().
34}
35\description{
36Computes the weighted sample mean of a numeric vector.
37}
38\section{Missing values}{
39
40This function handles missing values consistently with
41\code{\link[stats]{weighted.mean}}.  More precisely, if \code{na.rm = FALSE},
42then any missing values in either \code{x} or \code{w} will give result
43\code{NA_real_}.  If \code{na.rm = TRUE}, then all \code{(x, w)} data points
44for which \code{x} is missing are skipped.  Note that if both \code{x} and
45\code{w} are missing for a data points, then it is also skipped (by the same
46rule).  However, if only \code{w} is missing, then the final results will
47always be \code{NA_real_} regardless of \code{na.rm}.
48}
49
50\examples{
51x <- 1:10
52n <- length(x)
53
54w <- rep(1, times = n)
55m0 <- weighted.mean(x, w)
56m1 <- weightedMean(x, w)
57stopifnot(identical(m1, m0))
58
59# Pull the mean towards zero
60w[1] <- 5
61m0 <- weighted.mean(x, w)
62m1 <- weightedMean(x, w)
63stopifnot(identical(m1, m0))
64
65# Put even more weight on the zero
66w[1] <- 8.5
67m0 <- weighted.mean(x, w)
68m1 <- weightedMean(x, w)
69stopifnot(identical(m1, m0))
70
71# All weight on the first value
72w[1] <- Inf
73m0 <- weighted.mean(x, w)
74m1 <- weightedMean(x, w)
75stopifnot(identical(m1, m0))
76
77# All weight on the last value
78w[1] <- 1
79w[n] <- Inf
80m0 <- weighted.mean(x, w)
81m1 <- weightedMean(x, w)
82stopifnot(identical(m1, m0))
83
84# All weights set to zero
85w <- rep(0, times = n)
86m0 <- weighted.mean(x, w)
87m1 <- weightedMean(x, w)
88stopifnot(identical(m1, m0))
89}
90\seealso{
91\code{\link[base]{mean}}() and \code{\link[stats]{weighted.mean}}.
92}
93\author{
94Henrik Bengtsson
95}
96\keyword{robust}
97\keyword{univar}
98