Cardinal (version 1.4.0)

IAnnotatedDataFrame-class: Class Containing Measured Variables and Their Meta-Data Description 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.

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.

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

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)