ggspatial

https://paleolimbot.github.io/ggspatial/
Admin
ggspatial is an R package that enables mapping and spatial data visualization by combining spatial...
Tokens:17,552
Snippets:95
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Render North Arrow Examples

Source: https://paleolimbot.github.io/ggspatial/reference/north_arrow_orienteering.html

Examples demonstrating how to draw north arrow grobs on a new grid page.

```R
grid::grid.newpage()
grid::grid.draw(north_arrow_orienteering())


grid::grid.newpage()
grid::grid.draw(north_arrow_fancy_orienteering())


grid::grid.newpage()
grid::grid.draw(north_arrow_minimal())


grid::grid.newpage()
grid::grid.draw(north_arrow_nautical())
```

--------------------------------

### Install ggspatial Package

Source: https://paleolimbot.github.io/ggspatial/index.html

Install the ggspatial package from CRAN. For the development version, use the remotes package to install from GitHub.

```R
install.packages("ggspatial")
```

```R
install.packages("remotes") # if remotes isn't installed
remotes::install_github("paleolimbot/ggspatial")
```

--------------------------------

### Example: Plotting Cities with Spatial Layers

Source: https://paleolimbot.github.io/ggspatial/reference/stat_spatial_identity.html

Demonstrates using geom_spatial_point and stat_spatial_identity with different CRSs. Ensure the 'ggrepel' library is loaded for 'label_repel'.

```R
cities <- data.frame(
  x = c(-63.58595, 116.41214, 0),
  y = c(44.64862, 40.19063, 89.9),
  city = c("Halifax", "Beijing", "North Pole")
)

library(ggrepel)
ggplot(cities, aes(x, y)) +
  geom_spatial_point(crs = 4326) +
  stat_spatial_identity(aes(label = city), geom = "label_repel") +
  coord_sf(crs = 3857)
#> Assuming `crs = 4326` in stat_spatial_identity()
```

--------------------------------

### Plot spatial tiles and rectangles

Source: https://paleolimbot.github.io/ggspatial/reference/geom_spatial_rect.html

Examples demonstrating the use of geom_spatial_tile and geom_spatial_rect with coordinate transformations.

```R
library(ggplot2)
tile_df <- expand.grid(
  x = seq(-140, -52, by = 20),
  y = seq(40, 70, by = 10)
)

ggplot(tile_df, aes(x, y)) +
  geom_spatial_tile(crs = 4326) +
  coord_sf(crs = 3979)


# the same plot using geom_spatial_rect()
ggplot(
  tile_df,
  aes(xmin = x - 10, xmax = x + 10, ymin = y - 5, ymax = y + 5)
) +
  geom_spatial_rect(crs = 4326) +
  coord_sf(crs = 3979)
```

--------------------------------

### Visualize spatial segments with ggspatial

Source: https://paleolimbot.github.io/ggspatial/reference/geom_spatial_segment.html

Examples demonstrating how to use geom_spatial_segment to draw paths between coordinates, including great circle paths and flat segments.

```R
library(ggplot2)

# visualize flights from
# Halifax -> Anchorage -> Berlin -> Halifax
cities <- data.frame(
  lon = c(-63.58595, 116.41214, 13.50, -149.75),
  lat = c(44.64862, 40.19063, 52.51, 61.20),
  city = c("Halifax", "Beijing", "Berlin", "Anchorage"),
  city_to = c("Anchorage", "Beijing", "Berlin", "Halifax")
)

cities$lon_end <- cities$lon[c(4, 3, 1, 2)]
cities$lat_end <- cities$lat[c(4, 3, 1, 2)]

p <- ggplot(cities, aes(lon, lat, xend = lon_end, yend = lat_end)) +
  geom_spatial_point(crs = 4326)

# by default, geom_spatial_segment() connects points
# using the shortest distance along the face of the earth
# wrapping at the date line
p +
  geom_spatial_segment(crs = 4326) +
  coord_sf(crs = 3857)
#> Linking to GEOS 3.12.1, GDAL 3.8.4, PROJ 9.4.0; sf_use_s2() is TRUE


# to let the projection handle the dateline,
# use `wrap_dateline = FALSE` (most useful for
# when using `arrow`)
p +
  geom_spatial_segment(
    wrap_dateline = FALSE,
    arrow = grid::arrow(),
    crs = 4326
  ) +
  coord_sf(crs = 3995)


# to ignore the roundness of the earth, use
# `great_circle = FALSE`
p +
  geom_spatial_segment(
    great_circle = FALSE,
    arrow = grid::arrow(),
    crs = 4326
  ) +
  coord_sf(crs = 3995)
```

--------------------------------

### Example: Adding multiple spatial layers to a ggplot

Source: https://paleolimbot.github.io/ggspatial/reference/layer_spatial.html

Demonstrates how to use annotation_spatial and layer_spatial to add roads, depth data, and raster data to a ggplot. annotation_spatial layers do not train scales, while layer_spatial layers do. This example also includes spatial-aware scale bar and north arrow annotations.

```R
# \donttest{
library(ggplot2)
load_longlake_data(
  which = c(
    "longlake_roadsdf",
    "longlake_depthdf",
    "longlake_depth_raster"
  ),
  raster_format = "terra"
)

ggplot() +

  # annotation_spatial() layers don't train the scales, so data stays central
  annotation_spatial(longlake_roadsdf, size = 2, col = "black") +
  annotation_spatial(longlake_roadsdf, size = 1.6, col = "white") +

  # raster layers train scales and get projected automatically
  layer_spatial(longlake_depth_raster, aes(alpha = after_stat(band1)), fill = "darkblue") +
  scale_alpha_continuous(na.value = 0) +

  # layer_spatial() layers train the scales
  layer_spatial(longlake_depthdf, aes(col = DEPTH_M)) +

  # spatial-aware automagic scale bar
  annotation_scale(location = "tl") +

  # spatial-aware automagic north arrow
  annotation_north_arrow(location = "br", which_north = "true")

# }
```

--------------------------------

### Add spatial grid lines to a map

Source: https://paleolimbot.github.io/ggspatial/reference/annotation_spatial_hline.html

Example demonstrating the use of annotation_spatial_vline and annotation_spatial_hline to draw longitude and latitude lines on a projected map.

```R
cities <- data.frame(
  x = c(-63.58595, 116.41214, 0),
  y = c(44.64862, 40.19063, 89.9),
  city = c("Halifax", "Beijing", "North Pole")
)

p <- ggplot(cities, aes(x, y, label = city)) +
  geom_spatial_point(crs = 4326) +
  # view of the north pole
  coord_sf(crs = 3995)

p +
  # longitude lines
  annotation_spatial_vline(
    intercept = seq(-180, 180, by = 10),
    crs = 4326
  ) +
  # latitude lines
  annotation_spatial_hline(
    intercept = seq(0, 90, by = 10),
    crs = 4326
  )
```

--------------------------------

### Load Specific Longlake Data Subset

Source: https://paleolimbot.github.io/ggspatial/reference/load_longlake_data.html

Example of loading a specific subset of longlake data, in this case, 'longlake_waterdf'. Ensure the 'which' argument matches the desired object name.

```R
load_longlake_data(which = "longlake_waterdf")
```

--------------------------------

### Add a scalebar to a ggplot2 map

Source: https://paleolimbot.github.io/ggspatial/reference/annotation_scale.html

Example usage of annotation_scale within a ggplot2 pipeline using coord_sf.

```R
cities <- data.frame(
  x = c(-63.58595, 116.41214),
  y = c(44.64862, 40.19063),
  city = c("Halifax", "Beijing")
)

ggplot(cities) +
  geom_spatial_point(aes(x, y), crs = 4326) +
  annotation_scale() +
  coord_sf(crs = 3995)
```

--------------------------------

### ggplot2 layer for depth raster with continuous scale

Source: https://paleolimbot.github.io/ggspatial/reference/layer_spatial.Raster.html

Example showing `layer_spatial` with a depth raster and a continuous fill scale. Includes handling of missing values.

```R
ggplot() + layer_spatial(longlake_depth_raster) + scale_fill_continuous(na.value = NA)
#> Warning: Removed 6584 rows containing missing values or values outside the scale range
#> (`geom_raster()`).
```

--------------------------------

### ggplot2 layer with SpatRaster data

Source: https://paleolimbot.github.io/ggspatial/reference/layer_spatial.SpatRaster.html

Example of adding a SpatRaster object as a layer to a ggplot. Requires loading data and then using layer_spatial with the SpatRaster object.

```R
# \donttest{

library(ggplot2)
load_longlake_data(
  which = c(
    "longlake_osm",
    "longlake_depth_raster"
  ),
  raster_format = "terra"
)
ggplot() +
  layer_spatial(longlake_osm)


ggplot() +
  layer_spatial(longlake_depth_raster) +
  scale_fill_continuous(
    na.value = NA,
    type = "viridis"
  )
# }

```

--------------------------------

### ggplot2 layer for Raster objects

Source: https://paleolimbot.github.io/ggspatial/reference/layer_spatial.Raster.html

Example demonstrating how to use `layer_spatial` with an OSM raster object in ggplot2. Requires loading the 'longlake_osm' data.

```R
library(ggplot2)
load_longlake_data(which = c("longlake_osm", "longlake_depth_raster"))
ggplot() + layer_spatial(longlake_osm)
```

--------------------------------

### Add north arrow to a ggplot2 map

Source: https://paleolimbot.github.io/ggspatial/reference/annotation_north_arrow.html

Examples demonstrating the use of true-north and grid-north orientations within a spatial ggplot2 context.

```R
cities <- data.frame(
  x = c(-63.58595, 116.41214),
  y = c(44.64862, 40.19063),
  city = c("Halifax", "Beijing")
)

ggplot(cities) +
  geom_spatial_point(aes(x, y), crs = 4326) +
  annotation_north_arrow(which_north = "true") +
  coord_sf(crs = 3995)


ggplot(cities) +
  geom_spatial_point(aes(x, y), crs = 4326) +
  annotation_north_arrow(which_north = "grid") +
  coord_sf(crs = 3995)
```

--------------------------------

### Plotting polygons with geom_polypath

Source: https://paleolimbot.github.io/ggspatial/reference/geom_polypath.html

Example of using geom_polypath to plot spatial data. Requires loading data and mapping aesthetics like x, y, and group. Note: This function is deprecated and suggests using ggplot2::geom_polygon with the subgroup aesthetic.

```R
library(ggplot2)
load_longlake_data(which = "longlake_waterdf")
ggplot(df_spatial(longlake_waterdf), aes(x, y, group = piece_id)) +
  geom_polypath()
#> `geom_polypath()` is deprecated: use `ggplot2::geom_polygon()` with the `subgroup` aesthetic
```

--------------------------------

### Add a bounding box to a ggplot map

Source: https://paleolimbot.github.io/ggspatial/reference/layer_spatial.bbox.html

Use layer_spatial() with sf::st_bbox() to add a bounding box to a ggplot map. This example demonstrates adding the bounding box of 'longlake_waterdf'.

```R
# \donttest{
library(ggplot2)
load_longlake_data(which = c("longlake_waterdf", "longlake_depthdf"))
ggplot() +
  layer_spatial(sf::st_bbox(longlake_waterdf)) +
  layer_spatial(longlake_depthdf)


# use shadow_spatial() to include the geographic area of an object
# without drawing it
ggplot() +
  shadow_spatial(longlake_waterdf) +
  layer_spatial(longlake_depthdf)

# }

```

--------------------------------

### Introduction to ggspatial with ggplot2

Source: https://paleolimbot.github.io/ggspatial/index.html

Demonstrates how to use ggspatial with ggplot2 to create a map. Includes loading data, adding map tiles, spatial annotations, raster layers, and spatial-aware scale bar and north arrow.

```R
library(ggplot2)
library(ggspatial)
load_longlake_data()

ggplot() +
  # loads background map tiles from a tile source
  annotation_map_tile(zoomin = -1) +
  
  # annotation_spatial() layers don't train the scales, so data stays central
  annotation_spatial(longlake_roadsdf, size = 2, col = "black") +
  annotation_spatial(longlake_roadsdf, size = 1.6, col = "white") +

  # raster layers train scales and get projected automatically
  layer_spatial(longlake_depth_raster, aes(colour = after_stat(band1))) +
  # make no data values transparent
  scale_fill_viridis_c(na.value = NA) +
  
  # layer_spatial trains the scales
  layer_spatial(longlake_depthdf, aes(fill = DEPTH_M)) +
  
  # spatial-aware automagic scale bar
  annotation_scale(location = "tl") +

  # spatial-aware automagic north arrow
  annotation_north_arrow(location = "br", which_north = "true")
```

--------------------------------

### Define annotation_map_tile parameters

Source: https://paleolimbot.github.io/ggspatial/reference/annotation_map_tile.html

Displays the function signature and available arguments for configuring map tile layers.

```R
annotation_map_tile(
  type = "osm",
  zoom = NULL,
  zoomin = -2,
  forcedownload = FALSE,
  cachedir = NULL,
  progress = c("text", "none"),
  quiet = TRUE,
  interpolate = TRUE,
  data = NULL,
  mapping = NULL,
  alpha = 1
)
```

--------------------------------

### Visualizing stars objects with ggplot2

Source: https://paleolimbot.github.io/ggspatial/reference/layer_spatial.stars.html

Demonstrates rendering OSM and depth raster data using layer_spatial.

```R
# \donttest{

library(ggplot2)
load_longlake_data(
  which = c(
    "longlake_osm",
    "longlake_depth_raster"
  ),
  raster_format = "stars"
)
ggplot() +
  layer_spatial(longlake_osm)


ggplot() +
  layer_spatial(longlake_depth_raster) +
  scale_fill_continuous(
    na.value = NA,
    type = "viridis"
  )
#> Warning: Removed 6584 rows containing missing values or values outside the scale range
#> (`geom_raster()`).

# }
```

--------------------------------

### Load ggspatial and sample data

Source: https://paleolimbot.github.io/ggspatial/articles/ggspatial.html

Load the necessary libraries and sample data for use in the vignette. This includes ggplot2, ggspatial, and the longlake data.

```R
library(ggplot2)
library(ggspatial)
load_longlake_data()
```

--------------------------------

### Add spatial layers with annotation_spatial and layer_spatial

Source: https://paleolimbot.github.io/ggspatial/articles/ggspatial.html

Use annotation_spatial for backdrop layers and layer_spatial for data layers that should train scales. Aesthetics can be mapped for most spatial objects, with exceptions for RGB rasters.

```R
ggplot() +
  annotation_spatial(longlake_waterdf) +
  layer_spatial(longlake_depthdf, aes(col = DEPTH_M))
```

--------------------------------

### shadow_spatial

Source: https://paleolimbot.github.io/ggspatial/reference/layer_spatial.html

Creates a shadow spatial layer.

```APIDOC
## shadow_spatial(data, ...)

### Description
Creates a shadow spatial layer for a given spatial object.

### Parameters
- **data** (object) - Required - An object that can be coerced to an sf object using st_as_sf.
- **...** (dots) - Optional - Additional arguments.

### Value
A ggplot2 layer.
```

--------------------------------

### Define layer_spatial, annotation_spatial, and shadow_spatial for bbox

Source: https://paleolimbot.github.io/ggspatial/reference/layer_spatial.bbox.html

These are S3 methods for the 'bbox' class, used to add bounding boxes to spatial plots. 'layer_spatial' draws the bounding box, 'annotation_spatial' annotates it, and 'shadow_spatial' includes it without drawing.

```R
# S3 method for class 'bbox'
layer_spatial(data, mapping = aes(), ..., detail = 30)

# S3 method for class 'bbox'
annotation_spatial(data, mapping = aes(), ..., detail = 30)

# S3 method for class 'bbox'
shadow_spatial(data, ..., detail = 30)
```

--------------------------------

### Method signatures for stars objects

Source: https://paleolimbot.github.io/ggspatial/reference/layer_spatial.stars.html

Defines the S3 methods for layer_spatial and annotation_spatial, along with the associated ggproto classes.

```R
# S3 method for class 'stars'
layer_spatial(
  data,
  mapping = NULL,
  interpolate = NULL,
  is_annotation = FALSE,
  lazy = FALSE,
  dpi = 150,
  options = character(0),
  ...
)

# S3 method for class 'stars'
annotation_spatial(data, mapping = NULL, interpolate = NULL, ...)

StatSpatialStars

StatSpatialStarsAnnotation

StatSpatialStarsDf

GeomSpatialStars
```

--------------------------------

### Visualize map tiles with ggplot2

Source: https://paleolimbot.github.io/ggspatial/reference/annotation_map_tile.html

Demonstrates adding map tiles to a ggplot2 plot using annotation_map_tile and overlaying spatial data.

```R
# \donttest{
library(ggplot2)
load_longlake_data(which = "longlake_waterdf")

ggplot() +
  annotation_map_tile(zoom = 13, cachedir = system.file("rosm.cache", package = "ggspatial")) +
  geom_sf(data = longlake_waterdf, fill = NA, col = "grey50")
#> Zoom: 13

# }
```

--------------------------------

### load_longlake_data

Source: https://paleolimbot.github.io/ggspatial/reference/load_longlake_data.html

Loads longlake test data into the specified environment with configurable vector and raster formats.

```APIDOC
## load_longlake_data

### Description
Loads longlake test data from the Nova Scotia Topographic Database and Open Street Map into the R environment.

### Parameters
#### Arguments
- **env** (environment) - Optional - The environment in which to assign the objects.
- **vector_format** (character) - Optional - The format in which vector objects should be loaded (options: "sf", "sp").
- **raster_format** (character) - Optional - The format in which raster objects should be loaded (options: "terra", "stars", "stars_proxy", "raster").
- **which** (character) - Optional - An optional subset of objects to be loaded.

### Request Example
load_longlake_data(which = "longlake_waterdf")
```

--------------------------------

### Plotting cities with spatial points and labels

Source: https://paleolimbot.github.io/ggspatial/articles/ggspatial.html

Use `geom_spatial_point` and `geom_spatial_label_repel` to plot points from a data frame with x and y coordinate columns. Requires `ggplot2` and `ggrepel`.

```R
cities <- data.frame(
  x = c(-63.58595, 116.41214), 
  y = c(44.64862, 40.19063),
  city = c("Halifax", "Beijing")
)

ggplot(cities, aes(x, y)) +
  annotation_map_tile(type = "stamenwatercolor") +
  geom_spatial_point() +
  geom_spatial_label_repel(aes(label = city), box.padding = 1) +
  coord_sf(crs = 3995)
```

--------------------------------

### Display raster layers with layer_spatial

Source: https://paleolimbot.github.io/ggspatial/articles/ggspatial.html

Use layer_spatial to display raster data, with automatic reprojection and handling of RGB(A) rasters. Map aesthetics to bands using stat(band1) and set na.value for no data values.

```R
ggplot() +
  layer_spatial(longlake_depth_raster, aes(fill = after_stat(band1))) +
  scale_fill_viridis_c(na.value = NA)
```

--------------------------------

### POST /xy_transform

Source: https://paleolimbot.github.io/ggspatial/reference/xy_transform.html

Transforms x and y coordinates from a source CRS to a target CRS.

```APIDOC
## POST /xy_transform

### Description
Transforms x and y coordinates from a specified source CRS to a target CRS, with options to handle non-finite cases.

### Parameters
#### Request Body
- **x** (numeric vector) - Required - The x coordinates.
- **y** (numeric vector) - Required - The y coordinates.
- **from** (integer/string) - Optional - Source CRS (default: 4326).
- **to** (integer/string) - Optional - Target CRS (default: 4326).
- **na.rm** (boolean) - Optional - Whether to warn for non-finite cases (default: FALSE).

### Request Example
{
  "x": [1, 2, 3],
  "y": [1, 2, 3],
  "to": 3857
}

### Response
#### Success Response (200)
- **data.frame** (object) - A data frame containing transformed x and y components.

#### Response Example
{
  "x": [111319.5, 222639.0, 333958.5],
  "y": [111325.1, 222684.2, 334111.2]
}
```

--------------------------------

### Define annotation_north_arrow parameters

Source: https://paleolimbot.github.io/ggspatial/reference/annotation_north_arrow.html

The function signature for configuring the north arrow's dimensions, padding, rotation, and visual style.

```R
annotation_north_arrow(
  mapping = NULL,
  data = NULL,
  ...,
  height = unit(1.5, "cm"),
  width = unit(1.5, "cm"),
  pad_x = unit(0.25, "cm"),
  pad_y = unit(0.25, "cm"),
  rotation = NULL,
  style = north_arrow_orienteering
)
```

--------------------------------

### SpatRaster S3 Methods for layer_spatial

Source: https://paleolimbot.github.io/ggspatial/reference/layer_spatial.SpatRaster.html

Defines the S3 methods for the layer_spatial function when applied to SpatRaster objects. Includes parameters for data, mapping, interpolation, annotation, lazy loading, and DPI.

```R
# S3 method for class 'SpatRaster'
layer_spatial(
  data,
  mapping = NULL,
  interpolate = NULL,
  is_annotation = FALSE,
  lazy = FALSE,
  dpi = 150,
  ...
)

# S3 method for class 'SpatRaster'
annotation_spatial(data, mapping = NULL, interpolate = NULL, ...)
```

--------------------------------

### Define annotation_scale function signature

Source: https://paleolimbot.github.io/ggspatial/reference/annotation_scale.html

The function signature for annotation_scale, defining parameters for styling and positioning the scalebar.

```R
annotation_scale(
  mapping = NULL,
  data = NULL,
  ...,
  plot_unit = NULL,
  bar_cols = c("black", "white"),
  line_width = 1,
  height = unit(0.25, "cm"),
  pad_x = unit(0.25, "cm"),
  pad_y = unit(0.25, "cm"),
  text_pad = unit(0.15, "cm"),
  text_cex = 0.7,
  text_face = NULL,
  text_family = "",
  tick_height = 0.6
)
```

--------------------------------

### geom_spatial_rect and geom_spatial_tile

Source: https://paleolimbot.github.io/ggspatial/reference/geom_spatial_rect.html

These functions allow plotting projected rectangular regions. geom_spatial_rect is used for plotting bounding boxes (xmin, xmax, ymin, ymax), while geom_spatial_tile is used for plotting tiles based on x and y coordinates. Both functions can handle different CRS and projections.

```APIDOC
## geom_spatial_rect and geom_spatial_tile

### Description
These functions allow plotting projected rectangular regions. `geom_spatial_rect()` is used for plotting bounding boxes (xmin, xmax, ymin, ymax), while `geom_spatial_tile()` is used for plotting tiles based on x and y coordinates. Both functions can handle different CRS and projections.

### Method
These are ggplot2 geoms, typically used within a `ggplot()` call.

### Endpoints
`geom_spatial_rect()`
`geom_spatial_tile()`

### Parameters
#### Common Arguments
- **mapping** (aesthetics) - An aesthetic mapping created with `ggplot2::aes()`.
- **data** (data frame) - A data frame or other object, coerced to a data.frame by `ggplot2::fortify()`.
- **...** - Passed to the combined stat/geom as parameters or fixed aesthetics.
- **crs** (crs) - The crs of the x and y aesthetics, or NULL to use default lon/lat crs (with a message).
- **detail** (numeric) - Passed to `sf::st_segmentize()`: the number of line segments per quadrant of the bounding box. Increase this number for a smoother projected bounding box.
- **linejoin** (character) - How corners should be joined.
- **na.rm** (logical) - Should missing aesthetic values be removed?
- **show.legend** (logical) - See `ggplot2::layer()`.
- **inherit.aes** (logical) - See `ggplot2::layer()`.

#### Specific Arguments for geom_spatial_rect
- **xmin, xmax, ymin, ymax** (aesthetics) - Define the boundaries of the rectangle.

#### Specific Arguments for geom_spatial_tile
- **x, y** (aesthetics) - Define the center or position of the tile.

### Request Example
```R
library(ggplot2)

# Example for geom_spatial_tile
tile_df <- expand.grid(
  x = seq(-140, -52, by = 20),
  y = seq(40, 70, by = 10)
)

ggplot(tile_df, aes(x, y)) +
  geom_spatial_tile(crs = 4326) +
  coord_sf(crs = 3979)

# Example for geom_spatial_rect
ggplot(
  tile_df,
  aes(xmin = x - 10, xmax = x + 10, ymin = y - 5, ymax = y + 5)
) +
  geom_spatial_rect(crs = 4326) +
  coord_sf(crs = 3979)
```

### Response
These functions do not return a direct response in the typical API sense. They modify a ggplot object by adding a layer.

#### Success Response (ggplot object)
- The ggplot object will be updated with the spatial rectangle or tile layer.

#### Response Example
(See Request Example for how the plot is generated and displayed.)
```

--------------------------------

### Add north arrow and scale bar

Source: https://paleolimbot.github.io/ggspatial/articles/ggspatial.html

Incorporate a north arrow using annotation_north_arrow() and a scale bar using annotation_scale(). These functions are spatial-aware and do not require arguments by default.

```R
ggplot() +
  annotation_spatial(longlake_waterdf) +
  layer_spatial(longlake_depthdf, aes(col = DEPTH_M)) +
  annotation_scale(location = "tl") +
  annotation_north_arrow(location = "br", which_north = "true")
```

--------------------------------

### shadow_spatial.bbox

Source: https://paleolimbot.github.io/ggspatial/reference/layer_spatial.bbox.html

Includes the geographic area of an object without drawing it.

```APIDOC
## shadow_spatial(data, ..., detail = 30)

### Description
Use shadow_spatial() to include the geographic area of an object without drawing it on the plot.

### Parameters
- **data** (bbox) - Required - A bounding box generated by sf::st_bbox().
- **...** (dots) - Optional - Passed to geom_sf.
- **detail** (numeric) - Optional - Passed to sf::st_segmentize(): the number of line segments per quadrant of the bounding box.

### Request Example
ggplot() + shadow_spatial(longlake_waterdf) + layer_spatial(longlake_depthdf)
```

--------------------------------

### Add background OSM tiles

Source: https://paleolimbot.github.io/ggspatial/reference/annotation_map_tile.html

This function uses rosm::osm.image() to add background tiles to a ggplot. Ensure proper attribution when publishing maps with these tiles.

```APIDOC
## POST /api/annotation_map_tile

### Description
Adds background OpenStreetMap tiles to a ggplot object.

### Method
POST

### Endpoint
/api/annotation_map_tile

### Parameters
#### Query Parameters
- **type** (string) - Optional - The map type (one of that returned by rosm::osm.types).
- **zoom** (numeric) - Optional - The zoom level (overrides zoomin).
- **zoomin** (numeric) - Optional - Delta on default zoom. The default value is designed to download fewer tiles than you probably want. Use -1 or 0 to increase the resolution.
- **forcedownload** (boolean) - Optional - Re-download cached tiles?
- **cachedir** (string) - Optional - Specify cache directory.
- **progress** (string) - Optional - Use `progress = "none"` to suppress progress and zoom output. Options: "text", "none".
- **quiet** (boolean) - Optional - Use `quiet = FALSE` to see which URLs are downloaded.
- **interpolate** (boolean) - Optional - Passed to `grid::rasterGrob()`.
- **alpha** (numeric) - Optional - Use to make this layer semi-transparent.

#### Request Body
- **data** (object) - Optional - Specify data to use this geom with facets.
- **mapping** (object) - Optional - Specify mapping to use this geom with facets.

### Request Example
{
  "type": "osm",
  "zoom": 13,
  "zoomin": -2,
  "forcedownload": false,
  "cachedir": null,
  "progress": "text",
  "quiet": true,
  "interpolate": true,
  "data": null,
  "mapping": null,
  "alpha": 1
}

### Response
#### Success Response (200)
- **GeomMapTile** (object) - A ggplot2 layer.

#### Response Example
{
  "GeomMapTile": {
    "type": "osm",
    "zoom": 13,
    "zoomin": -2,
    "forcedownload": false,
    "cachedir": null,
    "progress": "text",
    "quiet": true,
    "interpolate": true,
    "data": null,
    "mapping": null,
    "alpha": 1
  }
}

### Examples
```r
library(ggplot2)
load_longlake_data(which = "longlake_waterdf")

ggplot() +
  annotation_map_tile(zoom = 13, cachedir = system.file("rosm.cache", package = "ggspatial")) +
  geom_sf(data = longlake_waterdf, fill = NA, col = "grey50")
#> Zoom: 13
```
```

--------------------------------

### Load Longlake Data Function Signature

Source: https://paleolimbot.github.io/ggspatial/reference/load_longlake_data.html

Defines the signature of the `load_longlake_data` function, specifying available arguments for environment, vector and raster formats, and object subsetting.

```R
load_longlake_data(
  env = parent.frame(),
  vector_format = c("sf", "sp"),
  raster_format = c("terra", "stars", "stars_proxy", "raster"),
  which = NULL
)
```

--------------------------------

### North Arrow Styles

Source: https://paleolimbot.github.io/ggspatial/reference/north_arrow_orienteering.html

Functions to create different north arrow styles for maps.

```APIDOC
## North Arrow Styles

This section describes the functions available for generating different north arrow styles.

### `north_arrow_orienteering`

Creates an orienteering-style north arrow.

#### Parameters

- **line_width** (numeric) - Default: 1 - Line width for the arrow.
- **line_col** (character) - Default: "black" - Line color for the arrow.
- **fill** (character) - Default: c("white", "black") - Fill colors for the arrow.
- **text_col** (character) - Default: "black" - Color of the text.
- **text_family** (character) - Default: "" - Font family for the text.
- **text_face** (NULL or character) - Default: NULL - Font face for the text (e.g., "bold").
- **text_size** (numeric) - Default: 10 - Font size for the text.
- **text_angle** (numeric) - Default: 0 - Angle of the text.

### `north_arrow_fancy_orienteering`

Creates a fancy orienteering-style north arrow.

#### Parameters

- **line_width** (numeric) - Default: 1 - Line width for the arrow.
- **line_col** (character) - Default: "black" - Line color for the arrow.
- **fill** (character) - Default: c("white", "black") - Fill colors for the arrow.
- **text_col** (character) - Default: "black" - Color of the text.
- **text_family** (character) - Default: "" - Font family for the text.
- **text_face** (NULL or character) - Default: NULL - Font face for the text (e.g., "bold").
- **text_size** (numeric) - Default: 10 - Font size for the text.
- **text_angle** (numeric) - Default: 0 - Angle of the text.

### `north_arrow_minimal`

Creates a minimal-style north arrow.

#### Parameters

- **line_width** (numeric) - Default: 1 - Line width for the arrow.
- **line_col** (character) - Default: "black" - Line color for the arrow.
- **fill** (character) - Default: "black" - Fill color for the arrow.
- **text_col** (character) - Default: "black" - Color of the text.
- **text_family** (character) - Default: "" - Font family for the text.
- **text_face** (NULL or character) - Default: NULL - Font face for the text (e.g., "bold").
- **text_size** (numeric) - Default: 10 - Font size for the text.

### `north_arrow_nautical`

Creates a nautical-style north arrow.

#### Parameters

- **line_width** (numeric) - Default: 1 - Line width for the arrow.
- **line_col** (character) - Default: "black" - Line color for the arrow.
- **fill** (character) - Default: c("black", "white") - Fill colors for the arrow.
- **text_size** (numeric) - Default: 10 - Font size for the text.
- **text_face** (NULL or character) - Default: NULL - Font face for the text (e.g., "bold").
- **text_family** (character) - Default: "" - Font family for the text.
- **text_col** (character) - Default: "black" - Color of the text.
- **text_angle** (numeric) - Default: 0 - Angle of the text.

### Value

A Grob with npc coordinates (more or less) 0 to 1.

### Examples

```R
grid::grid.newpage()
grid::grid.draw(north_arrow_orienteering())

grid::grid.newpage()
grid::grid.draw(north_arrow_fancy_orienteering())

grid::grid.newpage()
grid::grid.draw(north_arrow_minimal())

grid::grid.newpage()
grid::grid.draw(north_arrow_nautical())
```
```

--------------------------------

### Add tile map layers with annotation_map_tile

Source: https://paleolimbot.github.io/ggspatial/articles/ggspatial.html

Incorporate tile map layers from predefined sources or custom URLs using annotation_map_tile(). Tiles are projected to match the plot's CRS and zoom levels can be adjusted.

```R
ggplot() +
  annotation_map_tile(type = "osm") +
  layer_spatial(longlake_depthdf, aes(col = DEPTH_M))
```

--------------------------------

### annotation_spatial.Raster

Source: https://paleolimbot.github.io/ggspatial/reference/layer_spatial.Raster.html

Renders a Raster object as a spatial annotation layer.

```APIDOC
## annotation_spatial(data, ...)

### Description
Adds a spatial raster as an annotation layer to a ggplot2 plot.

### Parameters
- **data** (Raster) - Required - A Raster object.
- **mapping** (aes) - Optional - Currently only RGB or RGBA rasters are supported.
- **interpolate** (logical) - Optional - Interpolate resampling for rendered raster image.

### Response
A ggplot2 layer.
```

--------------------------------

### Define North Arrow Styles

Source: https://paleolimbot.github.io/ggspatial/reference/north_arrow_orienteering.html

Functions to configure the visual appearance and text properties of north arrow annotations.

```R
north_arrow_orienteering(
  line_width = 1,
  line_col = "black",
  fill = c("white", "black"),
  text_col = "black",
  text_family = "",
  text_face = NULL,
  text_size = 10,
  text_angle = 0
)

north_arrow_fancy_orienteering(
  line_width = 1,
  line_col = "black",
  fill = c("white", "black"),
  text_col = "black",
  text_family = "",
  text_face = NULL,
  text_size = 10,
  text_angle = 0
)

north_arrow_minimal(
  line_width = 1,
  line_col = "black",
  fill = "black",
  text_col = "black",
  text_family = "",
  text_face = NULL,
  text_size = 10
)

north_arrow_nautical(
  line_width = 1,
  line_col = "black",
  fill = c("black", "white"),
  text_size = 10,
  text_face = NULL,
  text_family = "",
  text_col = "black",
  text_angle = 0
)
```

--------------------------------

### Define spatial rectangular and tile geometries

Source: https://paleolimbot.github.io/ggspatial/reference/geom_spatial_rect.html

Constructor functions for adding spatial rectangles or tiles to a ggplot2 plot.

```R
geom_spatial_rect(
  mapping = NULL,
  data = NULL,
  ...,
  crs = NULL,
  detail = 30,
  linejoin = "mitre",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_spatial_tile(
  mapping = NULL,
  data = NULL,
  ...,
  crs = NULL,
  detail = 30,
  linejoin = "mitre",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

StatSpatialRect

StatSpatialTile
```

--------------------------------

### Define layer_spatial, annotation_spatial, and shadow_spatial functions

Source: https://paleolimbot.github.io/ggspatial/reference/layer_spatial.html

These are the base function definitions for creating spatial layers in ggplot2. They accept spatial data and mapping aesthetics.

```R
layer_spatial(data, mapping, ...)

annotation_spatial(data, mapping, ...)

# Default S3 method
layer_spatial(
  data,
  mapping = aes(),
  inherit.aes = FALSE,
  sf_params = list(),
  ...
)

# Default S3 method
annotation_spatial(
  data,
  mapping = aes(),
  inherit.aes = FALSE,
  sf_params = list(),
  ...
)

shadow_spatial(data, ...)

# Default S3 method
shadow_spatial(data, ...)
```

--------------------------------

### geom_polypath function signature

Source: https://paleolimbot.github.io/ggspatial/reference/geom_polypath.html

The geom_polypath function signature shows its arguments, including mapping, data, stat, position, na.rm, show.legend, inherit.aes, rule, and ellipsis for additional parameters.

```R
geom_polypath(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  rule = "winding",
  ...
)
```

--------------------------------

### Apply fixed aspect ratio to a ggplot

Source: https://paleolimbot.github.io/ggspatial/reference/fixed_plot_aspect.html

Demonstrates adding fixed_plot_aspect to a ggplot object alongside coord_fixed.

```R
library(ggplot2)
df <- data.frame(x =  0:5, y =  seq(0, 10, length.out = 6))
ggplot(df, aes(x, y)) +
  geom_point() +
  fixed_plot_aspect(ratio = 1) +
  coord_fixed()
```

--------------------------------

### Define spatial line annotations

Source: https://paleolimbot.github.io/ggspatial/reference/annotation_spatial_hline.html

Function signatures for adding horizontal and vertical lines to a spatial plot.

```R
annotation_spatial_hline(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  ...,
  intercept = waiver(),
  limits = NULL,
  detail = 100,
  crs = NULL,
  na.rm = FALSE,
  show.legend = NA
)

annotation_spatial_vline(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  ...,
  intercept = waiver(),
  limits = NULL,
  detail = 100,
  crs = NULL,
  na.rm = FALSE,
  show.legend = NA
)

GeomSpatialXline
```

--------------------------------

### annotation_spatial.bbox

Source: https://paleolimbot.github.io/ggspatial/reference/layer_spatial.bbox.html

Adds a bounding box as an annotation layer to a ggplot2 object.

```APIDOC
## annotation_spatial(data, mapping = aes(), ..., detail = 30)

### Description
Adds a bounding box as an annotation to a map.

### Parameters
- **data** (bbox) - Required - A bounding box generated by sf::st_bbox().
- **mapping** (aes) - Optional - A mapping created using aes.
- **...** (dots) - Optional - Passed to geom_sf.
- **detail** (numeric) - Optional - Passed to sf::st_segmentize(): the number of line segments per quadrant of the bounding box.
```

--------------------------------

### Define geom_spatial_segment parameters

Source: https://paleolimbot.github.io/ggspatial/reference/geom_spatial_segment.html

The function signature for geom_spatial_segment, which mirrors ggplot2::geom_segment with additional spatial parameters.

```R
geom_spatial_segment(
  mapping = NULL,
  data = NULL,
  ...,
  crs = NULL,
  detail = waiver(),
  great_circle = TRUE,
  wrap_dateline = TRUE,
  arrow = NULL,
  lineend = "butt",
  linejoin = "round",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)
```

--------------------------------

### layer_spatial.bbox

Source: https://paleolimbot.github.io/ggspatial/reference/layer_spatial.bbox.html

Adds a bounding box layer to a ggplot2 object.

```APIDOC
## layer_spatial(data, mapping = aes(), ..., detail = 30)

### Description
Adds a bounding box to a map. Use this method for objects of class 'bbox' generated by sf::st_bbox().

### Parameters
- **data** (bbox) - Required - A bounding box generated by sf::st_bbox().
- **mapping** (aes) - Optional - A mapping created using aes.
- **...** (dots) - Optional - Passed to geom_sf.
- **detail** (numeric) - Optional - Passed to sf::st_segmentize(): the number of line segments per quadrant of the bounding box. Increase this number for a smoother projected bounding box.

### Request Example
library(ggplot2)
layer_spatial(sf::st_bbox(longlake_waterdf))
```

--------------------------------

### annotation_spatial.SpatRaster

Source: https://paleolimbot.github.io/ggspatial/reference/layer_spatial.SpatRaster.html

Renders a SpatRaster object as a spatial annotation layer in ggplot2.

```APIDOC
## annotation_spatial(data, mapping, interpolate, ...)

### Description
Adds a SpatRaster object as an annotation layer to a ggplot2 plot.

### Parameters
#### Arguments
- **data** (SpatRaster) - Required - A SpatRaster object created with terra::rast().
- **mapping** (aes) - Optional - Currently supports RGB or RGBA rasters.
- **interpolate** (logical) - Optional - Interpolate resampling for rendered raster image.
- **...** (dots) - Optional - Passed to other methods.

### Response
- **Value** (ggplot2 layer) - A ggplot2 layer object.
```

--------------------------------

### S3 method for class 'Raster'

Source: https://paleolimbot.github.io/ggspatial/reference/layer_spatial.Raster.html

Defines the S3 method for the `layer_spatial` function when applied to a 'Raster' object. This is used for adding raster data to ggplot2 plots.

```R
layer_spatial(
  data,
  mapping = NULL,
  interpolate = NULL,
  is_annotation = FALSE,
  lazy = FALSE,
  dpi = 150,
  ...
)
```

```R
annotation_spatial(data, mapping = NULL, interpolate = NULL, ...)
```

--------------------------------

### annotation_scale() and GeomScaleBar

Source: https://paleolimbot.github.io/ggspatial/reference/annotation_scale.html

Adds a spatial-aware scale bar to a ggplot object. It can be used as a standalone function or as a geom.

```APIDOC
## annotation_scale() and GeomScaleBar

### Description
Adds a spatial-aware scale bar to a ggplot object. It can be used as a standalone function or as a geom.

### Method
`annotation_scale()`

### Endpoint
N/A (This is an R function, not a web API endpoint)

### Parameters
#### Arguments for `annotation_scale()`
- **mapping** (See Aesthetics) - Optional - Aesthetic mappings
- **data** (data.frame) - Optional - Data for the scale bar
- **...** (See Aesthetics) - Optional - Additional arguments
- **plot_unit** (character) - Optional - Unit for x and y coordinates (km, m, cm, mi, ft, in) for non-coord_sf applications
- **bar_cols** (character vector) - Optional - Colors for the scale bar
- **line_width** (numeric) - Optional - Line width for the scale bar
- **height** (unit) - Optional - Height of the scale bar
- **pad_x** (unit) - Optional - Horizontal distance between scale bar and panel edge
- **pad_y** (unit) - Optional - Vertical distance between scale bar and panel edge
- **text_pad** (unit) - Optional - Padding for the text labels
- **text_cex** (numeric) - Optional - Font size multiplier for text labels
- **text_face** (character) - Optional - Font face for text labels
- **text_family** (character) - Optional - Font family for text labels
- **tick_height** (numeric) - Optional - Height of ticks relative to scale bar height

#### Aesthetics (can be used as arguments or aesthetics)
- **width_hint** (numeric) - Suggested proportion of plot area for the scalebar
- **unit_category** (character) - "metric" or "imperial"
- **style** (character) - "bar" or "ticks"
- **location** (character) - Position of the scale bar (e.g., "tl" for top left)
- **line_col** (character) - Color of the scale bar line
- **text_col** (character) - Color of the scale bar text

### Request Example
```R
library(ggplot2)
library(ggspatial)
cities <- data.frame(
  x = c(-63.58595, 116.41214),
  y = c(44.64862, 40.19063),
  city = c("Halifax", "Beijing")
)

ggplot(cities) +
  geom_spatial_point(aes(x, y), crs = 4326) +
  annotation_scale() +
  coord_sf(crs = 3995)
```

### Response
#### Success Response (200)
Returns a ggplot2 layer object.

#### Response Example
N/A (This is an R function, not a web API endpoint that returns JSON)
```
Tokens:
Raw