better documentation for map related functions?

[moodymudskipper]

Here are several comments, They're linked but I'm happy to split them into several issues if it's preferable.

geom_map()

The titles and descriptions of geom_map are :

Polygons from a reference map
This is pure annotation, so does not affect position scale

I think this could be clearer, geom_map wraps the functionalities of geom_polygon to plot maps. the difference being that we provide a reference map through the map argument, which takes care of the x and y aesthetics and allows us to use a more convenient data argument.

The description of the map argument doesn't mention the map_data() function (only an example does), tough it will probably be useful in most cases. Instead it says :

Data frame that contains the map coordinates. This will typically be created using fortify() on a spatial object. It must contain columns x or long, y or lat, and region or id.

fortify()

If we follow to fortify's page we read :

Rather than using this function, I now recommend using the broom package, which implements a much wider range of methods. fortify may be deprecated in the future.

It doesn't say what fortify() does, says we shouldn't use it anyway, and refers to broom without telling us which functions from broom we should use (we might think it's just broom::fortify() but it doesn't exist).

map_data()

The map argument is described as :

name of map provided by the maps package. These include maps::county(), maps::france(), maps::italy(), maps::nz(), maps::state(), maps::usa(), maps::world(), maps::world2().

But none of these functions exist.

From examples we can infer that we can use a string such as "state", but the doc seems to hint that we might have more choice than what's in this list, and doesn't tell us where to look. The following argument hints that we can look at ?maps::map, and there we find that we can infer the list of available maps by looking help(package='maps'). I think it is very convoluted and we would benefit from having these maps enumerated in the ggplot2 doc.

coord_map()

The projection argument is forwarded to mapproj::mapproject so I understand that you decide to redirect the user there, but again, once there we need to read and scroll to get a list of possible values and it all adds up for a user who "just wants to draw a map", as this one : https://twitter.com/calvinmdewilde/status/1215116524798636032.

So here as well, could we have in ggplot2's doc the list of available projections ?

a map vignette ?

I believe a vignette focused on maps would be extremely helpful. It could showcase all the projections and a couple cases of maps (world, US). At the moment if I google "ggplot maps" I find mostly references discussing geom_polygon() so it seems that geom_map() is under-advertised, which I think is unfortunate as map charts are very popular these days.

[yutannihilation]

Some quick comments.

It doesn't say what fortify() does, says we shouldn't use it anyway

In my understanding, fortify() is intended to be used in the internal of ggplot2 (and it's still useful in that way), but some people find it useful to use it like broom::tidy() before the days where there's no broom. I agree we need to clarify about this.

But none of these functions exist.

They are not functions, but topics, which you can read on ?maps::italy etc. Thanks for finding this...

By the way, as sf is pretty mature now, I think we are going to discourage use of geom_map() in favor of geom_sf() (for this reason, I don't think ggplot2 will have a map vignette because it already exists in sf package). So, I'm curious in what situation you still need geom_map(). Do you have any examples?

[moodymudskipper]

I just never explored geom_sf and didn't realize geom_map was redundant :).

If geom_map is bound to be deprecated some of these remarks lose their relevance obviously.

However I think the larger point remains, it seems to me that it is very intimidating to learn how to plot a simple map (fill a handful of countries or states with colors mapped to a value).

geom_sf() is not an evocative name and learning that sf means "simple features" which can be point, lines or polygons, doesn't make it so obvious that we might want to use it to draw a world map. So I like geom_map() because it's the function name i'd have typed naturally I if didn't know it existed.

I feel that if I have a df <- data.frame(country = c("Russia", "China"), value = 1:2) I should be able to use a one liner to draw the corresponding map and the fact that I couldn't answer the tweet linked above in 30 minutes, despite having worked with maps a bit in the past prompted this issue :).

I would have liked to do something like ggplot(df, aes(region = country, fill = value)) + geom_map(map = "world"), scroll a document to find my prefered projection, and be done.

On stack overflow I find these answers when looking for "plot world map":

https://stackoverflow.com/questions/9805895/mapping-the-world-on-ggplot2 : 5k views, uses fortify() and geom_polygon()
https://stackoverflow.com/questions/11225343/how-to-create-a-world-map-in-r-with-specific-countries-filled-in 20k views, no ggplot answer

[teunbrand]

Ok so since the issue was filed:

• geom_map() has a clearer description
• coord_map() has been superseded, so it doesn't make sense to me to polish the documentation on this as we discourage its use.
• The suggestions about a map vignette are covered in geom_sf()'s examples.

This leaves the map_data(map) description and fortify.map() points, which are covered in #6218 which would then close this issue once merged.