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:

1 2 3 4 5 6 7 8 9 10 11 12 | ```
> 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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 | ```
## 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
``` |

Questions? Problems? Suggestions? Tweet to @rdrrHQ or email at ian@mutexlabs.com.

All documentation is copyright its authors; we didn't write any of that.