SImageData-class: Class Containing Sparse Image Data

Description

A container class for holding pixel-sparse image as a virtual datacube. It is assumed there will be missing pixels, so the feature vectors are stored as a matrix for memory efficiency, and the datacube is reconstructed on-the-fly. The implementation remains efficient even for non-sparse data as long as the full datacube does not need to be reconstructed as often as single images and feature vectors. All elements of data must have an identical number of rows (features) and columns (pixels).

Usage

## Instance creation
SImageData( data = Hashmat(nrow=0, ncol=0), coord = expand.grid( x = seq_len(ncol(data)), y = seq_len(ifelse(ncol(data) > 0, 1, 0))), storageMode = "immutableEnvironment", positionArray = generatePositionArray(coord), dimnames = NULL, ...)
## Additional methods documented below

Arguments

data

A matrix-like object with number of rows equal to the number of features and number of columns equal to the number of non-missing pixels. Each column should be a feature vector. Alternatively, a multidimensional array that represents the datacube with the first dimension as the features can also be supplied. Additional dimensions could be the spatial dimensions of the image, for example.

coord

A data.frame with columns representing the spatial dimensions. Each row provides a spatial coordinate for the location of a feature vector corresponding to a column in data. This argument is ignored if data is a multidimensional array rather than a matrix.

storageMode

The storage mode to use for the SImageData object for the environment in the data slot. Only "immutableEnvironment" is allowed for SImageData. See documentation on the storageMode slot below for more details.

positionArray

The positionArray for the imaging data. This should not normally be specified the user, since it is generated automatically from the coord argument, unless for some reason coord is not specified.

dimnames

A list of length two, giving the feature names and pixel names in that order. If missing, this is taken from the 'dimnames' of the data argument.

...

Additional Named arguments that are passed to the initialize method for instantiating the object. These must be matrices or matrix-like objects of equal dimension to data. They will be assigned into the environment in the data slot.

Slots

data:: An environment which contains at least one element named "iData", which is a matrix-like object with rows equal to the number of features and columns equal to the number of non-missing pixels. Each column is a feature vector.
coord:: An data.frame with rows giving the spatial coordinates of the pixels corresponding to the columns of "iData".
positionArray:: An array with dimensions equal to the spatial dimensions of the image, which stores the column numbers of the feature vectors corresponding to the pixels in the "iData" element of the data slot. This allows re-construction of the imaging "datacube" on-the-fly.
dim:: A length 2 integer vector analogous to the 'dim' attribute of an ordinary R matrix.
dimnames:: A length 2 list analogous to the 'dimnames' attribute of an ordinary R matrix.
storageMode:: A character which is one of "immutableEnvironment", "lockedEnvironment", or "environment". The values "lockedEnvironment" and "environment" behave as described in the documentation of AssayData. An "immutableEnvironment" uses a locked environment while retaining R's typical copy-on-write behavior. Whenever an object in an immutable environment is modified, a new environment is created for the data slot, and all objects copied into it. This allows usual R functional semantics while avoiding copying of large objects when other slots are modified.
.__classVersion__:: A Versions object describing the version of the class used to created the instance. Intended for developer use.

Extends

Versioned

Creating Objects

SImageData instances are usually created through SImageData().

Methods

Class-specific methods:

iData(object), iData(object)<-:: Return or set the matrix of image intensities. Columns should correspond to feature vectors, and rows should correspond to pixel vectors.
coord(object), coord(object)<-:: Return or set the coodinates. This is a data.frame with each row corresponding to the spatial coordinates of a pixel.
positionArray(object), positionArray(object)<-:: Return or set the positionArray slot. When setting, this should be an array returned by a call to generatePositionArray.
featureNames(object), featureNames(object) <- value:: Access and set feature names (names of the rows of the intensity matrix).
pixelNames(object), pixelNames(object) <- value:: Access and set the pixel names (names of the columns of the intensity matrix).
storageMode(object), storageMode(object)<-:: Return or set the storage mode. See documentation on the storageMode slot above for more details.

Standard generic methods:

combine(x, y, ...):: Combine two or more SImageData objects. Elements must be matrix-like objects and are combined column-wise with a call to 'cbind'. The numbers of rows must match, but otherwise no checking of row or column names is performed. The pixel coordinates are checked for uniqueness.
dim:: Return the dimensions of the (virtual) datacube. This is equal to the number of features (the number of rows in the matrix returned by iData) and the dimensions of the positionArray slot. For a standard imaging dataset, that is the number features followed by the spatial dimensions of the image.
dims:: A matrix where each column corresponds to the dimensions of the (virtual) datacubes stored as elements in the data slot. See above for how the dimensions are calculated.
SImageData[i, j, ..., drop]:: Access intensities in the (virtual) imaging datacube. The datacube is reconstructed on-the-fly. The object can be indexed like any ordinary array with number of dimensions equal to dim(object). Use drop = NA to return a subset of the same class as the object.

Examples

Run this code

## Create an SImageData object
SImageData()

## Using a P x N matrix
data1 <- matrix(1:27, nrow=3)
coord <- expand.grid(x=1:3, y=1:3)
sdata1 <- SImageData(data1, coord)
sdata1[] # extract data as array

## Using a P x X x Y array
data2 <- array(1:27, dim=c(3,3,3))
sdata2 <- SImageData(data2)
sdata2[] # should be identical to above

# Missing data from some pixels
data3 <- matrix(1:9, nrow=3)
sdata3 <- SImageData(data3, coord[c(1,5,9),])

dim(sdata3) # presents as an array
iData(sdata3) # stored as matrix
sdata3[] # recontruct the datacube

iData(sdata3)[,1] <- 101:103 # assign using iData()
sdata3[] # can only assign into matrix representation

## Sparse feature vectors
data4 <- Hashmat(nrow=9, ncol=9)
sdata4 <- SImageData(data4, coord)
iData(sdata4)[] <- diag(9)
sdata4[1,,]

Run the code above in your browser using DataLab