Apache

Description Details Objects from the Class Slots Extends Methods Author(s) Examples

Classes providing matrix and array functionality, but allowing stronger type specification, e.g., NumericMatrix is a matrix whose members must be of type "numeric". A "matrix" is two-dimensional; an "array" is any dimensions, but R treats two-dimensional arrays as "matrix" and one-dimensional arrays as "vector" so "XxxArray" is most useful for specifying arrays with greater than 2 dimensions.

Available classes are "RawMatrix" "CharMatrix" "LogicalMatrix" "IntegerMatrix" "NumericMatrix" "ComplexMatrix" "RawArray" "CharArray" "LogicalArray" "IntegerArray" "NumericArray" "ComplexArray".

The following illustrates how to use these classes in R and Java, using NumericMatrix as an example.

The examples assume that mapping between R and Java uses the “javalib” type mode.

Suppose you would like an R function to return a matrix of numeric (double) values, and that you are using the “javalib” mode for mapping between R and Java (typeMode="javalib" in createMap, or typemode=javalib in the ant configuration file RWebServicesTuning.properties). For this type mode, specifying “matrix” as a return type is insufficient: a matrix could contain any basic type (raw, character, integer, double, complex, etc.), so there is not enough information to map to a Java object. The solution is to specify more clearly what the type of the return value is, for instance, if the return type is a matrix of numeric (double) values, then arrange for the function to return an object of class NumericMatrix.

In R the basic properties of NumericMatrix can be seen here:

        > nm=new("NumericMatrix", matrix(as.double(50:1),10,5))
    > dim(nm)
    [1] 10  5
    > nm[7,3]
    [1] 24
    > as.vector(nm)
     [1] 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33
    [19] 32 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15
    [37] 14 13 12 11 10  9  8  7  6  5  4  3  2  1
    > as.vector(nm)[(3-1)*nrow(nm)+7]
    [1] 24

The last line is meant to illustrate that the 'matrix' data in R is stored as a single vector, in 'column-major' order, i.e., elements 1:nrow(nm) are the first column, (nrow(nm)+1):(2*nrow(nm)) are the second column, etc.

In Java, dim=getDim() returns an int[], containing the number of rows and the number of columns, e.g., int[] = {10, 5} for the example above of columns in the matrix (like dim() would do on a matrix in R).

value=getValue() will return double[], containing all the data, like the result of as.vector above. Remembering that Java starts indexing at 0, we can get the element in row i and column j as

1	value[i * dim[0] + j]

We (or you) could write methods getMatrix / setMatrix returning / taking double[][] to do this, or getElement / setElement to access specific elements; it's worthwhile remembering that this does require quite a bit of memory allocation (for big arrays), so in some ways it's better to force the client to just give the data in the expected format anyway.

Objects can be created by calls of the form new("NumericMatrix", ...). To create an instance from an existing, untyped, "matrix" or "array", use forms like new("NumericMatrix", m) or unclass and update the mode of the object. See examples for additional detail.

None.

Class "matrix", from data part. Class "structure", by class "matrix", distance 2. Class "array", by class "matrix", distance 2. Class "vector", by class "matrix", distance 3, with explicit coerce. Class "vector", by class "matrix", distance 4, with explicit coerce.

Use "NumericMatrix" and friends as replacements for "matrix" or "array".

Martin Morgan <mtmorgan@fhcrc.rog

## creating an empty instance
obj <- new("ComplexMatrix")
obj
mode(obj)
## Converting between array and typed Array
new("RawArray", array(raw(), dim=c(5,2,3)))

## Converting between types
obj <- new("NumericMatrix", matrix(numeric()))
obj <- unclass(obj)                     # retrieve underlying matrix
mode(obj) <- "raw"
obj <- new("RawMatrix", obj)
validObject(obj)
obj