Skip to content

The Map Widget

Source: vignettes/articles/widget.Rmd
widget.Rmd

The function leaflet() returns a Leaflet map widget, which stores a list of objects that can be modified or updated later. Most functions in this package have an argument map as their first argument, which makes it easy to use the pipe operator %>% in the magrittr package, as you have seen from the example in vignette("leaflet").

Initializing Options

The map widget can be initialized with certain parameters. This is achieved by populating the options argument as shown below.

# Set value for the minZoom and maxZoom settings.
leaflet(options = leafletOptions(minZoom = 0, maxZoom = 18))

The leafletOptions() can be passed any option described in the leaflet reference document. Using the leafletOptions(), you can set a custom CRS and have your map displayed in a non spherical Mercator projection as described in projections.

Map Methods

You can manipulate the attributes of the map widget using a series of methods. Please see the help page ?setView for details.

  • setView() sets the center of the map view and the zoom level;
  • fitBounds() fits the view into the rectangle [lng1, lat1] – [lng2, lat2];
  • clearBounds() clears the bound, so that the view will be automatically determined by the range of latitude/longitude data in the map layers if provided;

The Data Object

Both leaflet() and the map layer functions have an optional data parameter that is designed to receive spatial data in one of several forms:

  • From base R:
    • lng/lat matrix
    • data frame with lng/lat columns
  • From the {maps} package:
    • the data frame from returned from map()
  • Simple features from the sf package.

leaflet() is, additionally, back-compatible with sp SpatailDataFrames, although the use of these is discouraged for new users.

The data argument is used to derive spatial data for functions that need it; for example, if data is a sf Simple Features data.frame, then calling addPolygons() on that map widget will know to add the polygons from the geometry column.

It is straightforward to derive these variables from sf objects since they always represent spatial data in the same way. On the other hand, for a normal matrix or data frame, any numeric column could potentially contain spatial data. So we resort to guessing based on column names:

  • the latitude variable is guessed by looking for columns named lat or latitude (case-insensitive)
  • the longitude variable is guessed by looking for lng, long, or longitude

You can always explicitly identify latitude/longitude columns by providing lng and lat arguments to the layer function.

For example, we do not specify the values for the arguments lat and lng in addCircles() below, but the columns Lat and Long in the data frame df will be automatically used:

# add some circles to a map
df = data.frame(Lat = 1:10, Long = rnorm(10))
leaflet(df) %>% addCircles()

You can also explicitly specify the Lat and Long columns (see below for more info on the ~ syntax):

leaflet(df) %>% addCircles(lng = ~Long, lat = ~Lat)

A map layer may use a different data object to override the data provided in leaflet(). We can rewrite the above example as:

leaflet() %>% addCircles(data = df)
leaflet() %>% addCircles(data = df, lat = ~ Lat, lng = ~ Long)

Below are examples of using sf and {maps}, respectively:

library(sf)
polygon1 <- st_polygon(list(cbind(c(2, 4, 4, 1, 2), c(2, 3, 5, 4, 2))))
polygon2 <- st_polygon(list(cbind(c(5, 4, 2, 5), c(2, 3, 2, 2))))
polygon3 <- st_polygon(list(cbind(c(4, 4, 5, 10, 4), c(5, 3, 2, 5, 5))))
polygon4 <- st_polygon(list(cbind(c(5, 6, 6, 5, 5), c(4, 4, 3, 3, 4))))
multi_polygon <- st_multipolygon(list(
    list(cbind(c(4, 4, 5, 10, 4), c(5, 3, 2, 5, 5))),
    list(cbind(c(5, 6, 6, 5, 5), c(4, 4, 3, 3, 4)))
))
sf_polygons <- st_sf(geometry = st_sfc(polygon1, polygon2, multi_polygon))
leaflet(height = "300px") %>% addPolygons(data = sf_polygons)

library(maps)
mapStates = map("state", fill = TRUE, plot = FALSE)
leaflet(data = mapStates) %>%
  addTiles() %>%
  addPolygons(fillColor = topo.colors(10, alpha = NULL), stroke = FALSE)

The Formula Interface

The arguments of all layer functions can take normal R objects, such as a numeric vector for the lat argument, or a character vector of colors for the color argument. They can also take a one-sided formula, in which case the formula will be evaluated using the data argument as the environment. For example, ~ x means the variable x in the data object, and you can write arbitrary expressions on the right-hand side, e.g., ~ sqrt(x + 1).

m = leaflet() %>% addTiles()
df = data.frame(
  lat = rnorm(100),
  lng = rnorm(100),
  size = runif(100, 5, 20),
  color = sample(colors(), 100)
)
m = leaflet(df) %>% addTiles()
m %>% addCircleMarkers(radius = ~size, color = ~color, fill = FALSE)
m %>% addCircleMarkers(radius = runif(100, 4, 10), color = c('red'))