Uniform Rectangular Data Functions

DESCRIPTION:

Functions that allow you to access all rectangular data objects in the same way. Rectangular data objects include matrices, data frames, bdFrames, atomic vectors, and bdVectors. as.rectangular converts any object to a rectangular data object (usually a data frame or bdFrame), if possible. is.rectangular tests whether an object is rectangular. subscript2d is for subscripting. numRows and numCols count the number of rows and columns, and rowIds and colIds (and rownames and colnames) return the row and column names or other identifiers attached to rows and columns. subscript2d, numRows, numCols, rowIds, colIds, rownames and colnames can also be used on the left side of assignments.

USAGE:

as.rectangular(x) 
as.char.rect(x) 
is.rectangular(x) 
subscript2d(x,i,j) 
subscript2d(x,i,j) <- value
numRows(x) 
NROW(x)
numRows(x) <- value
numCols(x) 
NCOL(x)
numCols(x) <- value
rowIds(x) 
rowIds(x) <- value
colIds(x) 
colIds(x) <- value
rownames(x, do.NULL=TRUE, prefix="row") 
rownames(x) <- value
colnames(x, do.NULL=TRUE, prefix="col") 
colnames(x) <- value

REQUIRED ARGUMENTS:

x
object to be converted to rectangular data ( as.rectangular), or a rectangular data object.

OPTIONAL ARGUMENTS:

i
first (row) subscript.
j
second (column) subscript.
do.NULL
a logical value. If FALSE, then return created names if the object's row ( rownames) or column ( colnames) names are NULL.
prefix
a character string to use as the prefix when creating row or column names.

VALUE:

as.rectangular returns x if it is already rectangular, or as.data.frame(x) if it is not.

as.char.rect takes a rectangular object and returns a rectangular object consisting of character strings, suitable for printing (but not formatted to fixed width).

is.rectangular returns TRUE if x is rectangular, and FALSE if it is not.

subscript2d(x,i,j) is like x[i,j,drop=F], except that it allows x[,1] (for example) for atomic vectors as well. It usually returns an object of the same class as x (this is not appropriate for some objects, e.g. "bs" objects). It does not support a drop argument.

numRows and numCols return integers, like nrow and ncol, except that they also work on atomic vectors ( numRows returns the length of the vector, and numCols returns 1).

rowIds and colIds return the IDs of the rows and columns. These are often character vectors or bdCharacters, but need not be, depending on the class of x. They are like the components of dimnames, except that for named vectors or bdVectors, rowIds returns or sets the names (though colIds returns NULL).

colnames and rownames return the same values as colIds and rowIds, respectively, if do.NULL=T. But if do.NULL=F and the row or column names are NULL, then a character vector of the appropriate length is created by prepending prefix to a sequence of integers beginning with "1".

DETAILS:

subscript2d used in an assignment does not allow subscript replacement outside the bounds of x; instead you should set numRows or numCols first. When numRows or numCols is used in an assignment, the row and column IDs will be maintained to have the correct length. Usually, this is done by setting numRows on the ID vector, but for some objects (for example, data frames) this may not be appropriate and they have their own methods.

The value may be a character vector, or anything that can be coerced to a character vector. However, it should not be a bdCharacter or other bdVector; you can convert these to an ordinary vector using bd.coerce

Instead of using names to replace row names from a matrix, use rowIds or dimnames.

The functions colnames, rownames, colnames<-, rownames<-, NROW, and NCOL emulate R functions of the same names. Functions colnames<- and rownames<- simply call colIds<- and rowIds<-, respectively. Functions NROW and NCOL call numRows and numCols, respectively. colnames and rownames return the same values as colIds and rowIds, respectively, if do.NULL=T.

NOTE:

subscript2d used to be called sub. This name conflicted with that of an R (and perl) function that does what the S-PLUS substituteString does so it was renamed for S-PLUS 8.0.

SEE ALSO:

, , , , .

EXAMPLES:

x <- 1:10 
y <- list(a=1:10, b=11:20) 
is.rectangular(x) 
y <- as.rectangular(y) 
subscript2d(x,3,1) 
subscript2d(y,4,1) <- 55 
numRows(x) 
numCols(y) <- 3 
rowIds(x) <- letters[1:10] 
colIds(y) 
z <- cbind(1,1:4)
colnames(z, do.NULL = FALSE)
colnames(z) <- colnames(z, do.NULL = FALSE)
rownames(z) <- rownames(z, do.NULL = FALSE, prefix="R")