magimage: Magically pretty images

Description

magimage is a level replacement for base image with hooks into magaxis for the tick marks and magmap for the image scaling. The default behavious is a bit different to base (e.g. x/y scales are automatically the number of pixels in the image matrix). magimageRGB is similar, but is for the creation colour images where the user can provide R G B input matrix chanels (or similar).

Usage

magimage(x, y, z, zlim, xlim, ylim, col = grey((0:1000)/1000), add = FALSE,
useRaster = TRUE, asp = 1, magmap=TRUE, lo = 0, hi = 1, flip = FALSE, range = c(0, 1),
type = "quan", stretch = "asinh", stretchscale = 'auto', bad = NA, clip = "", axes = TRUE,
frame.plot = TRUE, ...)
magimageRGB(x, y, R, G, B, zlim, xlim, ylim, add = FALSE, useRaster = TRUE, asp = 1,
magmap = TRUE, lo = 0.2, hi = 0.995, flip = FALSE, range = c(0, 1), type = "quan",
stretch = "asinh", stretchscale = "auto", bad = range[1], clip = "", axes = TRUE,
frame.plot = TRUE, ...)

Arguments

x, y

Locations of grid lines at which the values in z are measured. These must be finite and non-missing (order may be reversed). By default, equally spaced values from 0 to dim(z)[1] are used. If x is a list, its components x$x and x$y are used for x and y, respectively. If the list has component z this is used for z.

A numeric or logical matrix containing the values to be plotted (NAs are allowed). Note that x can be used instead of z for convenience.

A numeric or logical matrix containing the red colour values to be plotted (NAs are allowed). Note that a 3D array x can be used instead of R for convenience, where R=x[,,1].

A numeric or logical matrix containing the green colour values to be plotted (NAs are allowed). Note that a 3D array x can be used instead of G for convenience, where G=x[,,2].

A numeric or logical matrix containing the blue colour values to be plotted (NAs are allowed). Note that a 3D array x can be used instead of B for convenience, where B=x[,,3].

zlim

The z limit with respect to the output of magmap$map. If magmap=FALSE (default) zlim should be with respect to the provided z matrix (like base image). If magmap=TRUE zlim should be with respect to the range output of magmap. By default the magmap function scales between 0 and 1, so to only show the brighter pixels zlim could be set to c(0.5,1).

xlim, ylim

Ranges for the plotted x and y values, defaulting to the ranges of x and y.

col

A list of colours for the magmap re-mapping of z to be parsed into (e.g. rainbow, heat.colors, topo.colors, terrain.colors or similar).

add

If true add the new image to the current plot.

useRaster

If TRUE a bitmap raster is used to plot the image instead of polygons. The grid must be regular in that case, otherwise an error is raised. Raster is much faster, so use when pixels are equal sized.

asp

The y/x aspect ratio

magmap

The low limit to clip the z data at (what this means varies depending on the 'type' option). This should be a single value. See magmap for more information.

The high limit to clip the z data at (what this means varies depending on the 'type' option). This should be a single value. See magmap for more information.

flip

Should the z scaling be flipped. This allows numbers from 0 to 10 to be mapped from 1 to 0 (so ordered back to front with respect to the input). See magmap for more information.

range

The numerical range of the output z mapping which should be a vector of length two specifying c(low,high). See magmap for more information.

type

The type of z mapping attempted. Options are 'quan' (default), 'num', 'sig' and 'rank'. See magmap for more information.

stretch

stretch='lin' gives linear mapping. stretch='log' gives logarithmic mapping. stretch='atan' gives atan mapping. stretch='asinh' gives asinh mapping. stretch='sqrt' gives sqrt mapping. See magmap for more information.

stretchscale

A number to multiply the z data by before applying the stretch. This only has a user impact for stretch='atan' and stretch='asinh' since it controls what parts of the data is in the linear or logarithmic regime of the stretch procedure. If set to 'auto' (the default) it uses 1/median(abs(data)) to find a useful scale.See magmap for more information.

bad

Sets the value that NA, NaN and infinite input z data should be set to in the final map output. This should be thought of in the context of the range argument, i.e. if bad=range[1] then bad values will be the low range value and if bad=range[2] bad values will be the high range value. See magmap for more information. For magimageRGB bad is set to range[1] by default since this removes RGB conversion errors that would be experiences with NA values (i.e. negative values when stretch='log').

clip

By default clipped z values inherit the nearest lo/hi value (depending on which side they are clipped). Setting clip='NA' will set values outside the 'lo' and 'hi' values to be NA (currently this is the only other clip option). See magmap for more information.

axes

Specify if any axes be drawn on the image. If FALSE then only the pixels (with appropriate magmap scaling) are shown.

frame.plot

Specify if a box be drawn around the image frame. Only happens if add=TRUE and axes=TRUE.

...

Arguments to be parsed to magaxis. See magaxis for details.

Value

Outputs the final image list containing x,y and z. Generally run for the side effect of producing nice image plots.

Details

See image, magmap and magaxis for more details.

Examples

Run this code

#Basic
magimage(matrix(1:9,3))

#Mid pixel versus pixel edge:
magimage(3:0,1:3,matrix(1:9,3))

#Standard scaling is not very useful in this instance:
magimage(matrix(10^(1:9),3))
#Linear scaling is not very useful in this instance, though it does now map from [0,1]:
magimage(matrix(10^(1:9),3),magmap=TRUE,zlim=c(0,0.5))
#Log scaling with magmap makes it much clearer:
magimage(matrix(10^(1:9),3),magmap=TRUE,stretch='log')
#And it's easy just to show the lowest half now:
magimage(matrix(10^(1:9),3),magmap=TRUE,stretch='log',zlim=c(0,0.5))

Run the code above in your browser using DataLab