bigmemory (version 2.3)

big.matrix, is.big.matrix, as.big.matrix: The basic ``big.matrix'' operations.

Description

Create a big.matrix (or check to see if an object is a big.matrix, or create a big.matrix from a matrix).

Usage

big.matrix(nrow, ncol, type = "integer", init = 0, dimnames = NULL)
as.big.matrix(x, type = "integer")
is.big.matrix(x)

Arguments

x

an object; if a vector, a one-column big.matrix is created by as.big.matrix.

nrow

number of rows.

ncol

number of columns.

type

the type of the atomic element ("integer" by default).

init

a scalar value for initializing the matrix (0 by default).

dimnames

a list of the row and column names.

Value

• A big.matrix is returned (for big.matrix and as.big.matrix), and TRUE or FALSE for is.big.matrix.

Details

A big.matrix consists of an object in R that does little more than point to the data structure implemented in C++. The object acts much like a traditional R matrix, but helps protect the user from many inadvertant memory-consuming pitfalls of traditional R matrices and data frames.

Four atomic types are implemented (see argument type, above) to help provide memory efficiency in different applications: double (equivalent to numeric in R), integer (using 4 bytes), short (using 2 bytes), and char (using a single byte).

If x is a big.matrix, then x[1:5,] is returned as an R matrix containing the first five rows of x. If x is of type double, then the result will be numeric; otherwise, the result will be an integer R matrix. The expression x alone will display information about the R object (e.g. the type) rather than evaluating the matrix itself (the user should try x[,] with extreme caution, recognizing that a huge R matrix will be created).

If x has a huge number of rows, then the use of rownames will be extremely memory-intensive and should be avoided. If x has a huge number of columns, the user might want to store the transpose as there is overhead of a pointer for each column in the matrix.

Finally, when a big.matrix, x, is passed as an argument to a function, it is essentially providing call-by-reference rather than call-by-value behavior. If the function modified any of the values of x within the function, the changes are not limited in scope to a local copy within the function.

See Also

bigmemory, and perhaps the class documentation of big.matrix.

Examples

x <- big.matrix(10, 2, type='integer', init=-5)
colnames(x) = c("alpha", "beta")
is.big.matrix(x)
dim(x)
colnames(x)
rownames(x)
x[1:8,1] <- 11:18
x[,]
colmin(x)
colmax(x)
colrange(x)
colsum(x)
colprod(x)
colmean(x)
colvar(x)
summary(x)

x <- as.big.matrix(matrix(-5, 10, 2))
colnames(x) <- c("alpha", "beta")
is.big.matrix(x)
dim(x)
colnames(x)
rownames(x)
x[1:8,1] <- 11:18
x[,]
colmin(x)
colmax(x)
colsum(x)
colprod(x)
colmean(x)
colvar(x)
colrange(x)
summary(x)