annmatrix {annmatrix}

annmatrix Objects and Basic Functionality

Description

Annotated matrix is a regular matrix with additional functionality for attaching persistent information about row and column entries. Annotations associated with rows and columns are preserved after subsetting, transposition, and various other matrix-specific operations.

Intended 'annmatrix' use case is for storing and manipulating genomic datasets that typically consist of a matrix of measurements (like gene expression values) as well as annotations about rows (i.e. genomic locations) and annotations about columns (i.e. meta-data about collected samples). But annmatrix objects are also expected be useful in various other contexts.

Usage

annmatrix(x, rann, cann)

rowanns(x, names)
rowanns(x, names) <- value

colanns(x, names)
colanns(x, names) <- value

## S3 method for class 'annmatrix'
@(object, name)
## S3 replacement method for class 'annmatrix'
@(object, name) <- value

## S3 method for class 'annmatrix'
x$name
## S3 replacement method for class 'annmatrix'
x$name <- value

Arguments

x, object

an R object.

rann

annotation data.frame for rows of the annmatrix object.

cann

annotation data.frame for columns of the annmatrix object.

names

a character vector of existing row/column annotation names.

value

a value that will be assigned to row/column annotation field.

name

a name of an existing row/column annotation.

Details

annmatrix() constructs an annmatrix. The function expects x to be a matrix and rowanns and colanns to be of class data.frame. If the passed objects are of a different classes they will be converted via the use of as.matrix and as.data.frame.

rowanns and colanns returns the selected field from column and row annotations respectively. When the selected field is not specified the whole annotation data.frame is returned.

@ and $ are convenience shortcuts for selecting annotations. X@value selects an existing column from row annotations while X$value selects a column from column annotations. An empty selection of X@'' and X$'' will return the whole annotation data.frame for rows and columns respectively.

rowanns<- and colanns<- functions can be used to replace the column and row annotations respectively. When the selected field is not specified the whole annotation data.frame is replaced.

@<- and $<- are convenience shortcuts for the above (see Examples). A replacement of an empty value - X@'' <- df and X$'' <- df will replace the whole annotation data.frame.

Value

annmatrix returns an R object of class 'annmatrix'.

Author(s)

Karolis Koncevičius

See Also

as.annmatrix

Examples

# construct annmatrix object
x <- matrix(rnorm(20*10), 20, 10)

coldata <- data.frame(group  = rep(c("case", "control"), each = 5),
                      gender = sample(c("M", "F"), 10, replace = TRUE))

rowdata <- data.frame(chr = sample(c("chr1", "chr2"), 20, replace = TRUE),
                      pos = runif(20, 0, 1000000))

X <- annmatrix(x, rowdata, coldata)

is.matrix(x)
is.matrix(X)

is.annmatrix(x)
is.annmatrix(X)

# manipulating annotations without using shortcuts
rowanns(X)
colanns(X)

rowanns(X, "chr")
rowanns(X, "gene") <- letters[1:20]
rowanns(X, c("chr", "gene"))
rowanns(X, "gene") <- NULL
rowanns(X)

colanns(X, "group")
colanns(X, "age") <- 1:10*10
colanns(X, "age")
colanns(X, "age") <- NULL
colanns(X, "age")

# more convenient
X@''
X@chr
X@gene <- letters[1:20]
X@gene
X@gene <- NULL
X@gene

X$''
X$group
X$age <- 1:10*10
X$age
X$age <- NULL
X$age
X$'' <- data.frame(id = 1:10, name = LETTERS[1:10])
X$name

# annotations are preserved after subsetting
Y <- X[X@chr == "chr1", X$name %in% c("A", "B", "C")]
Y@chr
Y$''

Y[, 1]
Y[, 1, drop = FALSE]