Annotate and customize rasterly figures

Create a static plot based on rasterly object. This function allows users to add axes, legends and other descriptive details when generating `rasterly` objects.

rasterlyGrob(
  rasterlyObj,
  xlim = NULL,
  ylim = NULL,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  sub = NULL,
  interpolate = FALSE,
  axes = TRUE,
  legend = TRUE,
  legend_label = NULL,
  legend_layer = 1,
  legend_main = NULL,
  axes_gpar = grid::gpar(col = "black", cex = 1),
  label_gpar = grid::gpar(col = "black", cex = 1),
  main_gpar = grid::gpar(col = "black", cex = 1.5),
  legend_gpar = grid::gpar(col = "black", cex = 1.5),
  name = NULL,
  gp = NULL,
  vp = NULL
)

grid.rasterly(
  rasterlyObj,
  interpolate = FALSE,
  axes = TRUE,
  xlim = NULL,
  ylim = NULL,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  sub = NULL,
  legend = TRUE,
  legend_label = NULL,
  legend_layer = 1,
  legend_main = NULL,
  axes_gpar = grid::gpar(col = "black", cex = 1),
  label_gpar = grid::gpar(col = "black", cex = 1),
  main_gpar = grid::gpar(col = "black", cex = 1.5),
  legend_gpar = grid::gpar(col = "black", cex = 1.5),
  name = NULL,
  gp = NULL,
  vp = NULL,
  ...
)

# S3 method for rasterly
plot(
  x,
  y = NULL,
  xlim = NULL,
  ylim = NULL,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  legend_main = NULL,
  sub = NULL,
  interpolate = FALSE,
  axes = TRUE,
  legend = TRUE,
  legend_label = NULL,
  legend_layer = 1,
  new.page = TRUE,
  ...
)

# S3 method for rasterly
print(x, ...)

Arguments

rasterlyObj	A rasterly object.
xlim	Numeric; the x limits (x1, x2) of the plot. Default is NULL.
ylim	Numeric; the y limits (y1, y2) of the plot. Default is NULL.
xlab	Character; the label to be used for the x axis. Default is NULL.
ylab	Character; the label to be used for the y axis. Default is NULL.
main	Character; the title to be used for the plot. Default is NULL.
sub	sub Character; a subtitle for the plot. Default is NULL.
interpolate	Logical. Linearly interpolates the image if TRUE. Default is FALSE.
axes	Logical; should axes be drawn? Default is TRUE, set to FALSE to hide axes.
legend	Logical. Show a figure legend? Default is TRUE; set to FALSE to hide the legend.
legend_label	Character. The label to apply to the figure legend. Default is NULL, which omits the figure legend label.
legend_layer	Numeric. Specify the layer level within the rasterly object. The default layer level is `1`, which represents the uppermost layer.
legend_main	Character. The main title to use within the figure legend. The default is NULL, which omits the figure legend title.
axes_gpar	Object of class gpar. This graphical parameter (gpar) controls axis color, size, and other aesthetics.
label_gpar	Object of class gpar. This graphical parameter (gpar) controls label color, size, and other aesthetics.
main_gpar	Object of class gpar. This graphical parameter (gpar) controls the main title's color, size, and other aesthetics.
legend_gpar	Object of class gpar. This graphical parameter (gpar) controls the legend's color, size, and other aesthetics.
name	Character. An identifier used to locate the grob within the display list and/or as a child of another grob.
gp	A gpar object, typically the output from a call to the function grid::gpar. This argument represents a list of graphical parameter settings.
vp	Object of class viewport. If provided, rasterlyGrob will pass this argument through to grob. Default is NULL.
...	Other arguments to modify the display.
x	A rasterly object
y	NULL, will be ignored.
new.page	display on a new page or not.

Details

We provide three functions to produce static graphics, which is based on the API of grid, plot and print.

• grid: The rasterlyGrob and grid.rasterly are the most flexible data structure. These functions produce a **grob** object. Users can modify the existing display by the functions provided by grid.

• plot.rasterly: The usage of this S3 method is very similar to the classic plot function. Users can set axis limits via xlim and ylim, as well as the corresponding labels using xlab and ylab, among other attributes.

• print.rasterly: This S3 method returns only a basic image raster.

See also

plotRasterly, ggRasterly

Examples

if(requireNamespace("grid")) {
  data <- data.frame(x = rnorm(1e6),
                     y = rexp(1e6, 10))
  # a rasterly object
  rasterlyObj <- data %>%
                   rasterly(mapping = aes(x = x, y = y)) %>%
                   rasterly_points()
  # Generate a grob
  rg <- rasterlyGrob(rasterlyObj)
  ## get the raster grob by `grid::getGrob()`
  grid::getGrob(rg, "raster")
  grid::grid.newpage()
  grid::grid.draw(rg)
  # or
  grid::grid.newpage()
  grid.rasterly(rasterlyObj)
  # or `plot`
  plot(rasterlyObj, xlab = "rnorm(1e6)",
       ylab = "rexp(1e6, 10)",
       main = "This is an arbitrary plot")
  # or simply print
  rasterlyObj
  ## it is equivalent to `print(rasterlyObj)`
}