Graticule

Michael D. Sumner

2023-09-25

Graticule

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.

Examples

A simple example 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(raster)

library(graticule)

## 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"


## 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)

A polar example

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)

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)

Create the graticule as polygons

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 <- reproj::reproj_xy(coordinates(polargrid), "+proj=longlat +datum=WGS84", source = projection(ice))
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)

Comparison to tools in sp and rgdal

This section kept for historical interest only.

See: https://github.com/hypertidy/graticule/issues/19#issuecomment-1379874409

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.

Notes

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.

Terminology

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.

References

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

Environment

devtools::session_info()
#> ─ Session info ───────────────────────────────────────────────────────────────
#>  setting  value
#>  version  R version 4.3.1 (2023-06-16)
#>  os       Ubuntu 20.04.6 LTS
#>  system   x86_64, linux-gnu
#>  ui       X11
#>  language (EN)
#>  collate  C
#>  ctype    en_AU.UTF-8
#>  tz       Australia/Hobart
#>  date     2023-09-25
#>  pandoc   2.19.2 @ /usr/lib/rstudio-server/bin/quarto/bin/tools/ (via rmarkdown)
#> 
#> ─ Packages ───────────────────────────────────────────────────────────────────
#>  package     * version date (UTC) lib source
#>  bslib         0.4.2   2022-12-16 [4] CRAN (R 4.2.3)
#>  cachem        1.0.7   2023-02-24 [4] CRAN (R 4.2.3)
#>  callr         3.7.3   2022-11-02 [4] CRAN (R 4.2.2)
#>  class         7.3-22  2023-05-03 [6] CRAN (R 4.3.1)
#>  classInt      0.4-9   2023-02-28 [4] CRAN (R 4.2.2)
#>  cli           3.6.1   2023-03-23 [4] CRAN (R 4.2.3)
#>  codetools     0.2-19  2023-02-01 [6] CRAN (R 4.2.2)
#>  crayon        1.5.2   2022-09-29 [4] CRAN (R 4.2.1)
#>  DBI           1.1.3   2022-06-18 [4] CRAN (R 4.2.0)
#>  devtools      2.4.5   2022-10-11 [4] CRAN (R 4.2.3)
#>  digest        0.6.31  2022-12-11 [4] CRAN (R 4.2.2)
#>  dplyr         1.1.2   2023-04-20 [4] CRAN (R 4.2.3)
#>  e1071         1.7-13  2023-02-01 [4] CRAN (R 4.2.2)
#>  ellipsis      0.3.2   2021-04-29 [4] CRAN (R 4.1.0)
#>  evaluate      0.20    2023-01-17 [4] CRAN (R 4.2.2)
#>  fansi         1.0.4   2023-01-22 [4] CRAN (R 4.2.2)
#>  fastmap       1.1.1   2023-02-24 [4] CRAN (R 4.2.3)
#>  fs            1.6.2   2023-04-25 [4] CRAN (R 4.2.3)
#>  generics      0.1.3   2022-07-05 [4] CRAN (R 4.2.1)
#>  geosphere     1.5-18  2022-11-15 [4] CRAN (R 4.2.2)
#>  glue          1.6.2   2022-02-24 [4] CRAN (R 4.1.2)
#>  graticule   * 0.4.0   2023-09-25 [1] local
#>  highr         0.10    2022-12-22 [4] CRAN (R 4.2.2)
#>  htmltools     0.5.5   2023-03-23 [4] CRAN (R 4.2.3)
#>  htmlwidgets   1.6.2   2023-03-17 [4] CRAN (R 4.2.3)
#>  httpuv        1.6.9   2023-02-14 [4] CRAN (R 4.2.3)
#>  jquerylib     0.1.4   2021-04-26 [4] CRAN (R 4.1.0)
#>  jsonlite      1.8.4   2022-12-06 [4] CRAN (R 4.2.2)
#>  KernSmooth    2.23-22 2023-07-10 [6] CRAN (R 4.3.1)
#>  knitr         1.42    2023-01-25 [4] CRAN (R 4.2.2)
#>  later         1.3.0   2021-08-18 [4] CRAN (R 4.1.1)
#>  lattice       0.21-8  2023-04-05 [6] CRAN (R 4.3.0)
#>  lifecycle     1.0.3   2022-10-07 [4] CRAN (R 4.2.1)
#>  magrittr      2.0.3   2022-03-30 [4] CRAN (R 4.1.3)
#>  memoise       2.0.1   2021-11-26 [4] CRAN (R 4.1.2)
#>  mime          0.12    2021-09-28 [4] CRAN (R 4.1.2)
#>  miniUI        0.1.1.1 2018-05-18 [4] CRAN (R 4.1.0)
#>  pillar        1.9.0   2023-03-22 [4] CRAN (R 4.2.3)
#>  pkgbuild      1.4.0   2022-11-27 [4] CRAN (R 4.2.2)
#>  pkgconfig     2.0.3   2019-09-22 [4] CRAN (R 4.1.0)
#>  pkgload       1.3.2   2022-11-16 [4] CRAN (R 4.2.2)
#>  prettyunits   1.1.1   2020-01-24 [4] CRAN (R 4.1.0)
#>  processx      3.8.0   2022-10-26 [4] CRAN (R 4.2.2)
#>  profvis       0.3.7   2020-11-02 [4] CRAN (R 4.2.1)
#>  PROJ          0.4.5   2023-07-15 [3] local
#>  proj4         1.0-12  2022-11-30 [4] CRAN (R 4.2.2)
#>  promises      1.2.0.1 2021-02-11 [4] CRAN (R 4.1.0)
#>  proxy         0.4-27  2022-06-09 [4] CRAN (R 4.2.0)
#>  ps            1.7.3   2023-03-21 [4] CRAN (R 4.2.3)
#>  purrr         1.0.1   2023-01-10 [4] CRAN (R 4.2.2)
#>  R6            2.5.1   2021-08-19 [4] CRAN (R 4.1.1)
#>  raster      * 3.6-23  2023-07-10 [3] local
#>  Rcpp          1.0.10  2023-01-22 [4] CRAN (R 4.2.2)
#>  remotes       2.4.2   2021-11-30 [4] CRAN (R 4.1.2)
#>  reproj        0.5.0   2023-08-21 [4] Github (hypertidy/reproj@266ac05)
#>  rlang         1.1.1   2023-04-28 [4] CRAN (R 4.3.0)
#>  rmarkdown     2.23    2023-07-01 [4] CRAN (R 4.3.0)
#>  rstudioapi    0.14    2022-08-22 [4] CRAN (R 4.2.1)
#>  sass          0.4.5   2023-01-24 [4] CRAN (R 4.2.3)
#>  sessioninfo   1.2.2   2021-12-06 [4] CRAN (R 4.1.2)
#>  sf            1.0-14  2023-07-11 [4] CRAN (R 4.3.1)
#>  shiny         1.7.4   2022-12-15 [4] CRAN (R 4.2.3)
#>  sp          * 2.0-0   2023-06-22 [4] CRAN (R 4.3.0)
#>  stringi       1.7.12  2023-01-11 [4] CRAN (R 4.2.3)
#>  stringr       1.5.0   2022-12-02 [4] CRAN (R 4.2.2)
#>  terra         1.7-46  2023-09-06 [4] CRAN (R 4.3.1)
#>  tibble        3.2.1   2023-03-20 [4] CRAN (R 4.2.3)
#>  tidyselect    1.2.0   2022-10-10 [4] CRAN (R 4.2.2)
#>  units         0.8-1   2022-12-10 [4] CRAN (R 4.2.2)
#>  urlchecker    1.0.1   2021-11-30 [4] CRAN (R 4.1.2)
#>  usethis       2.1.6   2022-05-25 [4] CRAN (R 4.2.0)
#>  utf8          1.2.3   2023-01-31 [4] CRAN (R 4.2.2)
#>  vctrs         0.6.3   2023-06-14 [4] CRAN (R 4.3.0)
#>  xfun          0.39    2023-04-20 [4] CRAN (R 4.2.3)
#>  xtable        1.8-4   2019-04-21 [4] CRAN (R 4.1.0)
#>  yaml          2.3.7   2023-01-23 [4] CRAN (R 4.2.2)
#> 
#>  [1] /perm_storage/home/data/r_tmp/Rtmp2t0Efw/Rinstc8bcb67193a70
#>  [2] /perm_storage/home/data/r_tmp/RtmpZHx90m/temp_libpathc804464bc4707
#>  [3] /perm_storage/home/mdsumner/R/x86_64-pc-linux-gnu-library/4.3
#>  [4] /usr/local/lib/R/site-library
#>  [5] /usr/lib/R/site-library
#>  [6] /usr/lib/R/library
#> 
#> ──────────────────────────────────────────────────────────────────────────────