knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.path = "README-" )

Graticules are the longitude latitude lines shown on a projected map, and defining and drawing these lines is not easy to automate. The graticule package provides the tools to create and draw these lines by explicit specification by the user. This provides a good compromise between high-level automation and the flexibility to drive the low level details as needed, using base graphics in R.

Please note that this is an evolving topic, across a number of packages in R. There's no ongoing integration of how best to do this, and some of the commentary in this vignette will be out of date quickly as individual packages do updates. I've recorded the exact versions used for this document at the end.

This is an area that needs much more discussion and outlining of needs and experiences.

A simple example uses data from rworldmap to build a map around the state of Victoria in Australia. Victoria uses a local Lambert Conformal Conic projection that was introduced while the shift to GDA94 was implemented, to reduce complications due to working with more than one UTM zone for the state.

library(rgdal) library(raster) library(rworldmap) data(countriesLow) llproj <- projection(countriesLow) library(graticule) map<- subset(countriesLow, SOVEREIGNT == "Australia") ## VicGrid prj <- "+proj=lcc +lat_1=-36 +lat_2=-38 +lat_0=-37 +lon_0=145 +x_0=2500000 +y_0=2500000 +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs" pmap <- spTransform(map, CRS(prj)) ## specify exactly where we want meridians and parallels lons <- seq(140, 150, length = 5) lats <- seq(-40, -35, length = 6) ## optionally, specify the extents of the meridians and parallels ## here we push them out a little on each side xl <- range(lons) + c(-0.4, 0.4) yl <- range(lats) + c(-0.4, 0.4) ## build the lines with our precise locations and ranges grat <- graticule(lons, lats, proj = prj, xlim = xl, ylim = yl) ## build the labels, here they sit exactly on the western and northern extent ## of our line ranges labs <- graticule_labels(lons, lats, xline = min(xl), yline = max(yl), proj = prj) ## set up a map extent and plot op <- par(mar = rep(0, 4)) plot(extent(grat) + c(4, 2) * 1e5, asp = 1, type = "n", axes = FALSE, xlab = "", ylab = "") plot(pmap, add = TRUE) ## the lines are a SpatialLinesDataFrame plot(grat, add = TRUE, lty = 5, col = rgb(0, 0, 0, 0.8)) ## the labels are a SpatialPointsDataFrame, and islon tells us which kind text(subset(labs, labs$islon), lab = parse(text = labs$lab[labs$islon]), pos = 3) text(subset(labs, !labs$islon), lab = parse(text = labs$lab[!labs$islon]), pos = 2) par(op)

Download some sea ice concentration data and plot with a graticule. These passive microwave data are defined on a Polar Stereographic grid on the Hughes ellipsoid (predating WGS84), and there are daily files available since 1978. This is not the prettiest map, but the example is showing how we have control over exactly where the lines are created. We can build the lines anywhere, not necessarily at regular intervals or rounded numbers, and we can over or under extend the parallels relative to the meridians and vice versa.

library(raster) library(graticule) library(rgdal) tfile <- system.file("extdata", "nt_20140320_f17_v01_s.bin", package = "graticule") ice <- raster(tfile) meridians <- seq(-180, 160, by = 20) parallels <- c(-80, -73.77, -68, -55, -45) mlim <- c(-180, 180) plim <- c(-88, -50) grat <- graticule(lons = meridians, lats = parallels, xlim = mlim, ylim = plim, proj = projection(ice)) labs <- graticule_labels(meridians, parallels, xline = -45, yline = -60, proj = projection(ice)) plot(ice, axes = FALSE) plot(grat, add = TRUE, lty = 3) text(labs, lab = parse(text= labs$lab), col= c("firebrick", "darkblue")[labs$islon + 1], cex = 0.85) title(sprintf("Sea ice concentration %s", gsub(".bin", "", basename(tfile))), cex.main = 0.8) title(sub = projection(ice), cex.sub = 0.6)

Continuing from the sea ice example, build the graticule grid as actual polygons. Necessarily the `xlim/ylim`

option is ignored since we have not specified sensibly closed polygonal rings where there are under or over laps.

polargrid <- graticule(lons = c(meridians, 180), lats = parallels, proj = projection(ice), tiles = TRUE) centroids <- project(coordinates(polargrid), projection(ice), inv = TRUE) labs <- graticule_labels(meridians, parallels, proj = projection(ice)) #labs <- graticule_labels(as.integer(centroids[,1]), as.integer(centroids[,2]), proj = projection(ice)) #labs <- labs[!duplicated(as.data.frame(labs)), ] ## this needs a fix cols <- sample(colors(), nrow(polargrid)) op <- par(mar = rep(0, 4)) plot(polargrid, col = cols, bg = "black") text(labs[labs$islon, ], lab = parse(text = labs$lab[labs$islon]), col = "white", cex = 0.9, pos = 3) par(op)

The rgdal function `llgridlines()`

will draw a graticule on a map but had a few limitations prior to May 2016 (some of this story is now out of date and has been improved).

- no control over the exact meridian and parallel lines to draw
- the extent of lines is not independent of their perpendicular counterparts
- relies on a projected object with sufficient verticular density.

Many of these limitations can be worked around, especially by leveraging tools in the raster package but it's not particularly elegant. Interestingly `mapGrid`

in oce seems to share some of the same limitations, but I need to explore that more before being sure about the details.

Above we defined longitude and latitude ranges for an area of interest in Australia. We can plot the projected map and put on a `llgridlines`

graticule. (Note that there's a fair region around the main land mass of Australia here, due to Heard Island, Macquarie Island and Lord Howe Island driving the bounds of this map.)

plot(pmap) op <- par(xpd = NA) llgridlines(pmap) par(op)

We cannot easily modify the lines to be only in our local area, since `llgridlines`

overrides our inputs with the bounding box of the overall object.

plot(pmap) lons <- seq(140, 150, length = 5) lats <- seq(-40, -35, length = 6) llgridlines(pmap, easts = lons, norths = lats)

What we can do is crop the object, or create a new one with the overall extents of our region of interest. This is much closer to what I want but still I need to fiddle to get it just right.

op <- par(xpd = NA) ex <- as(extent(range(lons), range(lats)), "SpatialPolygons") projection(ex) <- llproj pex <- spTransform(ex, CRS(projection(pmap))) plot(extent(pex), type = "n", axes = FALSE, xlab = "", ylab = "", asp = 1) plot(pmap, add = TRUE) llgridlines(pex, easts = lons, norths = lats) par(op)

How about the polar example? This is not bad, but the default number of vertices is not sufficient and we don't get a sensible set of meridians.

plot(ice, axes = FALSE) ##llgridlines(ice) does not understand a raster llgridlines(as(ice, "SpatialPoints"))

Try again, we increase the verticular density, but still I can't get a line at -180/180 and 80S.

plot(ice, axes = FALSE) llgridlines(as(ice, "SpatialPoints"), easts = c(-180, -120, -60, 0, 60, 120), norths = c(-80, -70, -60, -50), ndiscr = 50)

(This is pretty good, needs more exploration.)

library(sf) sf_map <- st_as_sf(pmap) g <- st_graticule(sf_map) plot(st_geometry(sf_map)) op <- par(xpd = NA) plot(st_geometry(g), add = TRUE) invisible(lapply(seq_len(nrow(g)), function(i) { if (g$type[i] == "N" && g$x_start[i] - min(g$x_start) < 1000) text(g[i,"x_start"], g[i,"y_start"], labels = parse(text = g[i,"degree_label"]), srt = g$angle_start[i], pos = 2, cex = .7) if (g$type[i] == "E" && g$y_start[i] - min(g$y_start) < 1000) text(g[i,"x_start"], g[i,"y_start"], labels = parse(text = g[i,"degree_label"]), srt = g$angle_start[i] - 90, pos = 1, cex = .7) if (g$type[i] == "N" && g$x_end[i] - max(g$x_end) > -1000) text(g[i,"x_end"], g[i,"y_end"], labels = parse(text = g[i,"degree_label"]), srt = g$angle_end[i], pos = 4, cex = .7) if (g$type[i] == "E" && g$y_end[i] - max(g$y_end) > -1000) text(g[i,"x_end"], g[i,"y_end"], labels = parse(text = g[i,"degree_label"]), srt = g$angle_end[i] - 90, pos = 3, cex = .7) })) par(op)

library(spex) pex <- spex(ice) plot(ice, axes = FALSE) g <- st_graticule(st_as_sf(pex)) plot(st_geometry(g), add = TRUE) op <- par(xpd = NA) invisible(lapply(seq_len(nrow(g)), function(i) { if (g$type[i] == "N" && g$x_start[i] - min(g$x_start) < 1000) text(g[i,"x_start"], g[i,"y_start"], labels = parse(text = g[i,"degree_label"]), srt = g$angle_start[i], pos = 2, cex = .7) if (g$type[i] == "E" && g$y_start[i] - min(g$y_start) < 1000) text(g[i,"x_start"], g[i,"y_start"], labels = parse(text = g[i,"degree_label"]), srt = g$angle_start[i] - 90, pos = 1, cex = .7) if (g$type[i] == "N" && g$x_end[i] - max(g$x_end) > -1000) text(g[i,"x_end"], g[i,"y_end"], labels = parse(text = g[i,"degree_label"]), srt = g$angle_end[i], pos = 4, cex = .7) if (g$type[i] == "E" && g$y_end[i] - max(g$y_end) > -1000) text(g[i,"x_end"], g[i,"y_end"], labels = parse(text = g[i,"degree_label"]), srt = g$angle_end[i] - 90, pos = 3, cex = .7) })) par(op)

TBD

The oce package has a lot of really neat map projection tools, but it works rather differently from the *Spatial* and *raster* tools in R. We need to drive the creation of the plot from the start with `mapPlot`

, as it sets up the projection metadata for the current plot and handles that for subsequent plotting additions. (My use of oce is inexpert, I'm not across much of the details yet so I may well be off-track with some things here).

Here is our map of Victoria.

library(oce) ## we need to hop the crevasse into another world pp <- raster::geom(map, sepNA = TRUE) mapPlot(pp[,"x"], pp[,"y"], projection = projection(pmap), longitudelim = xl, latitudelim = yl, type = "p", grid = FALSE) mapGrid(longitude = lons, latitude = lats) ## and to prove that all is well in the world plot(pmap, add = TRUE, col = "grey") mapGrid(longitude = lons, latitude = lats)

Here is our polar map, this is good I haven't explore oce enough yet to do it justice.
For bonus points we add `mapTissot()`

, which should be in the basic toolkit of all intrepid R
mappers.

ipts <- coordinates(spTransform(xyFromCell(ice, sample(ncell(ice), 1000), spatial = TRUE), CRS(llproj))) mapPlot(ipts[,1], ipts[,2], projection = projection(ice), type = "n", grid = FALSE) plot(ice, add = TRUE) mapGrid(10, 15) mapTissot()

Also see here for another implementation of the Tissot Indicatrix in R by user whuber on GIS StackExchange. This is available in the dev package tissot.

Efforts could be shared with the sp and rgdal projects to improve the functionality for the `llgridlines`

and its worker functions `gridlines`

and `gridat`

in that central place, and I agree with this. But I have an interest in working with graticules more directly as objects, and potentially stored in relational-table approach built on dplyr, and so I just found it simpler to start from scratch in this package. Also, there is a lot of this functionality spread around the place in sp, raster, maptools, fields, oce and many others. It is time for a new review, analogous to the effort that built sp in ca. 2002.

I tend to use the same terminology as used within Manifold System *because it's so awesome* and that's where I first learnt about most of these concepts. In my experience not many people use the term *graticule* in this way, so take it from the master himself on page 8 (Snyder, 1987):

To identify the location of points on the Earth, a graticule or network of longitude and latitude lines has been superimposed on the surface. They are commonly referred to as meridians and parallels, respectively.

"Verticular density" is kind of a joke, but I like it. YMMV

Snyder, John Parr. Map projections--A working manual. No. 1395. USGPO, 1987.

devtools::session_info()

**Any scripts or data that you put into this service are public.**

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.