rowVars: Variance estimates for each row (column) in a matrix
In HenrikBengtsson/matrixStats: Functions that Apply to Rows and Columns of Matrices (and to Vectors)

rowVars

R Documentation

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)

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.

Value

Returns a numeric vector of length N (K).

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(s)

Henrik Bengtsson

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))

HenrikBengtsson/matrixStats documentation built on Nov. 15, 2024, 3:20 p.m.