% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rowAvgsPerColSet.R
\name{rowAvgsPerColSet}
\alias{rowAvgsPerColSet}
\alias{colAvgsPerRowSet}
\title{Applies a row-by-row (column-by-column) averaging function to equally-sized
subsets of matrix columns (rows)}
\usage{
rowAvgsPerColSet(X, W = NULL, rows = NULL, S, FUN = rowMeans, ...,
  na.rm = NA, tFUN = FALSE)

colAvgsPerRowSet(X, W = NULL, cols = NULL, S, FUN = colMeans, ...,
  na.rm = NA, tFUN = FALSE)
}
\arguments{
\item{X}{A \code{\link[base]{numeric}} NxM \code{\link[base]{matrix}}.}

\item{W}{An optional \code{\link[base]{numeric}} NxM
\code{\link[base]{matrix}} of weights.}

\item{rows}{A \code{\link[base]{vector}} indicating subset of rows to
operate over. If \code{\link[base]{NULL}}, no subsetting is done.}

\item{S}{An \code{\link[base]{integer}} KxJ \code{\link[base]{matrix}}
specifying the J subsets.  Each column holds K column (row) indices for the
corresponding subset.}

\item{FUN}{The row-by-row (column-by-column) \code{\link[base]{function}}
used to average over each subset of \code{X}.  This function must accept a
\code{\link[base]{numeric}} NxK (KxM) \code{\link[base]{matrix}} and the
\code{\link[base]{logical}} argument \code{na.rm}, and return a
\code{\link[base]{numeric}} \code{\link[base]{vector}} of length N (M).}

\item{...}{Additional arguments passed to then \code{FUN}
\code{\link[base]{function}}.}

\item{na.rm}{(logical) Argument passed to \code{FUN()} as
\code{na.rm = na.rm}.  If \code{\link[base:logical]{NA}} (default), then
\code{na.rm = TRUE} is used if \code{X} or \code{S} holds missing values,
otherwise \code{na.rm = FALSE}.}

\item{tFUN}{If \code{\link[base:logical]{TRUE}}, the NxK (KxM)
\code{\link[base]{matrix}} passed to \code{FUN()} is transposed first.}

\item{cols}{A \code{\link[base]{vector}} indicating subset of columns to
operate over. If \code{\link[base]{NULL}}, no subsetting is done.}
}
\value{
Returns a \code{\link[base]{numeric}} JxN (MxJ)
\code{\link[base]{matrix}}, where row names equal \code{rownames(X)}
(\code{colnames(S)}) and column names \code{colnames(S)}
(\code{colnames(X)}).
}
\description{
Applies a row-by-row (column-by-column) averaging function to equally-sized
subsets of matrix columns (rows).  Each subset is averaged independently of
the others.
}
\details{
If argument \code{S} is a single column vector with indices \code{1:N}, then
\code{rowAvgsPerColSet(X, S = S, FUN = rowMeans)} gives the same result as
\code{rowMeans(X)}.  Analogously, for \code{colAvgsPerRowSet()}.
}
\examples{
X <- matrix(rnorm(20 * 6), nrow = 20, ncol = 6)
rownames(X) <- LETTERS[1:nrow(X)]
colnames(X) <- letters[1:ncol(X)]
print(X)


# - - - - - - - - - - - - - - - - - - - - - - - - - -
# Apply rowMeans() for 3 sets of 2 columns
# - - - - - - - - - - - - - - - - - - - - - - - - - -
nbr_of_sets <- 3
S <- matrix(1:ncol(X), ncol = nbr_of_sets)
colnames(S) <- sprintf("s\%d", 1:nbr_of_sets)
print(S)

Z <- rowAvgsPerColSet(X, S = S)
print(Z)

# Validation
Z0 <- cbind(s1 = rowMeans(X[, 1:2]),
            s2 = rowMeans(X[, 3:4]),
            s3 = rowMeans(X[, 5:6]))
stopifnot(identical(drop(Z), Z0))


# - - - - - - - - - - - - - - - - - - - - - - - - - -
# Apply colMeans() for 5 sets of 4 rows
# - - - - - - - - - - - - - - - - - - - - - - - - - -
nbr_of_sets <- 5
S <- matrix(1:nrow(X), ncol = nbr_of_sets)
colnames(S) <- sprintf("s\%d", 1:nbr_of_sets)
print(S)

Z <- colAvgsPerRowSet(X, S = S)
print(Z)

# Validation
Z0 <- rbind(s1 = colMeans(X[  1:4, ]),
            s2 = colMeans(X[  5:8, ]),
            s3 = colMeans(X[ 9:12, ]),
            s4 = colMeans(X[13:16, ]),
            s5 = colMeans(X[17:20, ]))
stopifnot(identical(drop(Z), Z0))


# - - - - - - - - - - - - - - - - - - - - - - - - - -
# When there is only one "complete" set
# - - - - - - - - - - - - - - - - - - - - - - - - - -
nbr_of_sets <- 1
S <- matrix(1:ncol(X), ncol = nbr_of_sets)
colnames(S) <- sprintf("s\%d", 1:nbr_of_sets)
print(S)

Z <- rowAvgsPerColSet(X, S = S, FUN = rowMeans)
print(Z)

Z0 <- rowMeans(X)
stopifnot(identical(drop(Z), Z0))


nbr_of_sets <- 1
S <- matrix(1:nrow(X), ncol = nbr_of_sets)
colnames(S) <- sprintf("s\%d", 1:nbr_of_sets)
print(S)

Z <- colAvgsPerRowSet(X, S = S, FUN = colMeans)
print(Z)

Z0 <- colMeans(X)
stopifnot(identical(drop(Z), Z0))
}
\author{
Henrik Bengtsson
}
\keyword{internal}
\keyword{utilities}
