SImageData-class {Cardinal} | R Documentation

## SImageData: 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 = NULL` to return a subset of the same class as the object.

### Author(s)

Kylie A. Bemis

### See Also

`ImageData`, `MSImageData`, `SImageSet`, `MSImageSet`

### Examples

    ## 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,,]

[Package Cardinal version 2.4.0 Index]