Use of proper symbols (= or ~) with leaflet package

Question

I have seen two different formats used with popups in the leaflet package. For a single popup attached to a single marker, functions are called using "=" to assign variable values. (see https://rstudio.github.io/leaflet/popups.html). For a plot of multiple data values, I see both "=" and "= ~" used to assign values to variables. (see Change color of leaflet marker). I may not be making the correct observation, but does this relate to a singular point as opposed to a multiple points, or to something else? Where would I find the rules here?

Answer 1

Perhaps, these lines in leaflet might help explain what is happening. In effect the ~ means to evaluate that expression with the data provided. Your comment "does this relate to a singular point as opposed to a multiple points" is very close to the correct observation. If you look again at the lines, the doResolveFormula is defined for data.frame, list, map, and Spatial*.

Explain in Code

Let's build off the popups example to hopefully explain this in code. This is the example.

library(leaflet)

content <- paste(sep = "<br/>",
                 "<b><a href='http://www.samurainoodle.com'>Samurai Noodle</a></b>",
                 "606 5th Ave. S",
                 "Seattle, WA 98138"
)

leaflet() %>% addTiles() %>%
  addPopups(-122.327298, 47.597131, content,
            options = popupOptions(closeButton = FALSE)
  )

Now, let's put the lat, lng, and content all in a data.frame, and make an error on our path to discovery.

content_df <- data.frame(
  lng = -122.327298,
  lat = 47.59731,
  content = content
)

leaflet() %>% addTiles() %>%
  addPopups(content_df,
            options = popupOptions(closeButton = FALSE)
  )

So even though there is only one data point for our content, leaflet does not know how to map the columns of the data.frame to the arguments it expects. Here is how to help leaflet understand.

content_df <- data.frame(
  lng = -122.327298,
  lat = 47.59731,
  content = content
)

leaflet() %>% addTiles() %>%
  addPopups(
    lng = ~lng,
    lat = ~lat,
    popup = ~content,
    # default data is getMapData(map)
    #  which does not contain our popup content
    data = content_df,
    options = popupOptions(closeButton = FALSE)
  )

Manually Evaluate ~

Let's manually use resolveFormula to see what is happening.

leaflet:::resolveFormula(~content,content_df)

which gives us the content column of our content_df.

    [1] <b><a href='http://www.samurainoodle.com'>Samurai Noodle</a></b><br/>606 5th Ave. S<br/>Seattle, WA 98138

Outside of our mapping application, I'll add a simple contrived example to explain in one more way.

leaflet:::resolveFormula(~1+2,data.frame())

gives us 1+2.

3

The empty data.frame() is necessary, so R will choose doResolveFormula.data.frame. We could have also used list().

Why It Is Important

I really hope this helps. This is sort of an unconventional use of ~, and I had trouble with it at first also. However, I think it is important to understand as more and more packages outside of RStudio's are adopting this convention.