Cardinal (version 1.4.0)

image-methods: Plot the Pixel-Space of an Imaging Dataset

Description

Create and display plots in the pixel space of an imaging dataset. This uses a formula interface inspired by the lattice graphics package.

Usage

"image"(x, formula = ~ x * y, feature, feature.groups, groups = NULL, superpose = FALSE, strip = TRUE, key = FALSE, fun = mean, normalize.image = c("none", "linear"), contrast.enhance = c("none", "suppression", "histogram"), smooth.image = c("none", "gaussian", "adaptive"), ..., xlab, xlim, ylab, ylim, zlab, zlim, layout, asp = 1, col = rainbow(nlevels(feature.groups)), col.regions = intensity.colors(100), colorkey = !is3d, subset = TRUE, lattice = FALSE)
"image"(x, formula = ~ x * y, feature = features(x, mz=mz), feature.groups, mz, plusminus, ...)
"image"(x, formula, model = pData(modelData(x)), feature, feature.groups, superpose = TRUE, strip = TRUE, key = superpose, ..., column, col = if (superpose) rainbow(nlevels(feature.groups)) else "black", lattice = FALSE)
"image"(x, fold = 1:length(x), layout, ...)
"image"(x, formula = substitute(mode ~ x * y), mode = "scores", ...)
"image"(x, formula = substitute(mode ~ x * y), mode = c("fitted", "scores", "y"), ...)
"image"(x, formula = substitute(mode ~ x * y), mode = c("fitted", "scores", "Oscores", "y"), ...)
"image"(x, formula = substitute(mode ~ x * y), mode = c("probabilities", "classes", "scores"), ...)
"image"(x, formula = substitute(mode ~ x * y), mode = "cluster", ...)
"image3D"(x, formula = ~ x * y * z, ...)

Arguments

x

An imaging dataset.

formula

A formula of the form 'z ~ x * y | g1 * g2 * ...' (or equivalently, 'z ~ x + y | g1 + g2 + ...'), indicating a LHS 'y' (on the y-axis) versus a RHS 'x' (on the x-axis) and conditioning variables 'g1, g2, ...'.

Usually, the LHS is not supplied, and the formula is of the form '~ x * y | g1 * g2 * ...', and the y-axis is implicityl assumed to be the feature vectors corresponding to each pixel in the imaging dataset specified by the object 'x'. However, a variable evaluating to a vector of pixel values, or a sequence of such variables, can also be supplied.

The RHS is evaluated in pData(x) and should provide values for the xy-axes. These must be spatial coordinates.

The conditioning variables are evaluated in fData(x). These can be specified in the formula as 'g1 * g2 * ...'. The argument 'feature.groups' allows an alternate way to specify a single conditioning variable. Conditioning variables specified using the formula interface will always appear on separate plots. This can be combined with 'superpose = TRUE' to both overlay plots based on a conditioning variable and use conditioning variables to create separate plots.

model

A vector or list specifying which fitted model to plot. If this is a vector, it should give a subset of the rows of modelData(x) to use for plotting. Otherwise, it should be a list giving the values of parameters in modelData(x).

feature

The feature or vector of features for which to plot the image. This is an expression that evaluates to a logical or integer indexing vector.

feature.groups

An alternative way to express a single conditioning variable. This is a variable or expression to be evaluated in fData(x), expected to act as a grouping variable for the features specified by 'feature', typically used to distinguish different groups or ranges of features. Pixel vectors of images from features in the same feature group will have 'fun' applied over them; 'fun' will be applied to each feature group separately, usually for averaging. If 'superpose = FALSE' then these appear on separate plots.

groups

A variable or expression to be evaluated in pData(x), expected to act as a grouping variable for the pixel regions in the image(s) to be plotted, typically used to distinguish different image regions by varying graphical parameters like color and line type. By default, if 'superpose = FALSE', these appear overlaid on the same plot.

superpose

Should feature vectors from different feature groups specified by 'feature.groups' be superposed on the same plot? If 'TRUE' then the 'groups' argument is ignored.

strip

Should strip labels indicating the plotting group be plotting along with the each panel? Passed to 'strip' in levelplot is 'lattice = TRUE'.

key

A logical, or list containing components to be used as a key for the plot. This is passed to 'key' in levelplot if 'lattice = TRUE'.

fun

A function to apply over pixel vectors of images grouped together by 'feature.groups'. By default, this is used for averaging over features.

normalize.image

Normalization function to be applied to each image. The function can be user-supplied, of one of 'none' or 'linear'. The 'linear' normalization method normalized each image to the same intensity range using a linear transformation.

contrast.enhance

Contrast enhancement function to be applied to each image. The function can be user-supplied, or one of 'none', 'histogram', or 'suppression'. The 'histogram' equalization method flatterns the distribution of intensities. The hotspot 'suppression' method uses thresholding to reduce the intensities of hotspots.

smooth.image

Image smoothing function to be applied to each image. The function can be user-supplied, or one of 'none', 'gaussian', or 'adaptive'. The 'gaussian' smoothing method smooths images with a simple gaussian kernel. The 'adaptive' method uses bilateral filtering to preserve edges.

xlab

Character or expression giving the label for the x-axis.

ylab

Character or expression giving the label for the y-axis.

zlab

Character or expression giving the label for the z-axis. (Only used for plotting 3D images.)

xlim

A numeric vector of length 2 giving the left and right limits for the x-axis.

ylim

A numeric vector of length 2 giving the top and bottom limits for the y-axis.

zlim

A numeric vector of length 2 giving the lower and upper limits for the z-axis (i.e., the range of colors to be plotted).

layout

The layout of the plots, given by a length 2 numeric as c(ncol, nrow). This is passed to levelplot if 'lattice = TRUE'. For base graphics, this defaults to one plot per page.

asp

The aspect ratio of the plot.

col

A specification for the default plotting color(s) for groups.

col.regions

The default plotting color(s) for the z-axis of image intensities.

colorkey

Should a coloykey describing the z-axis be drawn with the plot?

subset

An expression that evaluates to a logical or integer indexing vector to be evaluated in pData(x).

lattice

Should lattice graphics be used to create the plot?

...

additional arguments passed to the underlying plot functions.

mz

The m/z value for which to plot the ion image.

plusminus

If specified, a window of m/z values surrounding the one given by coord will be included in the plot with fun applied over them, and this indicates the range of the window on either side.

fold

What folds of the cross-validation should be plotted.

mode

What kind of results should be plotted. This is the name of the object to plot in the ResultSet object.

column

What columns of the results should be plotted. If the results are a matrix, this corresponds to the columns to be plotted, which can be indicated either by numeric index or by name.

See Also

plot-methods, select-methods

Examples

data <- matrix(c(NA, NA, 1, 1, NA, NA, NA, NA, NA, NA, 1, 1, NA, NA, 
 NA, NA, NA, NA, NA, 0, 1, 1, NA, NA, NA, NA, NA, 1, 0, 0, 1, 
 1, NA, NA, NA, NA, NA, 0, 1, 1, 1, 1, NA, NA, NA, NA, 0, 1, 1, 
 1, 1, 1, NA, NA, NA, NA, 1, 1, 1, 1, 1, 1, 1, NA, NA, NA, 1, 
 1, NA, NA, NA, NA, NA, NA, 1, 1, NA, NA, NA, NA, NA), nrow=9, ncol=9)

mycol <- gradient.colors(100, "red", "black")

set.seed(1)
sset <- generateImage(data, range=c(1000,5000), centers=c(3000,4000), resolution=100)

pData(sset)$pg <- factor(data[is.finite(data)], labels=c("black", "red"))
fData(sset)$fg <- factor(rep("bg", nrow(fData(sset))), levels=c("bg", "black", "red"))
fData(sset)$fg[2950 < fData(sset)$t & fData(sset)$t < 3050] <- "black"
fData(sset)$fg[3950 < fData(sset)$t & fData(sset)$t < 4050] <- "red"

image(sset, feature=1, col=mycol)

image(sset, feature=fData(sset)$fg=="black", col=mycol)

image(sset, feature=fData(sset)$fg=="red", col=mycol)

image(sset, ~ x * y | fg, feature=1:nrow(sset), lattice=TRUE, col=mycol)

image(sset, feature=1:nrow(sset), feature.groups=fg, lattice=TRUE, col=mycol)

set.seed(1)
msset <- generateImage(data, range=c(1000,5000), centers=c(3000,4000), resolution=100, as="MSImageSet")

image(msset, mz=3000, col=mycol)

image(msset, mz=4000, col=mycol)

image(msset, mz=3500, plusminus=500, col=mycol)