Maps Draft Guidance

This repo contains draft guidance on producing maps using R and sgplot. See ScotGovAnalysis/sgplot#57 for more detail.

In addition to the guidance document (maps.Rmd), the repo also contains: a copy of Local Authority shape files in the shape-files folder; two proposed sgplot functions; and a script to pre-compile the guidance.

These materials were prepared in April 2025, with a view to receiving feedback from the GISAT team in Data Division, however this hasn't been possible. Text in red indicate rough notes and outstanding queries.

Functions

In the functions folder:

• map_theme_sg.R: An alternative to sgplot::theme_sg() for maps.

• os_copyright.R: A function to generate the required copyright wording (including OS licence number) for inclusion in published maps.

Pre-compiling

The guidance uses shape files for Local Authorities sourced from the Improvement Service. However, these files wouldn't be available within the sgplot package, meaning the guidance article couldn't be compiled by the pkgdown GitHub Action.

An alternative method is to pre-compute the guidance article in an environment where the shape files are available. This approach is described in this ROpenSci blog.

The pre-compile.R script manages this process. In short:

• The guidance document / vignette is stored with file extension .Rmd.orig. This is the file that should be edited.

• If the shape files exist, this .Rmd.orig file is knitted to an .Rmd file. This version of the file has all R code chunks pre-run. Maps produced using the shape files are sourced from file.

• The .Rmd file can then be used to build the pkgdown site as it no longer depends on the shape files.

• An additional step fixes an issue with URL encoding. After using pkgdown to build the article, the resulting HTML contains %2F characters in file paths for figures, rather than forward slashes (/). This causes the figures not to render when viewed in a browser. The additional code replaces all %2F characters with /.