imagep: Plot an image with a color palette

Description

Plot an image with a color palette

Usage

imagep(x, y, z, 
    xlim, ylim, zlim, 
    zclip=FALSE, flipy=FALSE,
    xlab="", ylab="", zlab="", zlabPosition=c("top", "side"),
    decimate=TRUE,
    breaks, col, colormap, labels=NULL, at=NULL,
    drawContours=FALSE,
    drawPalette=TRUE,
    drawTriangles=FALSE,
    tformat,
    drawTimeRange=getOption("oceDrawTimeRange"),
    filledContour=FALSE,
    missingColor=NULL,
    mgp=getOption("oceMgp"),
    mar, mai.palette,
    xaxs="i", yaxs="i",
    cex=par("cex"),
    adorn,
    axes=TRUE,
    main="",
    axisPalette,
    debug=getOption("oceDebug"),
    ...)

Arguments

x,y

optional locations of grid lines along which values of z are measured. The values must be finite and distinct. If they are out of order, they will be ordered (and the z data will be ordered in a matchin

a matrix containing the values to be plotted (NAs are allowed). Note that x can be used instead of z for convenience. (NOTE: these arguments are meant to mimic those of image, which explains t

xlim

limits on x axis.

ylim

limits on y axis.

zlim

either a pair of numbers giving the limits for the colorscale, or "histogram" to have a flattened histogram (i.e. to maximally increase contrast throughout the domain.)

decimate

value indicating whether to decimate the image. If decimate=FALSE, no decimation is done, i.e. all data are shown. If decimate=TRUE, then the image is decimated to display at most 800 pixels in width or h

zclip

logical, indicating whether to clip the colors to those corresponding to zlim. This only works if zlim is provided. Clipped regions will be colored with missingColor. Thus, clipping an image i

flipy

logical, with TRUE indicating that the image should be flipped top to bottom (e.g. to produce a profile image for a downward-looking acoustic-doppler profile).

xlab,ylab,zlab

names for x axis, y axis, and the image values.

zlabPosition

string indicating where to put the label for the z axis, either at the top-right of the main image, or on the side, in the axis for the palette.

breaks

the z values for breaks in the color scheme. If this is of length 1, the value indicates the desired number of breaks, which is supplied to pretty, in determining clean break points.

col

either a vector of colors corresponding to the breaks, of length 1 plus the number of breaks, or a function specifying colors, e.g. oce.colorsJet for a rainbow.

colormap

a color map as created by colormap. If provided, then colormap$breaks and colormap$col take precedence over the present arguments breaks and co

labels

optional vector of labels for ticks on palette axis (must correspond with at)

optional vector of positions for the labels

drawContours

logical value indicating whether to draw contours on the image, and palette, at the color breaks. Images with a great deal of high-wavenumber variation look poor with contours.

tformat

optional argument passed to oce.plot.ts, for plot types that call that function. (See strptime for the format used.)

drawTimeRange

logical, only used if the x axis is a time. If TRUE, then an indication of the time range of the data (not the axis) is indicated at the top-left margin of the graph. This is useful because the labels on

drawPalette

indication of the type of palette to draw, if any. If drawPalette=TRUE, a palette is drawn at the right-hand side of the main image. If drawPalette=FALSE, no palette is drawn, and the right-hand side of

drawTriangles

logical value indicating whether to draw triangles on the top and bottom of the palette. This is passed to drawPalette.

filledContour

boolean value indicating whether to use filled contours to plot the image.

missingColor

a color to be used to indicate missing data, or NULL to avoid making the indication.

mgp

3-element numerical vector to use for par(mgp), and also for par(mar), computed from this. The default is tighter than the R default, in order to use more space for the data and less for the axes.

mar

value to be used with par("mar"). If not given, a reasonable value is calculated based on whether xlab and ylab are empty strings.

mai.palette

palette margin corrections (in inches), added to the mai value used for the palette. Use with care.

xaxs

character indicating whether image should extend to edge of x axis (with value "i") or not; see par("xaxs").

yaxs

as xaxs but for y axis.

cex

size of labels on axes and palette; see par("cex").

adorn

optional expression to be performed immediately after drawing the data panel.

axes

logical, set TRUE to get axes on the main image.

main

title for plot.

axisPalette

optional replacement function for axis(), passed to drawPalette.

debug

a flag that turns on debugging. Set to 1 to get a moderate amount of debugging information, or to 2 to get more.

...

optional arguments passed to plotting functions.

Value

A list is silently returned, containing xat and yat, values that can be used by oce.grid to add a grid to the plot.

Details

Creates an image with a color palette to the right. The effect is similar to filled.contour except that with imagep it is possible to set the layout outside the function, which enables the creation of plots with many image-palette panels. Note that the contour lines may not coincide with the color transitions, in the case of coarse images.

Note that this does not use layout or any of the other screen splitting methods. It simply manipulates margins, and draws two plots together. This lets users employ their favourite layout schemes.

The palette is drawn before the image, so that further drawing can be done on the image if desired, if the user prefers not to use the adorn argument.

NOTE: imagep is an analogue of image, and so it borrows a somewhat odd convention: the number of rows in the matrix corresponds to the x axis, not the y axis. (Actually, image permits the length of x to match either nrow(z) or 1+nrow(z), but here only the first is permitted.)

Examples

Run this code

library(oce)

    ## 1. simplest use
    imagep(volcano)

    ## 2. something oceanographic (internal-wave speed)
    h <- seq(0, 50, length.out=100)
    drho <- seq(1, 3, length.out=200)
    speed <- outer(h, drho, function(drho, h) sqrt(9.8 * drho * h / 1024))
    imagep(h, drho, speed, xlab="Equivalent depth [m]",
    ylab=expression(paste(Delta*rho, "[kg/m^3]")),
    zlab="Internal-wave speed [m/s]")

    ## 3. fancy labelling on atan() function
    x <- seq(0, 1, 0.01)
    y <- seq(0, 1, 0.01)
    angle <- outer(x,y,function(x,y) atan2(y,x))
    imagep(x, y, angle, filledContour=TRUE, breaks=c(0, pi/4, pi/2),
           col=c("lightgray", "darkgray"),
           at=c(0, pi/4, pi/2),
           labels=c(0, expression(pi/4), expression(pi/2)))

    ## 4. a colormap case
    data(topoWorld)
    cm <- colormap(name="gmt_globe")
    imagep(topoWorld, colormap=cm)