IAnnotatedDataFrame-class {Cardinal} | R Documentation

## IAnnotatedDataFrame: Class containing measured variables and their metadata for imaging experiments

### Description

An `IAnnotatedDataFrame` is an extension of an `AnnotatedDataFrame` as defined in the 'Biobase' package modified to reflect that individual rows in `data` represent pixels rather than samples, and many pixels will come from a single sample. Additionally, it keeps track of the coordinates of the pixel represented by each row.

### Usage

    ## Instance creation
    IAnnotatedDataFrame(data, varMetadata,
    	dimLabels=c("pixelNames", "pixelColumns"),
    	...)

    ## Additional methods documented below

### Arguments

`data` | A `data.frame` of the pixels (rows) and measured variables (columns). Omitting this will yield an empty `IAnnotatedDataFrame` with zero rows.
`varMetadata` | A `data.frame` with columns describing the measured variables in `data`. Generated automatically if missing.
`dimLabels` | Aesthetic labels for the rows and columns in the `show` method.
`...` | Additional arguments passed to the `initialize` method.

### Details

The key difference between a `IAnnotatedDataFrame` and a `AnnotatedDataFrame` is that an `IAnnotatedDataFrame` makes a distinction between samples and pixels, recognizing that rows belong to pixels, many of which may belong to the same sample. Therefore, `data` contains a required column called 'sample', which indicates the sample to which the pixel belongs, and `varMetadata` contains an additional required column called 'labelType', which indicates whether a variable is a spatial dimensions ('dim') or a phenotype ('pheno') or a sample ('sample'). The 'labelType' of the 'sample' variable depends on the structure of the experiment. See below for details.

The 'labelType' for 'sample' will be 'sample' in the case of a 2D imaging experiment with a single sample. The 'labelType' for 'sample' will be 'dim' in the case of a 2D imaging experiment with multiple samples, since the 'sample' will be acting as a proxy spatial coordinate. Note however that in this case, the result of a call to `coordLabels` will not include 'sample'.

It is possible to compare the results of `names(coord(object))` and `coordLabels(object)` to distinguish between coordinate types that should be considered independent. It will be assumed a spatial relationship exists for all variables returned by `coordLabels(object)`, but this is not necessarily true for all variables returned by `names(coord(object))`. This is required, because every row in the `data.frame` returned by `coord(object)` should be unique and correspond to a unique pixel.

The suggested structure for 3D imaging experiments is to create an additional variable solely to refer to the spatial dimension (e.g., 'z') and treat it separately from the 'sample'. Therefore, in a 3D imaging experiment with a single sample, the 'labelType' for 'sample' would be 'sample'.

### Slots

`data`:

  Object of class `data.frame` containing pixels (rows) and measured variables (columns). Contains at least one column named 'sample' which is a `factor` and gives the sample names for each pixel. The sample names can be set using `sampleNames<-`. Inherited from AnnotatedDataFrame.

`varMetadata`:

  Object of class `data.frame` with number of rows equal to the number of columns in `data`. Contains at least two columns, one named 'labelDescription' giving a textual description of each variable, and an additional one named 'labelType' describing the type of variable. The 'labelType' is a factor with levels `"dim", "sample", "pheno"`. Inherited from AnnotatedDataFrame

`dimLabels`:

  Object of class `character` of length 2 that provides labels for the rows and columns in the `show` method. Inherited from AnnotatedDataFrame.

`.__classVersion__`:

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

### Extends

Class `AnnotatedDataFrame`, directly. Class `Versioned`, by class "AnnotatedDataFrame", distance 2.

### Creating Objects

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

### Methods

Class-specific methods:

`sampleNames(object)`, `sampleNames(object)<-`:

  Return or set the sample names in the object, as determined by the factor levels of the 'sample' variable in `data`.

`pixelNames(object)`, `pixelNames(object)<-`:

  Return or set the pixel names (the rows of `data`).

`coordLabels(object)`, `coordLabels(object)<-`:

  Return or set the names of the pixel coodinates. These are the subset of `varLabels(object) for which the corresponding variables have a 'labelType' of 'dim'.` Note that this will never include 'sample', even if the 'sample' variable has type 'dim'. (See details.)

`coord(object)`, `coord(object)<-`:

  Return or set the coodinates. This is a `data.frame` containing the subset of columns of `data` for which the variables have a 'labelType' of 'dim'.

Standard generic methods:

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

  Combine two or more `IAnnotatedDataFrame` objects. The objects are combined similarly to 'rbind' for `data.frame` objects. Pixels coordinates are checked for uniqueness. The 'varLabels' and 'varMetadata' must match.

### Author(s)

Kylie A. Bemis

### See Also

`AnnotatedDataFrame`, `iSet`, `SImageSet` `MSImageSet`

### Examples

    ## Create an IAnnotatedDataFrame object
    IAnnotatedDataFrame()

    ## Simple IAnnotatedDataFrame
    df1 <- IAnnotatedDataFrame(data=expand.grid(x=1:3, y=1:3),
    	varMetadata=data.frame(labelType=c("dim", "dim")))
    pData(df1)
    varMetadata(df1)

    # Example of possible experiment data
    coord <- expand.grid(x=1:3, y=1:3)
    df2 <- IAnnotatedDataFrame(data=
    	data.frame(rbind(coord, coord), sample=factor(rep(1:2, each=nrow(coord)))),
    	varMetadata=data.frame(labelType=c("dim", "dim")))
    df2$diagnosis <- factor(rbinom(nrow(df2), 1, 0.5), labels=c("normal", "cancer"))
    varMetadata(df2)["diagnosis", "labelDescription"] <- "disease pathology"
    df2[["time", labelDescription="time measured"]] <- rep(date(), nrow(df2))
    pData(df2)
    varMetadata(df2)

    # Change labels and pixel coord
    coordLabels(df2) <- c("x1", "x2")
    pixelNames(df2) <- paste("p", 1:nrow(df2), sep="")
    sampleNames(df2) <- c("subject A", "subject B")
    coord(df2) <- coord(df2)[nrow(df2):1,]
    pData(df2)

[Package Cardinal version 2.4.0 Index]