Help for package igr

Title:

Irish Grid Reference Utilities

Version:

1.0.0

Description:

Convert between Irish grid references and Irish Grid coordinates. Irish grid references can also be converted to or from an 'sf' object in any coordinate reference system. Precisions from 1 m to 100 km including 2 km (tetrads) are supported, as are datasets with mixed precision. Conversion to 'sf' polygons is precision-aware.

License:

GPL (≥ 3)

URL:

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

BugReports:

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

Imports:

Suggests:

knitr, maps, rmarkdown, testthat (≥ 3.0.0), tmap, units

VignetteBuilder:

knitr

Config/testthat/edition:

Encoding:

UTF-8

RoxygenNote:

7.3.2

NeedsCompilation:

Packaged:

2025-01-07 17:09:30 UTC; jkenn

Author:

John Kennedy

[aut, cre, cph], Digital Nature [fnd]

Maintainer:

John Kennedy <john@digitalnature.ie>

Repository:

CRAN

Date/Publication:

2025-01-07 17:40:02 UTC

igr: Irish Grid Reference Utilities

Description

Author(s)

Maintainer: John Kennedy john@digitalnature.ie (ORCID) [copyright holder]

Other contributors:

Digital Nature [funder]

Convert Irish Grid coordinates to Irish grid references

Description

ig_to_igr() converts valid Irish Grid (EPSG:29903) coordinates to Irish grid references at the specified precision.

Usage

ig_to_igr(x, digits = 3, precision = NULL, sep = "")

Arguments

x

A matrix containing Irish Grid X and Y coordinates in the first and second columns respectively.

digits

An integer, the number of digits for both easting and northing in the Irish grid references.

0: equivalent to a precision of 100 km.
1: equivalent to a precision of 10 km.
2: equivalent to a precision of 1 km.
3 (the default): equivalent to a precision of 100 m.
4: equivalent to a precision of 10 m.
5: equivalent to a precision of 1 m.

precision

An integer, the precision of the Irish grid references in metres: 1, 10, 100, 1000, 2000, 10000, or 100000. Overrides digits. Use 2000 to produce the tetrad form of Irish grid reference.

sep

A character string to place between the 100 km grid letter, easting, northing, and tetrad.

Details

Either digits or precision must be specified. precision overrides digits.

Value

A character vector of Irish grid references.

Examples

# A matrix of Irish Grid coordinates
m <- matrix(c(0, 412300, 0, 98700, 456000, 0), byrow = TRUE, ncol = 2)

m

# Convert to Irish grid references
ig_to_igr(m)

# Insert a space between the 100 km grid letter, easting, and northing
ig_to_igr(m, sep = " ")

# Convert into Irish grid references with 4 digit easting and northing (10 m precision)
ig_to_igr(m, digits = 4)

# Convert into Irish grid references with 1 km precision (2 digit easting and northing)
ig_to_igr(m, precision = 1000)

# Convert into Irish grid references with 2 km precision (tetrad form)
ig_to_igr(m, precision = 2000)

Check if Irish grid references are valid

Description

igr_is_valid() identifies valid Irish grid references.

Usage

igr_is_valid(x, tetrad = TRUE)

Arguments

x

A character vector of Irish grid references.

tetrad

Permit tetrad form of Irish grid reference?

Details

Valid Irish grid references consist of a letter (other than I) optionally followed by both an easting and northing. The easting and northing must be of the same length of between 1 and 5 digits. There may be whitespace between the letter, easting and northing.

The tetrad form of Irish grid reference consists of a valid 10 km precision Irish grid reference (one letter, one digit easting and one digit northing) followed by a letter (other than O). This refers to a 2 km square within the 10 km square referenced.

Value

A logical vector indicating the validity of each Irish grid reference.

Examples

# A vector of alternating valid and invalid Irish grid references
v <- c("N8090", "D 12 345 88800", "W34", "I30", "W", "A123", "B1234", "", "A12Z", "A12O")

# Check validity of Irish Grid coordinates
igr_is_valid(v)

# Check validity of Irish Grid coordinates, disallowing tetrad form
igr_is_valid(v, tetrad = FALSE)

Convert Irish grid references to Irish Grid coordinates

Description

igr_to_ig() converts Irish grid references into a list of Irish Grid (EPSG:29903) X and Y coordinates. By default the coordinates of the south west corners of each Irish grid reference are calculated. The precision of each Irish grid reference in metres can be returned.

Usage

igr_to_ig(
  x,
  coords = c("x", "y"),
  centroids = FALSE,
  precision = NULL,
  tetrad = TRUE
)

Arguments

x

A character vector of Irish grid references. See igr_is_valid() for a definition of valid Irish grid references.

coords

A character vector of the names of the columns to contain the Irish Grid X and Y coordinates respectively.

centroids

Should the coordinates of the centroids of the Irish grid references be returned (rather than the south west corners)?

precision

The name of the column to contain the precision of each Irish grid reference in metres, if required.

tetrad

Permit tetrad form of Irish grid reference?

Value

A list containing Irish Grid X and Y coordinates and, optionally, the precision in metres of each Irish grid reference. Invalid or missing Irish grid references return NA.

Examples

# A vector of Irish grid references of different precisions
v <- c("N8090", "D1234588800", "W34", "", "D12T")

# Convert south west corners of Irish grid references to Irish Grid coordinates
igr_to_ig(v)

# Convert centroids of Irish grid references to Irish Grid coordinates
igr_to_ig(v, centroids = TRUE)

# Specify column names
igr_to_ig(v, coords = c("e", "n"))

# Also return the precision in metres of each Irish grid reference
igr_to_ig(v, precision = "prec")

Convert a data frame containing Irish grid references into an sf object

Description

st_igr_as_sf() converts a data frame containing Irish grid references into an sf object containing point or polygon features. If points, the south west corners of the grid references are returned. If polygons, squares spanning the full extent of each grid reference are returned, with each square's size depending on the precision of each grid reference. The Irish Grid (EPSG:29903) X and Y coordinates and grid reference precision in metres can also be returned.

Usage

st_igr_as_sf(
  x,
  igrefs = "igr",
  crs = 29903,
  remove = FALSE,
  add_coords = FALSE,
  coords = c("x", "y"),
  centroids = FALSE,
  precision = NULL,
  polygons = FALSE,
  tetrad = TRUE
)

Arguments

x

A data.frame containing a column of valid Irish grid references. It must not have column names specified in coords.

igrefs

The name or index of the character column holding Irish grid references.

crs

A valid EPSG value (numeric), a string accepted by GDAL, or an object of class crs containing the coordinate reference system to be assigned. See sf::st_crs().

remove

Should the column containing the Irish grid references be removed from the result?

add_coords

Should the Irish Grid coordinates with column names specified by coords be included in the result?

coords

A character vector of the names of the columns to contain the Irish Grid X and Y coordinates respectively.

centroids

Should the coordinates of the centroids of the Irish grid references be returned (rather than the south west corners)?

precision

The name of the column to contain the precision of each Irish grid reference in metres, if required.

polygons

If FALSE (the default) the result will contain point features located at the south-west corner of each Irish grid reference. If TRUE the result will contain polygon features spanning the extent of each Irish grid reference.

tetrad

Permit tetrad form of Irish grid reference?

Value

An sf object containing point or polygon features for each Irish grid reference in x.

Examples

# A data.frame containing Irish grid references
x <- data.frame(igr = c("A00", "N8000", "D12T"))

# Convert a data.frame of Irish grid references to an sf object in the
# Irish Grid coordinate reference system
st_igr_as_sf(x, "igr")

# Convert to an sf object in the WGS 84 coordinate reference system
st_igr_as_sf(x, "igr", crs = 4326)

# Include the Irish Grid coordinates and precision in the sf object
st_igr_as_sf(x, "igr", add_coords = TRUE, precision = "prec")

# Convert into polygon features rather than point features
st_igr_as_sf(x, "igr", polygons = TRUE)

Generate Irish grid references from an sf object

Description

st_irishgridrefs() returns the Irish grid references for all features in an sf object of point geometries. Features located outside the Irish Grid (EPSG:29903) extent are returned as NA.

Usage

st_irishgridrefs(x, digits = 3, precision = NULL, sep = "")

Arguments

x

An sf object containing geometries of type POINT.

digits

An integer, the number of digits for both easting and northing in the Irish grid references.

0: equivalent to a precision of 100 km.
1: equivalent to a precision of 10 km.
2: equivalent to a precision of 1 km.
3 (the default): equivalent to a precision of 100 m.
4: equivalent to a precision of 10 m.
5: equivalent to a precision of 1 m.

precision

sep

A character string to place between the 100 km grid letter, easting, northing, and tetrad.

Value

A character vector of Irish grid references.

Examples

# An sf object containing point data
x_sf <- sf::st_as_sf(data.frame(x = c(0, 490000), y = c(400000, 0)),
  crs = 29903,
  coords = c("x", "y")
)

# Convert to Irish grid references
st_irishgridrefs(x_sf)

# Convert into Irish grid references with 4 digit easting and northing (10 m precision)
st_irishgridrefs(x_sf, digits = 4)

# Convert into Irish grid references with 1 km precision (2 digit easting and northing)
st_irishgridrefs(x_sf, precision = 1000)

# Convert into Irish grid references with 2 km precision (tetrad form)
st_irishgridrefs(x_sf, precision = 2000)

# Insert a space between the 100 km grid letter, easting, and northing
st_irishgridrefs(x_sf, sep = " ")

igr: Irish Grid Reference Utilities

Description

Author(s)

See Also

Convert Irish Grid coordinates to Irish grid references

Description

Usage

Arguments

Details

Value

Examples

Check if Irish grid references are valid

Description

Usage

Arguments

Details

Value

Examples

Convert Irish grid references to Irish Grid coordinates

Description

Usage

Arguments

Value

Examples

Convert a data frame containing Irish grid references into an sf object

Description

Usage

Arguments

Value

Examples

Generate Irish grid references from an sf object

Description

Usage

Arguments

Value

Examples