image-methods {Cardinal} | R Documentation

## Plot an image of the pixel data of an imaging dataset

### Description

Create and display images for the pixel data of an imaging dataset using a formula interface.

### Usage

    ## S4 method for signature 'formula'
    image(x, data = environment(x), ...,
        xlab, ylab, zlab, subset)

    #### Methods for Cardinal >= 2.x classes ####

    ## S4 method for signature 'PositionDataFrame'
    image(x, formula,
            groups = NULL,
            superpose = FALSE,
            strip = TRUE,
            key = superpose || !is.null(groups),
            normalize.image = c("none", "linear"),
            contrast.enhance = c("none", "suppression", "histogram"),
            smooth.image = c("none", "gaussian", "adaptive"),
            ...,
            xlab, xlim,
            ylab, ylim,
            zlab, zlim,
            asp = 1,
            layout,
            col = discrete.colors,
            colorscale = viridis,
            colorkey = !key,
            alpha.power = 1,
            subset = TRUE,
            add = FALSE)

    ## S4 method for signature 'SparseImagingExperiment'
    image(x, formula,
            feature,
            feature.groups,
            groups = NULL,
            superpose = FALSE,
            strip = TRUE,
            key = superpose || !is.null(groups),
            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,
            asp = 1,
            layout,
            col = discrete.colors,
            colorscale = viridis,
            colorkey = !key,
            alpha.power = 1,
            subset = TRUE,
            add = FALSE)

    ## S4 method for signature 'SparseImagingExperiment'
    image3D(x, formula, ..., alpha.power = 2)

    ## S4 method for signature 'MSImagingExperiment'
    image(x, formula,
            feature = features(x, mz=mz),
            feature.groups,
            mz,
            plusminus,
            ...)

    ## S4 method for signature 'SparseImagingResult'
    image(x, formula,
            model = modelData(x),
            superpose = is_matrix,
            ...,
            column,
            colorscale = cividis,
            colorkey = !superpose,
            alpha.power = 2)

    ## S4 method for signature 'PCA2'
    image(x, formula,
        values = "scores", ...)

    ## S4 method for signature 'PLS2'
    image(x, formula,
        values = c("fitted", "scores"), ...)

    ## S4 method for signature 'SpatialFastmap2'
    image(x, formula,
        values = "scores", ...)

    ## S4 method for signature 'SpatialKMeans2'
    image(x, formula,
        values = "cluster", ...)

    ## S4 method for signature 'SpatialShrunkenCentroids2'
    image(x, formula,
        values = c("probability", "class", "scores"), ...)

    ## S4 method for signature 'SpatialDGMM'
    image(x, formula,
        values = c("probability", "class", "mean"), ...)

    ## S4 method for signature 'MeansTest'
    image(x, formula,
        values = "mean", jitter = TRUE, ...)

    ## S4 method for signature 'SegmentationTest'
    image(x, formula,
        values = c("mean", "mapping"), jitter = TRUE, ...)

    ## S4 method for signature 'AnnotatedImage'
    image(x, frame = 1, offset = coord(x),
            height, width,
            layout = !add,
            native = TRUE,
            interpolate = TRUE,
            add = FALSE, ...)

    ## S4 method for signature 'AnnotatedImageList'
    image(x, i, frame = 1,
            strip = TRUE,
            layout = !add,
            native = TRUE,
            interpolate = TRUE,
            add = FALSE, ...)

    ## S4 method for signature 'AnnotatedImagingExperiment'
    image(x, i, frame = 1, ...)

    #### Methods for Cardinal 1.x classes ####

    ## S4 method for signature 'SImageSet'
    image(x, formula = ~ x * y,
        feature,
        feature.groups,
        groups = NULL,
        superpose = FALSE,
        strip = TRUE,
        key = superpose,
        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(groups)),
        col.regions = intensity.colors(100),
        colorkey = !is3d,
        subset = TRUE,
        lattice = FALSE)

    ## S4 method for signature 'SImageSet'
    image3D(x, formula = ~ x * y * z, ...)

    ## S4 method for signature 'MSImageSet'
    image(x, formula = ~ x * y,
        feature = features(x, mz=mz),
        feature.groups,
        mz,
        plusminus,
        ...)

    ## S4 method for signature 'ResultSet'
    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)

    ## S4 method for signature 'CrossValidated'
    image(x, fold = 1:length(x), layout, ...)

    ## S4 method for signature 'PCA'
    image(x, formula = substitute(mode ~ x * y),
        mode = "scores",
        ...)

    ## S4 method for signature 'PLS'
    image(x, formula = substitute(mode ~ x * y),
        mode = c("fitted", "scores", "y"),
        ...)

    ## S4 method for signature 'OPLS'
    image(x, formula = substitute(mode ~ x * y),
        mode = c("fitted", "scores", "Oscores", "y"),
        ...)

    ## S4 method for signature 'SpatialFastmap'
    image(x, formula = substitute(mode ~ x * y),
        mode = "scores",
        ...)

    ## S4 method for signature 'SpatialShrunkenCentroids'
    image(x, formula = substitute(mode ~ x * y),
        mode = c("probabilities", "classes", "scores"),
        ...)

    ## S4 method for signature 'SpatialKMeans'
    image(x, formula = substitute(mode ~ x * y),
        mode = "cluster",
        ...)

### 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.
`data` | A `list` or `data.frame`-like object from which variables in `formula` should be taken.
`mz` | The m/z value(s) for which to plot the ion image(s).
`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.
`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.
`colorscale` | The color scale to use for the z-axis of image intensities. This may be either a vector of colors or a function which takes a single numeric argument `n` and generates a vector of colors of length `n`.
`col.regions` | The default plotting color(s) for the z-axis of image intensities. Thus must be a vector of colors.
`colorkey` | Should a coloykey describing the z-axis be drawn with the plot?
`alpha.power` | Opacity scaling factor (1 is linear).
`jitter` | Should a small amount of noise be added to the image values before plotting them?
`subset` | An expression that evaluates to a logical or integer indexing vector to be evaluated in `pData(x)`.
`...` | Additional arguments passed to the underlying `plot` functions.
`i` | Which data element should be plotted.
`frame` | Which frame of an image should be plotted.
`offset` | Absolute offset in x/y coordinates of the top-left corner of the image (from the origin).
`height` | The height of the plotted image.
`width` | The width of the plotted image.
`native` | Should a native raster (using integer color codes) be produced, or an rgb raster (using character color codes)?
`interpolate` | Should any linear interpolation be done when plotting the image?
`fold` | What folds of the cross-validation should be plotted.
`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)`.
`mode` | What kind of results should be plotted. This is the name of the object to plot in the `ResultSet` object.
`values` | What kind of results should be plotted. This is the name of the object to plot in the `ImagingResult` object. Renamed from `mode` to avoid ambiguity.
`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.
`lattice` | Should lattice graphics be used to create the plot?
`add` | Should the method call `plot.new()` or be added to the current plot?

### Note

In most cases, calling `image3D(obj)` is equivalent to `image(obj, ~ x * y * z)`.

### Author(s)

Kylie A. Bemis

### See Also

`plot`, `selectROI`

### Examples

    setCardinalBPPARAM(SerialParam())

    set.seed(1)
    x <- simulateImage(preset=2, npeaks=10, dim=c(10,10))
    m <- mz(metadata(x)$design$featureData)

    image(x, mz=m[1], plusminus=0.5)
    image(x, mz=m[1], smooth.image="gaussian", contrast.enhance="histogram")
    image(x, mz=m[1], colorscale=col.map("grayscale"))
    image(x, mz=m[4:7], colorscale=col.map("cividis"))
    image(x, mz=m[c(1,8)], normalize.image="linear", superpose=TRUE)

    sm <- summarizePixels(x, FUN=c(tic="sum"), as="DataFrame")
    pData(x)$tic <- sm$tic

    image(x, tic ~ x * y, colorscale=magma)

[Package Cardinal version 2.8.0 Index]