Skip to contents

Plots for spatial elements

Source: R/spatialplot.R
spatialplots.Rd

  • SpatialImagePlot: Plot a SpatRaster object as an image.

  • SpatialMasksPlot: Plot a SpatRaster object as masks.

  • SpatialShapesPlot: Plot a SpatVector object as shapes.

  • SpatialPointsPlot: Plot a data.frame of points with spatial coordinates.

Usage

SpatialImagePlot(
  data,
  ext = NULL,
  raster = NULL,
  raster_dpi = NULL,
  flip_y = TRUE,
  palette = "turbo",
  palcolor = NULL,
  palette_reverse = FALSE,
  alpha = 1,
  fill_name = NULL,
  return_layer = FALSE,
  theme = "theme_box",
  theme_args = list(),
  legend.position = ifelse(return_layer, "none", "right"),
  legend.direction = "vertical",
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  seed = 8525,
  ...
)

SpatialMasksPlot(
  data,
  ext = NULL,
  flip_y = TRUE,
  add_border = TRUE,
  border_color = "black",
  border_size = 0.5,
  border_alpha = 1,
  palette = "turbo",
  palcolor = NULL,
  palette_reverse = FALSE,
  alpha = 1,
  fill_name = NULL,
  return_layer = FALSE,
  theme = "theme_box",
  theme_args = list(),
  legend.position = "right",
  legend.direction = "vertical",
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  seed = 8525,
  ...
)

SpatialShapesPlot(
  data,
  ext = NULL,
  flip_y = TRUE,
  fill_by = NULL,
  border_color = "black",
  border_size = 0.5,
  border_alpha = 1,
  palette = NULL,
  palcolor = NULL,
  palette_reverse = FALSE,
  alpha = 1,
  fill_name = NULL,
  facet_scales = "fixed",
  facet_nrow = NULL,
  facet_ncol = NULL,
  facet_byrow = TRUE,
  return_layer = FALSE,
  theme = "theme_box",
  theme_args = list(),
  legend.position = ifelse(return_layer, "none", "right"),
  legend.direction = "vertical",
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  seed = 8525,
  ...
)

SpatialPointsPlot(
  data,
  x = NULL,
  y = NULL,
  ext = NULL,
  flip_y = TRUE,
  color_by = NULL,
  size_by = NULL,
  fill_by = NULL,
  palette = NULL,
  palcolor = NULL,
  palette_reverse = FALSE,
  alpha = 1,
  color_name = NULL,
  size_name = NULL,
  shape = 16,
  border_color = "black",
  border_size = 0.5,
  border_alpha = 1,
  raster = NULL,
  raster_dpi = c(512, 512),
  hex = FALSE,
  hex_linewidth = 0.5,
  hex_count = FALSE,
  hex_bins = 50,
  hex_binwidth = NULL,
  label = FALSE,
  label_size = 4,
  label_fg = "white",
  label_bg = "black",
  label_bg_r = 0.1,
  label_repel = FALSE,
  label_repulsion = 20,
  label_pt_size = 1,
  label_pt_color = "black",
  label_segment_color = "black",
  label_insitu = FALSE,
  highlight = NULL,
  highlight_alpha = 1,
  highlight_size = 1,
  highlight_color = "black",
  highlight_stroke = 0.8,
  facet_scales = "fixed",
  facet_nrow = NULL,
  facet_ncol = NULL,
  facet_byrow = TRUE,
  return_layer = FALSE,
  theme = "theme_box",
  theme_args = list(),
  legend.position = ifelse(return_layer, "none", "right"),
  legend.direction = "vertical",
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  seed = 8525,
  ...
)

Arguments

data

A SpatRaster or SpatVector object from the terra package, or a data.frame for SpatialPointsPlot.

ext

A numeric vector of length 4 specifying the extent as c(xmin, xmax, ymin, ymax). Default is NULL.

raster

Whether to raster the plot. Default is NULL.

raster_dpi

A numeric vector of the raster dpi. Default is c(512, 512).

flip_y

Whether to flip the y-axis direction. Default is TRUE. This is useful for visualizing spatial data with the origin at the top left corner.

palette

A character string specifying the color palette to use. For SpatialImagePlot, if the data has 3 channels (RGB), it will be used as a color identity and this argument will be ignored.

palcolor

A character string specifying the color to use in the palette. A named list can be used to specify the colors for different split_by values. If some values are missing, the values from the palette will be used (palcolor will be NULL for those values).

palette_reverse

Whether to reverse the color palette. Default is FALSE.

alpha

A numeric value specifying the transparency of the plot.

fill_name

A character string for the fill legend title.

return_layer

Whether to return the layer or the plot. Default is FALSE.

theme

A character string or a theme class (i.e. ggplot2::theme_classic) specifying the theme to use. Default is "theme_this".

theme_args

A list of arguments to pass to the theme function.

legend.position

A character string specifying the position of the legend. if waiver(), for single groups, the legend will be "none", otherwise "right".

legend.direction

A character string specifying the direction of the legend.

title

A character string specifying the title of the plot. A function can be used to generate the title based on the default title. This is useful when split_by is used and the title needs to be dynamic.

subtitle

A character string specifying the subtitle of the plot.

xlab

A character string specifying the x-axis label.

ylab

A character string specifying the y-axis label.

seed

The random seed to use. Default is 8525.

...

Additional arguments.

add_border

Whether to add a border around the masks in SpatialMasksPlot. Default is TRUE.

border_color

A character string of the border color. Default is "black".

border_size

A numeric value of the border width. Default is 0.5.

border_alpha

A numeric value of the border transparency. Default is 1.

fill_by

A character string or vector specifying the column(s) to fill the shapes in SpatialShapesPlot.

facet_scales

Whether to scale the axes of facets. Default is "fixed" Other options are "free", "free_x", "free_y". See ggplot2::facet_wrap

facet_nrow

A numeric value specifying the number of rows in the facet. When facet_by is a single column and facet_wrap is used.

facet_ncol

A numeric value specifying the number of columns in the facet. When facet_by is a single column and facet_wrap is used.

facet_byrow

A logical value indicating whether to fill the plots by row. Default is TRUE.

x

A character string specifying the column name of the data frame to plot for the x-axis.

y

A character string specifying the column name of the data frame to plot for the y-axis.

color_by

A character string specifying the column to color the points in SpatialPointsPlot.

size_by

A character string specifying the column to size the points in SpatialPointsPlot.

color_name

A character string for the color legend title in SpatialPointsPlot.

size_name

A character string for the size legend title in SpatialPointsPlot.

shape

A numeric value or character string specifying the shape of the points in SpatialPointsPlot.

hex

Whether to use hex plot. Default is FALSE.

hex_linewidth

A numeric value of the hex line width. Default is 0.5.

hex_count

Whether to count the hex.

hex_bins

A numeric value of the hex bins. Default is 50.

hex_binwidth

A numeric value of the hex bin width. Default is NULL.

label

Whether to show the labels of groups. Default is FALSE.

label_size

A numeric value of the label size. Default is 4.

label_fg

A character string of the label foreground color. Default is "white".

label_bg

A character string of the label background color. Default is "black".

label_bg_r

A numeric value of the background ratio of the labels. Default is 0.1.

label_repel

Whether to repel the labels. Default is FALSE.

label_repulsion

A numeric value of the label repulsion. Default is 20.

label_pt_size

A numeric value of the label point size. Default is 1.

label_pt_color

A character string of the label point color. Default is "black".

label_segment_color

A character string of the label segment color. Default is "black".

label_insitu

Whether to place the raw labels (group names) in the center of the points with the corresponding group. Default is FALSE, which uses numbers instead of raw labels.

highlight

A character vector of the row names to highlight. Default is NULL.

highlight_alpha

A numeric value of the highlight transparency. Default is 1.

highlight_size

A numeric value of the highlight size. Default is 1.

highlight_color

A character string of the highlight color. Default is "black".

highlight_stroke

A numeric value of the highlight stroke. Default is 0.8.

Examples

# \donttest{
set.seed(8525)
# --- SpatialImagePlot ---
# Generate a sample SpatRaster
r <- terra::rast(
    nrows = 50, ncols = 40, vals = runif(2000),
    xmin = 0, xmax = 40, ymin = 0, ymax = 50,
    crs = ""
)
SpatialImagePlot(r)

SpatialImagePlot(r, raster = TRUE, raster_dpi = 20)

SpatialImagePlot(r, alpha = 0.5, theme = "theme_blank",
    theme_args = list(add_coord = FALSE), fill_name = "value")

SpatialImagePlot(r, ext = c(0, 10, 0, 10), flip_y = FALSE, palette = "viridis")


# --- SpatialMasksPlot ---
m <- terra::rast(
   nrows = 50, ncols = 40,
   vals = sample(c(1:5, NA), 2000, replace = TRUE, prob = c(rep(0.04, 5), 0.8)),
   xmin = 0, xmax = 40, ymin = 0, ymax = 50,
   crs = ""
)
SpatialMasksPlot(m, border_color = "red")

SpatialMasksPlot(m, ext = c(0, 15, 0, 20), add_border = FALSE,
    palette_reverse = TRUE, fill_name = "value")
#> Warning: Raster pixels are placed at uneven horizontal intervals and will be shifted
#> ℹ Consider using `geom_tile()` instead.


# --- SpatialShapesPlot ---
polygons <- data.frame(
   id = paste0("poly_", 1:10),
   cat = sample(LETTERS[1:3], 10, replace = TRUE),
   feat1 = rnorm(10),
   feat2 = rnorm(10),
   geometry = c(
       'POLYGON((64.6 75.3,66.0 70.5,66.4 70.2,67.0 69.8,72.8 70.4,64.6 75.3))',
       'POLYGON((56.7 63.0,52.3 65.6,48.0 63.2,51.2 55.7,57.1 59.2,56.7 63.0))',
       'POLYGON((9.9 16.5,9.3 15.9,8.0 13.1,11.5 7.8,17.8 11.3,9.9 16.5))',
       'POLYGON((64.9 37.2,60.3 37.4,57.6 31.7,58.9 29.3,64.0 28.1,64.9 37.2))',
       'POLYGON((30.5 49.1,22.4 46.5,22.4 43.9,30.9 41.9,31.6 42.9,30.5 49.1))',
       'POLYGON((78.3 57.8,70.5 61.6,71.6 52.7,72.2 52.5,77.4 54.5,78.3 57.8))',
       'POLYGON((41.8 23.8,41.3 25.9,41.0 26.4,36.5 28.7,35.8 28.6,41.8 23.8))',
       'POLYGON((15.7 75.9,14.2 74.4,15.7 67.5,23.0 69.8,23.4 71.7,15.7 75.9))',
       'POLYGON((80.7 37.4,75.3 31.3,77.1 28.5,82.5 28.0,83.1 28.5,80.7 37.4))',
       'POLYGON((15.5 37.8,14.4 38.6,7.3 32.6,8.3 30.9,15.1 30.2,15.5 37.8))'
   )
)

polygons <- terra::vect(polygons, crs = "EPSG:4326", geom = "geometry")

SpatialShapesPlot(polygons)

SpatialShapesPlot(polygons, ext = c(0, 20, 0, 20))

SpatialShapesPlot(polygons, border_color = "red", border_size = 2)

SpatialShapesPlot(polygons, fill_by = "cat", fill_name = "category")

# Let border color be determined by fill
SpatialShapesPlot(polygons, fill_by = "cat", alpha = 0.6, border_color = TRUE)

SpatialShapesPlot(polygons, fill_by = "feat1")

SpatialShapesPlot(polygons, fill_by = c("feat1", "feat2"), palette = "RdYlBu")


# --- SpatialPointsPlot ---
# create some random points in the above polygons
points <- data.frame(
  id = paste0("point_", 1:30),
  gene = sample(LETTERS[1:3], 30, replace = TRUE),
  feat1 = runif(30, 0, 100),
  feat2 = runif(30, 0, 100),
  size = runif(30, 1, 5),
  x = c(
    61.6, 14.3, 12.7, 49.6, 74.9, 58.9, 13.9, 24.7, 16.9, 15.6,
    72.4, 60.1, 75.4, 14.9, 80.3, 78.8, 16.7, 27.6, 48.9, 52.5,
    12.9, 11.8, 50.4, 25.6, 10.4, 51.9, 73.4, 26.8, 50.4, 60.0
  ),
  y = c(
    32.1, 12.8, 33.2, 59.9, 57.8, 31.9, 10.1, 46.8, 75.3, 69.0,
    60.0, 29.4, 54.2, 34.2, 35.3, 33.1, 74.7, 48.0, 63.2, 59.2,
    9.2, 15.1, 64.5, 47.1, 11.4, 60.1, 54.1, 44.5, 61.9, 30.3
  )
)

SpatialPointsPlot(points)

SpatialPointsPlot(points, color_by = "gene", size_by = "size", shape = 22,
  border_size = 1)

SpatialPointsPlot(points, raster = TRUE, raster_dpi = 30, color_by = "feat1")

SpatialPointsPlot(points, color_by = c("feat1", "feat2"), size_by = "size")

SpatialPointsPlot(points, color_by = "feat1", hex = TRUE)

SpatialPointsPlot(points, color_by = "gene", label = TRUE)

SpatialPointsPlot(points, color_by = "gene", highlight = 1:20,
  highlight_color = "red2", highlight_stroke = 0.8)


# --- Use the `return_layer` argument to get the ggplot layer
ext = c(0, 40, 0, 50)
ggplot2::ggplot() +
  SpatialImagePlot(r, return_layer = TRUE, alpha = 0.2, ext = ext) +
  SpatialShapesPlot(polygons, return_layer = TRUE, ext = ext, fill_by = "white") +
  SpatialPointsPlot(points, return_layer = TRUE, ext = ext, color_by = "feat1") +
  theme_box() +
  ggplot2::coord_sf(expand = 0) +
  ggplot2::scale_y_continuous(labels = function(x) -x)


# }