pretty_plot: Prettier default plots

In edwardlavender/prettyGraphics: Pretty Graphics with R

Prettier default plots

Description

pretty_plot is a general function which creates plots with pretty axes for multiple plotting functions. The default option functions like plot but implements pretty axes using pretty_axis. Arguments can be passed to plot, but additional arguments (e.g., points_args, lines_args and mtext_args, which can be used to add points, lines and control axis labels respectively) provide additional flexibility if required. Some other plotting functions can be implemented by adjusting the plotting function, f, and by specifying whether that plot depends on x, y or x and y. The function can return the list from pretty_axis which can be useful for later adjustments to plots (e.g. setting the clipping region with clip).

Usage

pretty_plot(
  x,
  y = NULL,
  f = graphics::plot,
  plot_xy = "xy",
  plot_coordinates = TRUE,
  pretty_axis_args = list(side = 1:2, pretty = list(n = 5)),
  xlim = NULL,
  ylim = NULL,
  points_args = list(),
  lines_args = list(),
  xlab,
  ylab,
  main,
  mtext_args = list(),
  return_list = NULL,
  ...
)

Arguments

x	The x coordinates or an object from which coordinates can be extracted (see Details). Coordinates are used to create the axes and may be plotted (see f and plot_coordinates).
y	(optional) The y coordinates.
f	A function used to create a plot. The default is plot but some other functions are supported. f should support the following arguments: axes, which are turned off automatically; xlim, ylim; xlab; ylab; and main. This feature is experimental.
plot_xy	A character vector specifying whether the plotting function, f, requires "x", "y" or both ("xy").
plot_coordinates	A logical input which defines whether or not the plotting function acts on coordinates extracted from x or the original object (see examples using image).
pretty_axis_args	A named list or arguments passed to pretty_axis to define pretty axes. For convenience, x and y axis limits can also be specified via xlim and ylim (see below).
xlim, ylim	A vector of two axis limits. This is a short-cut to specifying axis limits via pretty_axis_args (see pretty_axis).
points_args	A named list of arguments passed to points to control points. These can also be supplied via ... but point_args can provide additional flexibility where required. To implement this option, you probably want to specify type = "n" via ... because points_args is evaluated after the plot is evaluated.
lines_args	A named list of arguments passed to lines to control lines. These can also be supplied via ... but lines_args can provide additional flexibility where required. To implement this option, you probably want to specify type = "n" via ... because lines_args is evaluated after the plot is evaluated.
xlab	A character input which defines the label for the x axis. By default, this is "" so that labels can be added via mtext_args which is more flexible (see below). However, the label can be specified via xlab for speed.
ylab	A character input which defines the label for the y axis. By default, this is "" so that labels can be added via mtext_args which is more flexible (see below). However, the label can be specified via ylab for speed.
main	A character input which defines the label for the plot axis. By default, this is "" so that labels can be added via mtext_args which is more flexible (see below). However, the label can be specified via main for speed.
mtext_args	A named list of arguments passed to mtext to control axes' labels. These can also be supplied via xlab, ylab and main but mtext_args can provide additional flexibility where required.
return_list	(depreciated) A logical input which defines whether or not to return the list produced by pretty_axis.
...	Other parameters passed to f.

Details

x and y coordinates usually need to be provided. Some other object classes may be provided to x, from which x and y coordinates can be extracted to create axes. In this case, the user needs to indicate whether the plotting function, f, requires x and/or y and acts on extracted coordinates (plot_coordinates = TRUE) or the original object (plot_coordinates = FALSE). Objects of class density and some Spatial* objects (RasterLayer, SpatialPoints, Line, Lines, Polygon, Polygons, SpatialPolygonsDataFrame) are currently supported. If plot_xy = "xy" and only x is provided, x is treated as the response variable and plotted against an index (like plot).

Value

The function returns a plot and, invisibly, a list of arguments that are used to create pretty axes via pretty_axis.

Author(s)

Edward Lavender

Examples

#### Example (1): An example with graphics::plot()
set.seed(1)
pretty_plot(stats::runif(10, 0, 1),
            stats::runif(10, 0, 1),
            points_args = list(pch = 21, col = scales::alpha("black", 0.8)))

#### Example (2): pretty_plot() can also work with factors.
# ... As usual, the number of breaks can be controlled via pretty_axis_args:
## Define data:
dx <- factor(LETTERS[1:10])
dy <- 1:10
## Example plots:
pp <- par(mfrow = c(2, 2))
# Specify a break for every factor level via the pretty 'n' argument.
# ... (this can also be achieved via the units argument)
pretty_plot(dx, dy,
            pretty_axis_args = list(side = 1:2, pretty = list(n = 10))
)
# Specify a break for every other factor level via the pretty 'n' argument.
# ... (this can also be achieved via the units argument)
pretty_plot(dx, dy,
            pretty_axis_args = list(side = 1:2, pretty = list(n = 10/2))
)
# Comparisons to default plots:
graphics::plot(dx, dy)
graphics::plot.default(dx, dy)
par(pp)

#### Example (3): If only x is provided, x is plotted against an index
pretty_plot(x = c(10, 20))

#### Example (4): Coordinates usually need to be provided
# ... but pretty_plot() works with some other objects.
## Density example
pretty_plot(density(stats::rnorm(100, 0, 1)), type = "l")
## RasterLayer example
# Define example raster
r <- raster::raster(nrows=10, ncols=10)
r <- raster::setValues(r, 1:raster::ncell(r))
# Note the use of raster::image() rather than raster::plot() for plotting
# ... because raster::plot() doesn't act on xlim or ylim arguments defined by pretty_axis().
pretty_plot(x = r, y = NULL,
            f = raster::image, plot_xy = "x", plot_coordinates = FALSE)
## SpatialPolygonsDataFrame example
# Outline
pretty_plot(x = dat_coast_around_oban, y = NULL,
            f = raster::plot, plot_xy = "x", plot_coordinates = FALSE)
# Customised plot
pretty_plot(x = dat_coast_around_oban, y = NULL,
            pretty_axis_args = list(side = 1:4),
            xlim = raster::extent(dat_coast_around_oban)[1:2],
            ylim = raster::extent(dat_coast_around_oban)[3:4],
            f = raster::plot, plot_xy = "x", plot_coordinates = FALSE,
            col = "darkgreen")

#### Example (5): An example with stats::qqnorm()
# Define x and y values for qqnorm plot
set.seed(1)
qq <- qqplot(stats::rnorm(100, 0, 1), stats::rnorm(100, 0, 1), plot.it = FALSE)
# Define plot, saving list of axis parameters in axis_ls
# Supply x and y (qq$x and qq$y) respectively to create pretty axis limits;
# ... but use qqnorm to create plot which only required y (dd$y) (see ?stats::qqnorm)
axis_ls <- pretty_plot(qq$x, qq$y, f = stats::qqnorm, plot_xy = "y")
# Set clipping region with axis limits
usr <- par("usr")
clip(axis_ls[[1]]$lim[1], axis_ls[[1]]$lim[2], axis_ls[[2]]$lim[1], axis_ls[[2]]$lim[2])
# Add qqline within limits
qqline(qq$y)
do.call("clip", as.list(usr))

edwardlavender/prettyGraphics documentation built on Jan. 19, 2025, 2:47 p.m.