add_sp: Add spatial layers to a background map

In edwardlavender/prettyGraphics: Pretty Graphics with R

Add spatial layers to a background map

Description

These functions are designed to facilitate the addition of spatial layers to a background map.

Usage

add_sp_points(x, y = NULL, ext = NULL, crop_spatial = FALSE, ...)

add_sp_line(x, y = NULL, ext = NULL, crop_spatial = FALSE, ...)

add_sp_path(x, y = NULL, ext = NULL, crop_spatial = FALSE, ...)

add_sp_poly(x, ext = NULL, crop_spatial = FALSE, ...)

add_sp_raster(
  x,
  ext = NULL,
  crop_spatial = FALSE,
  plot_method = fields::image.plot,
  pretty_axis_args = NULL,
  ...
)

add_sp_grid_ll(
  x,
  crs_to = sp::CRS(SRS_string = "EPSG:4326"),
  easts = NULL,
  norths = NULL,
  ext = raster::extent(x),
  add_grid = list(lty = 2, lwd = 0.5),
  add_labels = list(),
  add_labels_unit_x = 1L,
  add_labels_unit_y = 1L
)

Arguments

x	A Raster* or Spatial* object, a two-column matrix of x and y coordinates or a numeric vector of x coordinates. Coordinate specifications are only supported for points, lines and paths; otherwise a Raster* or Spatial* object should be supplied. A numeric vector for x is assumed if y is provided (see below).
y	(optional) A numeric vector of y coordinates. This is only required if x is a numeric vector of x coordinates.
ext	(optional) An extent object that defines the extent of an area. If crop_spatial = TRUE, then the object is cropped to lie within this area via crop (see below).
crop_spatial	(optional) A logical variable that defines whether or not to crop the spatial layer to lie within the domain defined by ext. This is only implemented if ext is provided.
...	Additional arguments passed to the plotting functions, which are plot_method (usually image.plot) for rasters, arrows for paths, points for points and plot for all other objects.
plot_method	For add_sp_raster, plot_method is function that adds the layer to the plot. The default is image.plot.
pretty_axis_args	(optional) For add_sp_raster, pretty_axis_args is a named list, passed to pretty_axis, to control the tick mark positions and labels on the colour bar. This is only implemented add_sp_raster. For the default plotting method (image.plot), these can be controlled using the axis.args argument via ..., but pretty_axis_args can help to make prettier labels (e.g., with scientific notation). If supplied, plot_method must accept an axis.args like image.plot. pretty_axis is used to define a pretty sequence of tick mark positions and labels, and these passed to plot_method via axis.args as the at and labels elements.
crs_to	For add_sp_grid_ll, crs_to is a CRS object that defines the Coordinate Reference System of the grid.
easts	For add_sp_grid_ll, easts is a numeric vector of easting coordinates (in crs_to).
norths	For add_sp_grid_ll, norths is a numeric vector of northing coordinates (in crs_to).
add_grid	For add_sp_grid_ll, add_grid is a named list of graphical parameters, passed to plot, to customise the grid. NULL suppresses this option.
add_labels	For add_sp_grid_ll, add_labels is a named list of parameters, passed to axis, to customise axis (grid) labels. NULL suppresses this option.
add_labels_unit_x, add_labels_unit_y	For add_sp_grid_ll, add_labels_unit_x and add_labels_unit_y are integers that define which labels to keep (1 means every label; 2 means every 2nd label, and so on).

Details

These functions are designed to work with pretty_map, which produces a background plot and then adds layers to this plot. However, they can also be called directly after the definition of a background plot.

Value

The function adds a spatial layers to an existing plot.

Author(s)

Edward Lavender

Examples

#### Example (1) Adding single layers

## Examples with raster
# Define a background map and add a raster layer
pretty_map(dat_gebco)
add_sp_raster(dat_gebco)
# Customise the map
add_sp_raster(dat_gebco, col = viridis::viridis(100))

## Examples with polygon layers
# Define a background map and add a polygon layer
pretty_map(dat_coast_around_oban)
add_sp_poly(dat_coast_around_oban)
# Customise the map
add_sp_poly(dat_coast_around_oban, col = "darkgreen")

## Examples with points, lines and paths
## Define coordinates/line
xy <- cbind(c( -5.532913, -5.519556, -5.500856, -5.472138),
            c(56.42964, 56.44220, 56.45328, 56.45846))
xy_line <- Orcs::coords2Lines(xy, ID = 1)
## Add points
# via coordinates
pretty_map(dat_gebco)
add_sp_points(x = xy[1, ], y = xy[2, ])
# via matrix
pretty_map(dat_gebco)
add_sp_points(x = xy)
# via SpatialPoints
pretty_map(dat_gebco)
add_sp_points(x = sp::SpatialPoints(xy))
# Add lines (best via SpatialLines object)
pretty_map(dat_gebco)
add_sp_line(x = xy_line)
# Add path via coordinates, SpatialPoints or SpatialLines
pretty_map(dat_gebco)
add_sp_path(x = xy[, 1], y = xy[, 2], length = 0.05)
pretty_map(dat_gebco)
add_sp_path(x = sp::SpatialPoints(xy), length = 0.05)
pretty_map(dat_gebco)
add_sp_path(x = xy_line, length = 0.05)

#### Example (2) Layers can be stacked
pretty_map(dat_gebco)
add_sp_raster(dat_gebco)
add_sp_poly(dat_coast_around_oban)

#### Example (3) These functions are implemented pretty_map()
## Map of raster
pretty_map(add_rasters = list(x = dat_gebco))
## Map with a raster and multiple polygons, supplied as nested list
# Generate a random prism to include as a polygon
sim_prism <- sp::spsample(dat_coast_around_oban, n = 3, type = "random")
sim_prism <- sp::Polygon(sim_prism)
sim_prism <- sp::SpatialPolygons(list(sp::Polygons(list(sim_prism), ID = 1)))
# Make map
pretty_map(add_rasters = list(x = dat_gebco),
           add_polys = list(list(x = dat_coast_around_oban, col = "darkgreen"),
                            list(x = sim_prism, col = "blue")))

#### Example (4): Adding a lon/lat grid onto a projected map
pretty_map(add_polys = list(x = dat_coast_around_oban),
           pretty_axis_args =
             list(control_axis = list(lwd.ticks = 0, labels = FALSE))
           )
add_sp_grid_ll(dat_coast_around_oban)

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