--- title: "Getting started with tidymapr" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Getting started with tidymapr} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( dev.args = list(bg = "white"), collapse = TRUE, comment = "#>", fig.width = 7, fig.height = 6, out.width = "100%", dpi = 110 ) ok <- all(vapply( c("sf", "terra", "ggplot2", "ggnewscale"), requireNamespace, logical(1), quietly = TRUE )) knitr::opts_chunk$set(eval = ok) ``` tidymapr makes publication-quality maps and does spatial analysis in R, in the style of a desktop GIS. This guide takes one small, real data set from raw layers to a finished figure, an interactive web map and a 3D view. Everything here uses data shipped with the terra and sf packages, so it runs offline. ```{r setup, message = FALSE} library(tidymapr) ``` ## The data Luxembourg's elevation (from SRTM), its 12 cantons with their population, and its main roads, all shipped with terra. ```{r data} elev <- terra::rast(system.file("ex/elev.tif", package = "terra")) cantons <- sf::st_read(system.file("ex/lux.shp", package = "terra"), quiet = TRUE) roads <- sf::st_as_sf(terra::unwrap( readRDS(system.file("ex/lux_highways.rds", package = "terra")) )) seats <- suppressWarnings(sf::st_point_on_surface(cantons)) cantons[, c("NAME_2", "AREA", "POP")] ``` ## A map in one call `geo_automap()` chooses the projection, the classification, the colour ramp, the legend and the map furniture from the data, and `geo_automap_explain()` says why. ```{r automap, fig.alt = "Population of Luxembourg's cantons in five classes, with scale bar and north arrow"} m <- geo_automap(cantons, POP, legend_title = "Inhabitants") m geo_automap_explain(m) ``` ## A layered map `geo_map()` builds a map one layer at a time, as in a desktop GIS. Each layer gets its own legend section with the symbol for its geometry: a colour bar for the raster, a box for polygons, a line for roads and a point for towns. Roads are drawn in two classes, minor roads first and main roads on top, so the network stays connected (in this OpenStreetMap extract each road is split into pieces of different classes). `preset` gives a layer a standard cartographic style by name (see `map_presets()`). ```{r layered, fig.alt = "Layered map of Luxembourg: elevation over a hillshade, canton boundaries, main roads, canton centres and names"} lux <- geo_map(title = "Luxembourg", caption = "Data: terra package") |> map_raster(elev, name = "Elevation (m)", palette = "Terrain 2", hillshade = TRUE) |> map_polygons(cantons, preset = "admin", label = "Cantons") |> map_lines(roads[roads$highway != "primary", ], preset = "road_minor", label = "Other road", linewidth = 0.25 ) |> map_lines(roads[roads$highway == "primary", ], preset = "road_major") |> map_points(seats, preset = "town", label = "Canton centre") |> map_labels(seats, text = NAME_2, size = 2.6) lux ``` Zoom in on Luxembourg City and put the legend inside the map; tidymapr picks a corner that does not hide the scale bar or the north arrow. ```{r zoom, fig.alt = "The same map zoomed four times on Luxembourg City, with the legend inside the map"} lux |> map_zoom(4, centre = c(6.13, 49.61)) ``` ## Figures with several maps `geo_panels()` puts maps side by side with tags (a), (b); `geo_facet_map()` draws small multiples that share one classification. ```{r panels, fig.height = 4.5, fig.alt = "Two maps of Luxembourg side by side: elevation and population"} a <- geo_map(subtitle = "Elevation", north_arrow = FALSE) |> map_raster(elev, name = "Metres", palette = "Terrain 2") b <- geo_map(subtitle = "Population", scale_bar = FALSE) |> map_polygons(cantons, fill = POP, n = 4, group = "Inhabitants") geo_panels(a, b, ncol = 2, guides = "keep") ``` ## Labels that follow the shape ```{r curved, fig.alt = "Canton names written along the long axis of each canton"} geo_map(scale_bar = FALSE, north_arrow = FALSE) |> map_polygons(cantons, fill = "grey95", border = "grey60", label = "Cantons") |> map_curved_labels(cantons, text = NAME_2, size = 3.2, colour = "#7F2704") ``` ## Analysis tidymapr includes the spatial statistics of a GIS, written in C++ and run on several cores. For example, hot spots of population density (Getis-Ord Gi\*) and the terrain wetness index of the elevation model: ```{r analysis, fig.height = 4.5, fig.alt = "Topographic wetness index of Luxembourg"} cantons$density <- cantons$POP / cantons$AREA hot <- geo_hotspot(cantons, density, k = 3) sf::st_drop_geometry(hot)[, c("NAME_2", "density", "hotspot")] twi <- geo_twi(terra::project(elev, "EPSG:2169")) geo_map(title = "Topographic wetness index") |> map_raster(twi, name = "TWI", palette = "Blues 3") ``` ## 3D and the web `geo_map3d()` renders an elevation model as a 3D block diagram, drawn in C++ without OpenGL. Here, Mt Wilhelm in Papua New Guinea, from the Copernicus 30 m DEM (averaged to 90 m and shipped with tidymapr), with the ant survey sites of Mottl, Moses and Klimes (2023) placed on the terrain. ```{r map3d, fig.alt = "3D view of Mt Wilhelm, Papua New Guinea, with the eight ant survey sites from 200 m to 3700 m labelled"} wilhelm <- terra::rast(system.file("extdata", "wilhelm-dem.tif", package = "tidymapr")) ant_sites <- png_ants_sites[!duplicated(png_ants_sites$site), ] |> sf::st_as_sf(coords = c("lon", "lat"), crs = 4326) geo_map3d(wilhelm, theta = 190, phi = 30, points = ant_sites, label = "site", title = "Mt Wilhelm, Papua New Guinea", subtitle = "Ant survey sites on the Copernicus DEM", width = 1600, height = 1000 ) ``` and as an interactive web map in one HTML file, with switchable layers, pop-ups and the same legend: ```{r webmap, eval = FALSE} geo_webmap(lux, file = "luxembourg.html") ``` ## Save `geo_save()` writes a figure at journal sizes and resolution, on a white background: ```{r save, eval = FALSE} geo_save(lux, "luxembourg.png", width = 180, height = 190, dpi = 300) ``` ## Where next - Two case studies: [where the brown-throated sloth lives](https://tidymapr.in4metrix.dev/articles/case-sloth-sdm.html) (species distribution models) and [tree diversity across Barro Colorado Island](https://tidymapr.in4metrix.dev/articles/case-bci-diversity.html) (with [tidydiversity](https://tidydiversity.in4metrix.dev)). - The [gallery](https://tidymapr.in4metrix.dev/articles/gallery.html) shows every kind of map with its code. - The [spatial analysis guide](https://tidymapr.in4metrix.dev/articles/geospatial.html) covers interpolation, hot spots, hydrology, remote sensing, species distribution models and GeoSpaX recipes.