igr

An R Package to convert between Irish grid references and Irish Grid coordinates or an sf object

https://github.com/digitalnature-ie/igr

Repository

An R Package to convert between Irish grid references and Irish Grid coordinates or an sf object

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# igr: Irish Grid References in R 


[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
[![CRAN status](https://www.r-pkg.org/badges/version/igr)](https://CRAN.R-project.org/package=igr)
[![R-CMD-check](https://github.com/digitalnature-ie/igr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/digitalnature-ie/igr/actions/workflows/R-CMD-check.yaml)
[![test-coverage](https://github.com/digitalnature-ie/igr/actions/workflows/test-coverage.yaml/badge.svg)](https://github.com/digitalnature-ie/igr/actions/workflows/test-coverage.yaml)
[![Codecov test coverage](https://codecov.io/gh/digitalnature-ie/igr/branch/main/graph/badge.svg)](https://app.codecov.io/gh/digitalnature-ie/igr?branch=main)



Convert between Irish grid references and Irish Grid coordinates, or an sf object in any coordinate reference system.

An Irish grid reference is a way of referring to a square of certain size on the Irish Grid geographic coordinate system ([EPSG:29903](https://epsg.io/29903)). Rather than an X and Y coordinate, an Irish grid reference consists of a letter, optionally followed by an easting, northing and possibly a final letter. The size of the square referred to - the precision of the Irish grid reference - is defined by the number of digits in the easting and northing and presence or absence of a final letter. Spaces are sometimes inserted between letters, easting and northing for legibility.

For example:

* "N" refers to a particular 100 km square ("N" is the square highlighted in orange in the igr logo)
* "N16" refers to a particular 10 km square within "N"
* "N16K" is the tetrad form of grid reference and refers to a particular 2 km square within "N16"
* "N 12345 67890" refers to a particular 1 m square

This package supports Irish grid references of 100 km, 10 km, 2 km, 1 km, 100 m, 10 m, and 1 m precision. Datasets containing a mix of precision are supported.

Irish grid references can be converted to and from Irish Grid coordinates (X and Y), or to and from [sf](https://r-spatial.github.io/sf/) (simple feature) objects in any coordinate reference system.

Irish grid references can be converted to point locations or polygons. Point locations can be either the south-west corner or the centroid of each Irish grid reference. Polygons each span the entire extent of an Irish grid reference - the size of each polygon is precision-aware.

## Installation

To install the production version of igr from CRAN:

``` r
install.packages("igr")
```
To install the development version of igr from GitHub:

``` r
# Install remotes package if needed
install.packages("remotes")

# Install development version of igr package from GitHub
remotes::install_github("digitalnature-ie/igr")
```
## Usage

To check validity of Irish grid references:

* `igr_is_valid()` indicates which elements in a character vector are valid Irish grid references

To convert from Irish grid references:

* `igr_to_ig()` converts from a vector of Irish grid references to a matrix of Irish Grid coordinates
* `st_igr_as_sf()` converts from a data.frame containing Irish grid references to an sf object containing points or polygons

To convert to Irish grid references:

* `ig_to_igr()` converts from a list or matrix of Irish Grid coordinates to Irish grid references
* `st_irishgridrefs()` converts from an sf object to Irish grid references

### Check Irish grid references

```{r example-igr-valid}
library(igr)

# Sample grid references
igrs <- c("A", "A16", "A123678", "BAD", "I12", "", "B125", "Z", "N12D")

igr_is_valid(igrs)
```

### Convert from Irish grid references

```{r example-igr-as-sf}
# Sample grid references
igrs <- c("A", "D12", "J53", "M5090", "N876274", "S1234550000", "R10H", "X")

# Converting south west corners of Irish grid references to Irish Grid coordinates
igr_to_ig(igrs)

# Converting centroids of Irish grid references to Irish Grid coordinates
igr_to_ig(igrs, centroids = TRUE)

# Sample grid references in a data.frame
igrs_df <- data.frame(igr = igrs)

# Converting to an sf object of POINT features
st_igr_as_sf(igrs_df, "igr")

# Converting to an sf object of POINT features in WGS 84 - Longitude and Latitude
st_igr_as_sf(igrs_df, "igr", crs = 4326)
```

```{r example-igr-points, message=FALSE, echo=FALSE, warning=FALSE, fig.alt="A map of Ireland with a dot at the south west corner of each sample grid reference."}
if (requireNamespace("maps", quietly = TRUE) &
  requireNamespace("tmap", quietly = TRUE) &
  requireNamespace("units", quietly = TRUE)) {
  library(maps)
  library(tmap)
  library(units)

  points_sf <- st_igr_as_sf(igrs_df, "igr")

  ie_uk_sf <- maps::map("world",
    regions = c("Ireland", "UK"),
    plot = FALSE,
    fill = TRUE
  ) |>
    sf::st_as_sf(ie_uk) |>
    sf::st_transform(29903)

  tm_shape(points_sf, ext = 1.4) +
    tm_dots(size = 1, fill = "cornflowerblue") +
    tm_text("igr", ymod = 1) +
    tm_shape(ie_uk_sf) +
    tm_borders()
}
```


```{r example-igrt-as-sf-polygons}
# Converting to an sf object of POLYGON features
st_igr_as_sf(igrs_df, "igr", polygon = TRUE)
```

```{r example-igr-polygons, message=FALSE, echo=FALSE, warning=FALSE, fig.alt="A map of Ireland with polygons spanning each sample grid reference. The polygons range in size from 100 km square to 1 m square."}
if (requireNamespace("maps", quietly = TRUE) & requireNamespace("tmap", quietly = TRUE)) {
  polygons_sf <- st_igr_as_sf(igrs_df, "igr", polygons = TRUE)

  # identify small polygons requiring highlighting
  polygons_sf$area <- sf::st_area(polygons_sf)
  small_polygons_sf <- polygons_sf[polygons_sf$area <= units::set_units(5000000, m^2), ]

  tm_shape(ie_uk_sf, bbox = points_sf, ext = 1.4) +
    tm_borders() +
    tm_shape(polygons_sf) +
    tm_polygons(fill = "cornflowerblue", fill_alpha = 0.5) +
    tm_text("igr", ymod = -1) +
    tm_shape(small_polygons_sf) +
    tm_bubbles(
      fill_alpha = 0, col = "orangered", lwd = 2,
      size = 0.8
    )
}
```

### Convert to Irish grid references

```{r example-ig-to-igr}
# Sample Irish Grid coordinates
p <- matrix(c(0, 490000, 400000, 0, 453000, 4000), ncol = 2, byrow = TRUE)
colnames(p) <- c("x", "y")

p

# Convert to Irish grid references
ig_to_igr(p)

# Sample Irish Grid coordinates in an sf object
p_sf <- sf::st_as_sf(data.frame(p), crs = 29903, coords = c("x", "y"))

# Convert sf object to Irish grid references
st_irishgridrefs(p_sf, sep = " ")
```

```{r example-append-igr, eval = FALSE}
# Append Irish grid references to original sf object (using base R)
p_sf$igr <- st_irishgridrefs(p_sf)

# Append Irish grid references to original sf object (using tidy R)
p_sf <- p_sf |>
  dplyr::mutate(igr = st_irishgridrefs(p_sf))
```

# Design and Implementation

This package is designed to work seamlessly in tidy R. Function names, parameter names, and function behaviour attempt to follow conventions in related R packages such as [sf](https://r-spatial.github.io/sf/).

igr is written using base R where possible to minimise package dependencies, and adopts the [tidyverse coding style](https://style.tidyverse.org/). 

[R Packages](https://r-pkgs.org/), 2nd edition, by Hadley Wickham and Jennifer Bryan was of great assistance during package development.

# Feedback 

Please log any unexpected behaviour or suggestions via GitHub [Issues](https://github.com/digitalnature-ie/igr/issues). If you find igr useful or interesting  please consider starring the project on [GitHub](https://github.com/digitalnature-ie/igr).

Owner

GitHub Events

Issues and Pull Requests

Last synced: 10 months ago

Packages