pkern_plot: Plot grid data

In deankoch/pkern: Fast Kriging with Product Kernels

Plot grid data

Description

Plots a matrix or raster as a heatmap with an optional color bar legend. This is a wrapper for graphics::image similar to terra::plot but with tighter margins to increase the image area on screen; and with a different layout for heat-maps of matrices, which are plotted with i and j axes (row and column numbers) replacing y and x.

Usage

pkern_plot(g, gdim = NULL, ...)

Arguments

g	vector or any object understood by pkern_grid
gdim	numeric vector, (optional) grid dimensions of the data
...	plotting parameters (see details)

Details

g can be a vector, in which case gdim supplies the y, x dimensions (ie number of rows, number of columns), in that order. g can also can be a matrix, raster or any other object understood by pkern_grid (in which case gdim can be omitted).

The data in g can be of numeric, integer, logical, or factor class. The numeric class is plotted with a continuous color bar legend, while the others get a categorical legend.

Category names (ie tick labels) for the legend can be supplied in argument breaks, with one character string for each unique non-NA value in g, as integer, in ascending order. If the data are continuous, breaks can either be the desired number of bins for coloring, or a vector of break points delineating bins (passed to graphics::image). Note that a set of n bins has n+1 break points.

pal should be one of the palette names returned by graphics::hcl.pals, or else a vector of color names with length one fewer than the number of break points.

If the data are all NA, the function omits the heatmap and legend, and draws grid lines instead. col_grid can be specified to enable/disable grid lines more generally. These lines can sometimes appear misaligned due to anti-aliasing. If this is a problem, try switching to a different graphics device back-end (eg. in Windows Rstudio, try changing from the default to Cairo with options(RStudioGD.backend = 'cairo')).

The function sets the graphical parameters 'oma' (to c(0,0,0,0)) and 'mar' (to values between 1.1 and 5.1, depending on whether titles, axes, and legend are plotted), then calls graphics::image, which sets other graphical parameters such as 'usr'. By default all graphical parameters are reset to their original values at the end of the function call. reset=FALSE prevents this, so that additional elements can be added to the plot later (such as by calling sf::st_plot(.., add=TRUE) or graphics:lines).

Value

The function returns a vector of suggested plot height and width values in units of inches wich minimize the unused margin space. For example to save a trim version of your plot as png, call pkern_plot first to get the suggested height and width, say y and x, then pass the result to png(filename, height=m*y, width=m*x, pointsize=m*12, ...), where m is any positive scaling factor.

Plotting parameters

The following style parameters are optional:

adj, leg_just

numeric in 0,1: respectively, the horizontal justification of the title and vertical justification of the color bar legend (default 0.5 for both)

asp

numeric or NA: the aspect ratio parameter passed to graphics::image (default 1)

axes, leg

logical: respectively indicates to draw axes (y and x, or i and j), the color bar legend (default TRUE)

breaks

numeric (vector) or character vector: the color break points (see details)

col_box, col_grid

character: respectively, the colors to use for drawing a box around the image border and for drawing grid cell boundaries (NA to omit)

col_invert, col_rev

logical: respectively, inverts (default FALSE), and reverses the color scale (default TRUE

ij

logical: enables/disables matrix style plot with j axis annotations on top (default TRUE for vector and matrix input, otherwise FALSE)

layer

integer: the layer (column) to plot (default 1)

lwd_axis, lwd_ticks

numeric: respectively, line widths for the axis lines and ticks (0 to omit, default 1)

main, zlab, ylab, xlab

character: respectively, a title to put on top in bold, a legend title to put over the color bar, and axis titles for dimensions y and x. Setting to ” omits both the label and its margin space

minimal

logical: removes all annotation (except as otherwise specified by axes and/or leg)

pal

character (vector): one of graphics::hcl.pals (default 'Spectral') or a vector of colors

reset

logical: indicates to restore original graphical parameters after plot is finished (default TRUE)

zlim

numeric vector: range in the data to plot (ignored for discrete plots)

x_ontop

logical: toggles the placement of the horizontal dimension axis on top vs bottom

Examples

# example grid
gdim = c(50, 100)
n = prod(gdim)
g = pkern_grid(gdim)

# plot the grid layout as raster then as matrix
pkern_plot(g)
pkern_plot(g, ij=TRUE)

# example data: cosine of squared distance to top left corner
z = apply(expand.grid(g$gyx), 1, \(z) cos( 2*sum(z^2) ) )
g_example = modifyList(g, list(gval=z))
pkern_plot(g_example)

# plot as matrix (changes default palette)
pkern_plot(g_example, ij=T)

# alignment
pkern_plot(g_example, ij=T, main='Centered title and legend by default')
pkern_plot(g_example, ij=T, main='adj: left-right justification of title', adj=0)
pkern_plot(g_example, ij=T, main='leg_just: top-bottom justification of color bar', leg_just=0)

# set the palette - see hcl.pals() for valid names
pal = 'Zissou 1'
pkern_plot(g_example, pal=pal, main=pal)
pkern_plot(g_example, pal=pal, main=pal, col_invert=TRUE)
pkern_plot(g_example, pal=pal, main=pal, col_invert=TRUE, col_rev=TRUE)

# example data: cosine of distance to top left corner
z = apply(expand.grid(g$gyx), 1, \(z) cos( sqrt(sum(z^2))/50 ) )
g_example = modifyList(g, list(gval=z))
pkern_plot(g_example)

# specify the layer for multi-layer objects (default is first layer)
g_example = modifyList(g, list(gval=cbind(z, z^2), idx_grid=seq(n)))
pkern_plot(g_example)
pkern_plot(g_example, layer=2)

# reduce number of color breaks or specify a factor for discrete value plots
pkern_plot(g_example, breaks=50)
pkern_plot(g_example, breaks=3) # not a great way to bin the data
pkern_plot(g=modifyList(g, list(gval=cut(z, 3, dig.lab=1))))

# pass color bar labels for discrete plots in breaks (in order low to high)
pkern_plot(modifyList(g, list(gval=cut(z, 3))), breaks=c('a', 'b', 'c'), zlab='group')

# select some "observed" points and make a covariance matrix
idx_obs = match(seq(n), sort(sample.int(prod(gdim), 1e2)))
g_v_example = modifyList(g_example, list(gval=idx_obs))
v = pkern_var(g_v_example)

# matrix display mode is automatic when first argument is a matrix or vector
pkern_plot(v, zlab=expression(V[ij]))

# minimal versions
pkern_plot(v, minimal=T)
pkern_plot(v, minimal=T, leg=T)
pkern_plot(v, minimal=T, col_grid='white', leg=TRUE)

# logical matrix plots are grayscale by default
pkern_plot(v > 1e-2, main='logical matrix')

# logical, integer and factor class matrices get a discrete color-bar
interval = 1e-2 # try also 1e-3 to see behaviour with large number of bins
v_discrete = cut(v, seq(0, ceiling(max(v)), by=interval), dig.lab=2)
pkern_plot(as.character(v_discrete), dim(v))

# labels are preserved for character matrices
z_char = rep(c('foo', 'bar'), n/2)
z_char[sample.int(n, n/2)] = NA
pkern_plot(g=z_char, gdim)

deankoch/pkern documentation built on Oct. 26, 2023, 8:54 p.m.