query_open_topo: Query the Open Topo Data API for elevation data

In edwardlavender/flapper: Routines for the Analysis of Passive Acoustic Telemetry Data

Query the Open Topo Data API for elevation data

Description

This function queries the Open Topo Data elevation Application Programming Interface (API) to extract elevation data for inputted coordinates, rasters, or areas.

Usage

query_open_topo(
  x,
  db = "gebco2020",
  interpolation = "bilinear",
  encoding = NULL,
  verbose = TRUE,
  ...
)

Arguments

x	A two-column matrix of coordinates (x, y), an extent object or a raster that defines the coordinates/area for which elevation data are desired. If a matrix is supplied, a query is sent for all pairs of coordinates in this matrix. If an extent object is provided, a query is sent for all cells spanning this area, depending on the specified dimensions (see ...). If a raster is supplied, a query is only sent for non NA cells, which can be more efficient (since areas for which data are not required can be masked prior to function implementation). The coordinate reference system must be latitude/longitude.
db	A character string that defines the database to be queried. Any option supported by Open Topo Data can be inputted, including ASTER ("aster30m"), ETOPO1 ("etopo1"), EU-DEM ("eudem25m"), Mapzen ("mapzen"), NED ("ned10m"), NZ DEM ("nzdem8m"), SRTM ("srtm90m"), EMOD bathymetry ("emod2018") and GEBCO bathymetry ("gebco2020") (see https://www.opentopodata.org for further details).
interpolation	A character ("nearest", "bilinear" or "cubic") that defines the interpolation method that is used to interpolate elevation values to inputted x locations.
encoding	(optional) The character encoding (e.g., UTF-8).
verbose	A logical variable that defines whether or not to print messages to the console to relay function progress.
...	Additional arguments passed to raster if x is an Extent object, such as the resolution.

Details

Open Topo Data is an elevation API. Further information, including on supported datasets, supported numbers of locations (which, at the time of writing, is limited to 100) and other details are provided here: https://www.opentopodata.org/. This function requires the httr and jsonlite packages to query databases.

Value

The function returns elevation (‘z’) values from the specified database as a matrix, if code x is a matrix, or a raster, if code x is a raster or an Extent object. Coordinates/areas without data are returned as NAs.

Author(s)

Edward Lavender

See Also

Open Topo Data (https://www.opentopodata.org/).

Examples

## Not run: 
#### Set up example spatial data with lat/long projection
proj_wgs84 <- sp::CRS(SRS_string = "EPSG:4326")
dat_gebco_wgs84 <- raster::projectRaster(dat_gebco, crs = proj_wgs84)
dat_coast_wgs84 <- sp::spTransform(dat_coast, proj_wgs84)

#### Example (1): Queries with a single set of coordinates
# Define coordinates
x <- dat_gebco_wgs84
x <- matrix(c(-5.616532, 56.50279), ncol = 2)
# Plot area
prettyGraphics::pretty_map(
  add_rasters = list(x = dat_gebco_wgs84),
  add_polys = list(x = dat_coast_wgs84),
  add_points = list(x = x),
  verbose = FALSE
)
# Check depth in area using available data
raster::extract(dat_gebco_wgs84, x)
# Query database
query_open_topo(x = x, db = "gebco2020")

#### Example (2): Use alternative options
# Alternative databases, such as EMOD bathymetry
query_open_topo(x = x, db = "emod2018", verbose = FALSE)
# Set interpolation
query_open_topo(
  x = x, db = "emod2018",
  interpolation = "cubic", verbose = FALSE
)

#### Example (2): Queries with multiple coordinates
# Define a random sample of coordinates
x <- raster::coordinates(dat_gebco_wgs84)
index <- sample(1:nrow(x), 25)
x <- x[index, ]
# Query database
depth <- query_open_topo(x = x, db = "gebco2020")
# Compare to manually extracted values
# ... (some of these are NA because dat_gebco has been masked over land)
depth <- cbind(depth, raster::extract(dat_gebco_wgs84, x))

#### Example (3): Queries using an Extent object
# Note that only 100 locations can be queried at a time
# ... hence the restrictions on the resolution specified here.
x <- raster::extent(dat_coast_wgs84)
depth <- query_open_topo(x = x, nrows = 10, ncols = 10, db = "gebco2020")
prettyGraphics::pretty_map(
  add_rasters = list(x = depth),
  add_polys = list(x = dat_coast_wgs84),
  verbose = FALSE
)

#### Example (4): Queries from a masked raster
# Focus on a small area
ext <- raster::extent(c(-5.709508, -5.648977, 56.48656, 56.50267))
x <- raster::crop(dat_gebco_wgs84, ext)
prettyGraphics::pretty_map(
  add_rasters = list(x = x),
  add_polys = list(x = dat_coast_wgs84),
  verbose = FALSE
)
# Query database
depth <- query_open_topo(x = x, db = "gebco2020")
prettyGraphics::pretty_map(
  add_rasters = list(x = depth),
  add_polys = list(x = dat_coast_wgs84),
  verbose = FALSE
)

## End(Not run)

edwardlavender/flapper documentation built on Jan. 22, 2025, 2:44 p.m.