SImageSet-class {Cardinal} | R Documentation

## Class to Contain Pixel-Sparse Imaging Data

### Description

An `iSet` derived class for pixel-sparse imaging data. Data is stored to be memory efficient when there are missing pixels or when the the stored images are non-rectangular regions. The data structures remain efficient for non-sparse pixel data as long as the full datacube does not need to be reconstructed often, and single images or feature vectors are of primary interest. This class can be combined with `Hashmat` to be sparse in both feature space and pixel space. This is useful for datasets with sparse signals, such as processed spectra.

`MSImageSet` is a derived class of `SImageSet` for storing mass spectrometry imaging experiments.

### Usage

    ## Instance creation
    SImageSet(
        data = Hashmat(nrow=0, ncol=0),
        coord = expand.grid(
            x = seq_len(prod(dim(data)[-1])),
            y = seq_len(ifelse(prod(dim(data)[-1]) > 0, 1, 0))),
        imageData = SImageData(
            data=data,
            coord=coord),
        pixelData = IAnnotatedDataFrame(
            data=coord,
            varMetadata=data.frame(labelType=rep("dim", ncol(coord)))),
        featureData = AnnotatedDataFrame(
            data=data.frame(row.names=seq_len(nrow(data)))),
        protocolData = AnnotatedDataFrame(
            data=data.frame(row.names=sampleNames(pixelData))),
        experimentData = new("MIAPE-Imaging"),
        ...)

    ## 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.
`imageData` | An object of class `SImageData` that will contain the imaging data. Usually constructed using `data` and `coord`.
`pixelData` | An object of class `IAnnotatedDataFrame` giving the information about the pixels including coordinates of the data in `imageData`.
`featureData` | An object of class `AnnotatedDataFrame` giving information about the data features.
`protocolData` | An object of class `AnnotatedDataFrame` giving information about the samples. It must have one row for each of the `sampleNames` in `pixelData`.
`experimentData` | An object derived from class `MIAxE` giving information about the imaging experiment.
`...` | Additional arguments passed to the initializer.

### Slots

`imageData`:

  An instance of `SImageData`, which stores one or more matrices of equal number of dimensions as elements in an 'immutableEnvironment'. This slot preserves copy-on-write behavior when it is modified specifically, but is pass-by-reference otherwise, for memory efficiency.

`pixelData`:

  Contains pixel information in an `IAnnotatedDataFrame`. This includes both pixel coordinates and phenotypic and sample data. Its rows correspond to the columns in `imageData`.

`featureData`:

  Contains variables describing features in an `IAnnotatedDataFrame`. Its rows correspond to the rows in `imageData`.

`experimentData`:

  Contains details of experimental methods. Should be an object of a derived class of `MIAxE`.

`protocolData`:

  Contains variables in an `IAnnotatedDataFrame` describing the generation of the samples in `pixelData`.

`.__classVersion__`:

  A `Versions` object describing the version of the class used to created the instance. Intended for developer use.

### Extends

`iSet`, directly. `VersionedBiobase`, by class "iSet", distance 1. `Versioned`, by class "VersionedBiobase", distance 2.

### Creating Objects

`SImageSet` instances are usually created through `SImageSet()`.

### Methods

Class-specific methods:

`iData(object), iData(object) <- value`:

  Access and set the sparse image data in `imageData`. This is a matrix-like object with rows corresponding to features and columns corresponding to pixels, so that each column of the returned object is a feature vector.

`regeneratePositions`:

  Regenerates the `positionArray` in `imageData` used to reconstruct the datacube based on the coordinates in `pixelData`. Normally, this should not be called by the user. However, if the coordinates are modified manually, it can be used to re-sync the data structures.

Standard generic methods:

`combine(x, y, ...)`:

  Combine two or more `SImageSet` objects. Unique 'sample's in `pixelData` are treated as a dimension.

`SImageSet[i, j, ..., drop]`:

  Subset an `SImageSet` based on the rows (featureData components) and the columns (pixelData components). The result is a new `SImageSet`.

See `iSet` for additional methods.

### Author(s)

Kylie A. Bemis

### See Also

`iSet`, `SImageData`, `MSImageSet`

### Examples

    ## Create an SImageSet object
    data <- matrix(1:27, nrow=3)
    coord <- expand.grid(x=1:3, y=1:3)
    sset <- SImageSet(data=data, coord=coord)

    ## Access a single image corresponding to the first feature
    imageData(sset)[1,,]

    ## Reconstruct the datacube
    imageData(sset)[]

    ## Access the P x N matrix of column-wise feature vectors
    iData(sset)

    ## Subset the SImageSet to the first 2 features and first 6 pixels
    sset2 <- sset[1:2, 1:6]
    imageData(sset2)[]
    sset2

[Package Cardinal version 1.12.1 Index]