# Class "NumericMatrix" and friends

### Description

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".

### Details

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 from the Class

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.

### Slots

None.

### Extends

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.

### Methods

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

### Author(s)

Martin Morgan <mtmorgan@fhcrc.rog

### Examples

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
``` |