-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathquery_open_topo.Rd
116 lines (105 loc) · 5.16 KB
/
query_open_topo.Rd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/queries.R
\name{query_open_topo}
\alias{query_open_topo}
\title{Query the Open Topo Data API for elevation data}
\usage{
query_open_topo(
x,
db = "gebco2020",
interpolation = "bilinear",
encoding = NULL,
verbose = TRUE,
...
)
}
\arguments{
\item{x}{A two-column matrix of coordinates (x, y), an \code{\link[raster]{extent}} object or a \code{\link[raster]{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 \code{\link[raster]{extent}} object is provided, a query is sent for all cells spanning this area, depending on the specified dimensions (see \code{...}). If a \code{\link[raster]{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.}
\item{db}{A character string that defines the database to be queried. Any option supported by Open Topo Data can be inputted, including ASTER (\code{"aster30m"}), ETOPO1 (\code{"etopo1"}), EU-DEM (\code{"eudem25m"}), Mapzen (\code{"mapzen"}), NED (\code{"ned10m"}), NZ DEM (\code{"nzdem8m"}), SRTM (\code{"srtm90m"}), EMOD bathymetry (\code{"emod2018"}) and GEBCO bathymetry (\code{"gebco2020"}) (see https://www.opentopodata.org for further details).}
\item{interpolation}{A character (\code{"nearest"}, \code{"bilinear"} or \code{"cubic"}) that defines the interpolation method that is used to interpolate elevation values to inputted \code{x} locations.}
\item{encoding}{(optional) The character encoding (e.g., \code{UTF-8}).}
\item{verbose}{A logical variable that defines whether or not to print messages to the console to relay function progress.}
\item{...}{Additional arguments passed to \code{\link[raster]{raster}} if \code{x} is an \code{\link[raster]{Extent}} object, such as the \code{resolution}.}
}
\value{
The function returns elevation (`z') values from the specified database as a matrix, if code \code{x} is a matrix, or a \code{\link[raster]{raster}}, if code \code{x} is a \code{\link[raster]{raster}} or an \code{\link[raster]{Extent}} object. Coordinates/areas without data are returned as NAs.
}
\description{
This function queries the Open Topo Data elevation Application Programming Interface (API) to extract elevation data for inputted coordinates, rasters, or areas.
}
\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 \code{\link[httr]{httr}} and \code{\link[jsonlite]{jsonlite}} packages to query databases.
}
\examples{
\dontrun{
#### 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
)
}
}
\seealso{
Open Topo Data (https://www.opentopodata.org/).
}
\author{
Edward Lavender
}