matrixStats (version 1.2.0)

rowVars: Variance estimates for each row (column) in a matrix

Description

Variance estimates for each row (column) in a matrix.

Usage

rowVars(x, rows = NULL, cols = NULL, na.rm = FALSE, refine = TRUE,
  center = NULL, dim. = dim(x), ..., useNames = TRUE)
colVars(x, rows = NULL, cols = NULL, na.rm = FALSE, refine = TRUE,
  center = NULL, dim. = dim(x), ..., useNames = TRUE)

Value

Returns a numeric

vector of length N (K).

Arguments

x

An NxK matrix or, if dim. is specified, an N * K vector.

rows

A vector indicating subset of rows to operate over. If NULL, no subsetting is done.

cols

A vector indicating subset of columns to operate over. If NULL, no subsetting is done.

na.rm

If TRUE, missing values are excluded.

refine

If TRUE, `center` is NULL, and x is numeric, then extra effort is used to calculate the average with greater numerical precision, otherwise not.

center

(optional; a vector or length N (K)) If the row (column) means are already estimated, they can be pre-specified using this argument. This avoid re-estimating them again. _Warning: It is important that a non-biased sample mean estimate is passed. If not, then the variance estimate of the spread will also be biased._ If NULL (default), the row/column means are estimated internally.

dim.

An integer vector of length two specifying the dimension of x, also when not a matrix. Comment: The reason for this argument being named with a period at the end is purely technical (we get a run-time error if we try to name it dim).

...

Additional arguments passed to rowMeans() and rowSums().

useNames

If TRUE (default), names attributes of the result are set, otherwise not.

Providing center estimates

The sample variance is estimated as

\(n/(n-1) * mean((x - center)^2)\),

where \(center\) is estimated as the sample mean, by default. In matrixStats (< 0.58.0),

\(n/(n-1) * (mean(x^2) - center^2)\)

was used. Both formulas give the same result _when_ `center` is the sample mean estimate.

Argument `center` can be used to provide an already existing estimate. It is important that the sample mean estimate is passed. If not, then the variance estimate of the spread will be biased.

For the time being, in order to lower the risk for such mistakes, argument `center` is occasionally validated against the sample-mean estimate. If a discrepancy is detected, an informative error is provided to prevent incorrect variance estimates from being used. For performance reasons, this check is only performed once every 50 times. The frequency can be controlled by R option `matrixStats.vars.formula.freq`, whose default can be set by environment variable `R_MATRIXSTATS_VARS_FORMULA_FREQ`.

Author

Henrik Bengtsson

See Also

See rowMeans() and rowSums() in colSums().

Examples

set.seed(1)

x <- matrix(rnorm(20), nrow = 5, ncol = 4)
print(x)

# Row averages
print(rowMeans(x))
print(rowMedians(x))

# Column averages
print(colMeans(x))
print(colMedians(x))


# Row variabilities
print(rowVars(x))
print(rowSds(x))
print(rowMads(x))
print(rowIQRs(x))

# Column variabilities
print(rowVars(x))
print(colSds(x))
print(colMads(x))
print(colIQRs(x))

# Row ranges
print(rowRanges(x))
print(cbind(rowMins(x), rowMaxs(x)))
print(cbind(rowOrderStats(x, which = 1), rowOrderStats(x, which = ncol(x))))

# Column ranges
print(colRanges(x))
print(cbind(colMins(x), colMaxs(x)))
print(cbind(colOrderStats(x, which = 1), colOrderStats(x, which = nrow(x))))


x <- matrix(rnorm(2000), nrow = 50, ncol = 40)

# Row standard deviations
d <- rowDiffs(x)
s1 <- rowSds(d) / sqrt(2)
s2 <- rowSds(x)
print(summary(s1 - s2))

# Column standard deviations
d <- colDiffs(x)
s1 <- colSds(d) / sqrt(2)
s2 <- colSds(x)
print(summary(s1 - s2))