map-design.Rmd
The mapgl package aims to expose the powerful mapdesign capabilities of Mapbox GL JS and Maplibre GL JS, while stillfeeling intuitive to R users. This means that map-making may require alittle more code than other mapping packages - but it also gives youmaximum flexibility in how you design your maps.
Let’s grab some data from tidycensus on median ageby Census tract in Florida and initialize an empty map focused onFlorida.
library(tidycensus)library(mapgl)fl_age <- get_acs( geography = "tract", variables = "B01002_001", state = "FL", year = 2022, geometry = TRUE)## Getting data from the 2018-2022 5-year ACSfl_map <- mapboxgl(mapbox_style("light")) |> fit_bounds(fl_age, animate = FALSE)fl_mapContinuous styling
Styling in Mapbox GL JS and Maplibre GL JS is typically handledthrough expressions. Expressions allow for quite a bit ofcustomization for map-makers, but can feel clunky for R users.mapgl includes several functions to help R userstranslate their code into expressions for use in their datavisualizations.
The interpolate() function will create aninterpolate expression, which smoothly transitions valuesbetween a series of stops. This means that you can natively create justabout any color palette you want and map that palette seamlessly to yourdata.
Below, we specify two values - 20 and 80 - and map the colors“lightblue” and “darkblue” to those values. Mapbox GL JS will smoothlyinterpolate colors between light blue and dark blue and map them to datavalues found in the specified column.
The add_legend() function adds a legend to your map. Inmapgl’s initial release, add_legend() doesnot automatically populate with values from the style. This gives usersmuch more flexibility in how their format their legend, though usersalso need to take care to ensure that the legend appropriatelyrepresents their data. Future updates to the package may includefunctionality for automated legends.
fl_map |> add_fill_layer( id = "fl_tracts", source = fl_age, fill_color = interpolate( column = "estimate", values = c(20, 80), stops = c("lightblue", "darkblue"), na_color = "lightgrey" ), fill_opacity = 0.5 ) |> add_legend( "Median age in Florida", values = c(20, 80), colors = c("lightblue", "darkblue") )Categorical styling
Cartographers may prefer a binned method for visualizing their datarather than the continuous palette shown above. In Mapbox GL JS andMapLibre, binned maps can be created with a stepexpression. The step_expr() function helps R users assemblethis expression. Step expressions may feel a little unfamiliar to Rusers, as they require a base value followed by a series ofstops. In the example below, we generate a five-colorpalette from ColorBrewer. The first color will be used as the base, andthe other four colors as the stops. The values then specifythe bin edges.
brewer_pal <- RColorBrewer::brewer.pal(5, "RdYlBu")fl_map |> add_fill_layer( id = "fl_tracts", source = fl_age, fill_color = step_expr( column = "estimate", base = brewer_pal[1], stops = brewer_pal[2:5], values = seq(25, 70, 15), na_color = "white" ), fill_opacity = 0.5 ) |> add_legend( "Median age in Florida", values = c( "Under 25", "25-40", "40-55", "55-70", "Above 70" ), colors = brewer_pal, type = "categorical" )Pop-ups, tooltips, and highlighting
Mapmakers will often want to expose some additional interactivity totheir users in the form of on-click popups, hover tooltips, and otherhover effects. In native JavaScript, this can be tricky to set up as itrequires knowledge of events, queries, and feature states in theselibraries. mapgl wraps this functionality to make thesefeatures accessible to R users.
The popup and tooltip arguments take astring as input representing the name of the column to display on clickor on hover. Both arguments accommodate HTML, so the best way to setthis up is to create a column of values to display in the popup ortooltip, then use this column when adding the layer.
Hover effects can be set with the hover_optionsargument. This argument takes a list of key-value pairs where the keysare arguments for a given layer type (in this case, the fill layer) andarguments are the desired values on hover. In the example shown here, wetell Mapbox GL JS to change a Census tract’s fill to yellow and fillopacity to 1 when the users hovers over the tract.
fl_age$popup <- glue::glue( "<strong>GEOID: </strong>{fl_age$GEOID}<br><strong>Median age: </strong>{fl_age$estimate}")fl_map |> add_fill_layer( id = "fl_tracts", source = fl_age, fill_color = interpolate( column = "estimate", values = c(20, 80), stops = c("lightblue", "darkblue"), na_color = "lightgrey" ), fill_opacity = 0.5, popup = "popup", tooltip = "estimate", hover_options = list( fill_color = "yellow", fill_opacity = 1 ) ) |> add_legend( "Median age in Florida", values = c(20, 80), colors = c("lightblue", "darkblue") )