Matrix Objects

DESCRIPTION:

Creates or tests for matrices. There are different kinds of matrices; they all have two dimensions.

USAGE:

matrix(data=NA, nrow=<<see below>>, ncol=<<see below>>,  
        byrow=F, dimnames=NULL) 
is.matrix(x) 
as.matrix(x) 

REQUIRED ARGUMENTS:

x
any S-PLUS object.

OPTIONAL ARGUMENTS:

data
vector containing the data values for the matrix. Missing values ( NAs) are allowed.
nrow
first subscript, the number of rows. The default is ceiling(length(data)/ncol), that is, if ncol is specified, nrow is chosen to match the length of data. If neither nrow or ncol are specified, then nrow is the length of data and ncol is 1.
ncol
second subscript, the number of columns. If nrow is specified but ncol is not, then ncol is defined as: ceiling(length(data)/nrow).
byrow
logical flag: if TRUE, the data values are assumed to be the first row, then the second row, etc. If FALSE, the values are assumed to be the first column, then the second column, etc. (The latter is how the data are stored internally.)
dimnames
a list of length 2 giving a dimnames attribute for the matrix. Each component must either have length 0 or be a vector of character strings with length equal to the corresponding element of the dim attribute of the result.

VALUE:

matrix returns an nrow by ncol matrix with the same mode as data. If the data does not fill the matrix, it is repeated until the matrix is filled.

is.matrix returns TRUE if dim(x) is of length 2, and FALSE otherwise.

as.matrix returns x, if x is a matrix; otherwise, a matrix with data from x and dimension c(length(x),1).

DETAILS:

The as.matrix function is generic. It has a method for data frames and various other classes, and a default method.

Matrix objects are those that have an attribute dim of length 2. The objects may also have an attribute dimnames . If so, this is a list of 2 character vectors, each of which is either of length zero or else gives the labels corresponding to the levels of the corresponding subscript in the matrix.

If mat is a S-PLUS matrix, then as.vector(mat) is a vector containing the data values for mat in normal array order: the first subscript varies most rapidly.

The byrow argument should be set to TRUE if the data values were read from a file arranged by rows.

NOTE:

There are different types of matrices in S-PLUS. The simplest type is an ordinary matrix, which has class "matrix", a dim attribute of length 2, the product of the dimensions is the length of the object, and all elements have the same mode.

There are also objects like data frames and bdFrames, which have two dimensions, and can be subscripted like simple matrices, but which may have columns of different types. is.matrix returns TRUE for these objects, even though they do not have class "matrix".

as.matrix tries to produce a simple matrix. It converts a data frame into an ordinary matrix. It stops if passed a bdFrame. If you are confident that a bdFrame is small enough to fit into memory, then convert it to a data frame using , then convert that to a matrix using as.matrix.

matrix produces an ordinary matrix if x is ordinary data, and a bdFrame if x is a big data object.

If you wish to know if you can use two subscripts with an object, you may test it with is.matrix but if you want to do more with it, say matrix multiplication or decompositions, you must use as.matrix on it first. This is why you will see the seemingly nonsensical idiom if(is.matrix(x)) x <- as.matrix(x) else stop("Not a matrix").

SEE ALSO:

, , , , , , . You may prefer or to as.matrix for converting a data frame to an ordinary matrix; these handle character and factor columns differently.

EXAMPLES:

m <- matrix(0, 4, 5) # a 4 by 5 matrix of zeros 
matrix(1:10, 5) # a 5 by 2 matrix 
matrix(1:10, ncol=2) # the same thing 
mm <- matrix( scan("mfile"), ncol=5, byrow=TRUE) 
                    #read all rows from the file