dist2land: Calculate the closest distance to land for given coordinates

In MikkoVihtakari/PlotSvalbard: PlotSvalbard - Plot research data from Svalbard on maps

Calculate the closest distance to land for given coordinates

Description

Calculates the closest distance to land within a map type for a given set of coordinates

Usage

dist2land(
  x,
  lon.col = NULL,
  lat.col = NULL,
  map.type = "panarctic",
  bind = TRUE,
  dist.col = "dist",
  return.binary = FALSE,
  geodesic.distances = FALSE,
  cores = 1
)

Arguments

x	Data.frame containing geographic coordinates as decimal degrees
lon.col	The name of the longitude column in x.
lat.col	The name of the latitude column in x.
map.type	a character string specifying the map type which land boundaries should be used for the distance calculation. See the type argument for possible map types.
bind	Logical indicating whether x should be returned with the distances (TRUE, default) or should the distances be returned as vector (FALSE).
dist.col	The name of the distance column, if bind = TRUE. Defaults to "dist".
return.binary	Logical indicating whether binary (TRUE = the position is in the ocean, FALSE = the position is on land) should be returned instead of distances. Speeds up the function considerably.
geodesic.distances	Logical indicating whether dist2Line function should be used to calculate shortest distances using the WGS84 ellipsoid (TRUE) or whether the distances should be calculated from UTM coordinates (FALSE, default). Setting the argument to TRUE presumably leads to more exact distance estimations, but takes a much longer time to process than the UTM coordinate estimation.
cores	Integer value defining how many cores should be used in the calculations. Parallelization speeds up the function (see mclapply), but naturally eats up computer resources during the calculation. Set to 1 to remove parallelization (default).

Details

If geodesic.distances = FALSE, the function uses the gDistance function to calculate closest distances between coordinates in x and a specified SpatialPolygonsDataframe object. The spatial object (map) can be specified using the map.type argument. If geodesic.distances = TRUE, the dist2Line is used to calculate similar distances assumming an elliptical Earth. The dist2Line function is presumably more exact, especially for pan-Arctic maps, but considerably slower.

The function is very slow for large datasets. If you only want to use the function to remove (wrong) observations reported on land, set the return.binary argument to TRUE. This speeds up the function considerably.

The function has a possibility for parallel processing, which speeds up the calculations for large datasets. The parallel processing has been turned off by default (cores = 1). You can turn it on by setting another integer or a function, which produces such an integer (for example parallel::detectCores() - 2 uses all avaible cores exept two). Parallelizing does not work under Windows.

Value

If bind = TRUE, returns a data frame with calculated distances to land. If bind = FALSE returns vector in the same order than coordinates specified in x. Distances are returned as kilometers. If return_binary = TRUE, binary values are returned instead of distances (TRUE = the position is in the ocean, FALSE = the position is on land).

Author(s)

Mikko Vihtakari

Examples

## Distances from land using UTM coordinates
library(ggplot2)
data("npi_stations")

dists <- dist2land(npi_stations, map.type = "svalbard")
dists$Area <- ordered(dists$Area, c("Kongsfjorden", "Framstrait", "Rijpfjorden"))

ggplot(dists, aes(x = Area, y = dist, label = Station)) +
  geom_text() + ylab("Distance to land (km)")

## Geodesic distances are presumably more exact,
## but much slower to calculate. Do not use detailed
## maps for these:

d_utm <- dist2land(npi_stations,
  map.type = "barentssea", dist.col = "d_utm")
d_geo <- dist2land(npi_stations, map.type = "barentssea",
  geodesic.distances = TRUE, dist.col = "d_geo")

y <- merge(d_utm[c("Station", "d_utm")], d_geo[c("Station", "d_geo")])

ggplot(y, aes(x = d_utm, y = d_geo, label = Station)) +
 geom_text(color = "red") +
 geom_abline(slope=1, intercept=0) +
 scale_x_log10() + scale_y_log10()

## The processing time difference between binary, geodesic and UTM distances:

# Binary:
system.time(dist2land(npi_stations, map.type = "barentssea",
return.binary = TRUE))
#> user  system elapsed
#> 0.017   0.000   0.017

# UTM:
system.time(dist2land(npi_stations, map.type = "barentssea"))
#> user  system elapsed
#> 0.073   0.003   0.073

# Geodesic:
system.time(dist2land(npi_stations, map.type = "barentssea",
geodesic.distances = TRUE))
#> user  system elapsed
#> 14.096   0.615  14.755

## Despite the inaccuracy due to polar stereographic protection
## the UTM version seems to produce feasible distances from land
## on pan-Arctic scale

data("meiofauna")
d_panarctic <- dist2land(meiofauna,  lon.col = "Lon", lat.col = "Lat", map.type = "panarctic")
d_panarctic <- transform_coord(d_panarctic, lon = "Lon", lat = "Lat", map.type = "panarctic",
bind = TRUE)

basemap("panarctic", limits = c("d_panarctic", "lon.utm", "lat.utm")) +
 geom_point(data = d_panarctic, aes(x = lon.utm, y = lat.utm, color = dist), size = 3) +
 scale_color_viridis_c(name = "Distance (km)")

MikkoVihtakari/PlotSvalbard documentation built on July 12, 2022, 10:20 a.m.