From 401ac5e253f6ae7d5c460e63e1694002383a65b1 Mon Sep 17 00:00:00 2001 From: "Jeffrey W. Hollister" Date: Fri, 8 Sep 2023 10:23:56 -0400 Subject: [PATCH] documentation updates and drop progress suggests (closes #86) --- DESCRIPTION | 3 +- R/get_elev_point.R | 15 ++++------ R/get_elev_raster.R | 40 ++++++++++++--------------- README.Rmd | 4 +-- man/bbox_to_sf.Rd | 4 +-- man/get_aws_terrain.Rd | 13 ++++----- man/get_elev_point.Rd | 15 ++++------ man/get_elev_raster.Rd | 24 ++++++++-------- man/get_opentopo.Rd | 8 ++---- vignettes/introduction_to_elevatr.Rmd | 11 ++++---- 10 files changed, 61 insertions(+), 76 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 14fbf95..a1221a4 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -44,6 +44,5 @@ Suggests: testthat, knitr, rmarkdown, - formatR, - progress + formatR VignetteBuilder: knitr diff --git a/R/get_elev_point.R b/R/get_elev_point.R index b5a3129..c9abe23 100644 --- a/R/get_elev_point.R +++ b/R/get_elev_point.R @@ -3,9 +3,9 @@ #' This function provides access to point elevations using either the USGS #' Elevation Point Query Service (US Only) or by extracting point elevations #' from the AWS Terrain Tiles. The function accepts a \code{data.frame} of x -#' (long) and y (lat) or a \code{SpatialPoints}/\code{SpatialPointsDataFame} as -#' input. A SpatialPointsDataFrame is returned with elevation as an added -#' \code{data.frame}. +#' (long) and y (lat) or a \code{sf} \code{POINT} or \code{MULTIPOINT} object as +#' input. A \code{sf} \code{POINT} or \code{MULTIPOINT} object is returned with +#' elevation and elevation units as an added \code{data.frame}. #' #' #' @param locations Either a \code{data.frame} with x (e.g. longitude) as the @@ -14,12 +14,9 @@ #' \code{sf} \code{POINT} or \code{MULTIPOINT} object. #' Elevation for these points will be returned in the #' originally supplied class. -#' @param prj A string defining the projection of the locations argument. The -#' string needs to be an acceptable SRS_string for -#' \code{\link[sp]{CRS-class}} for your version of PROJ. If a \code{sf} -#' object, a \code{sp} object or a \code{raster} object -#' is provided, the string will be taken from that. This -#' argument is required for a \code{data.frame} of locations. +#' @param prj A valid input to \code{\link{st_crs}}. This +#' argument is required for a \code{data.frame} of locations and optional +#' for \code{sf} locations. #' @param src A character indicating which API to use, either "epqs" or "aws" #' accepted. The "epqs" source is relatively slow for larger numbers #' of points (e.g. > 500). The "aws" source may be quicker in these diff --git a/R/get_elev_raster.R b/R/get_elev_raster.R index 4a2b97c..6161368 100644 --- a/R/get_elev_raster.R +++ b/R/get_elev_raster.R @@ -1,10 +1,11 @@ #' Get Raster Elevation #' #' Several web services provide access to raster elevation. Currently, this -#' function provides access to the Amazon Web Services Terrian Tiles and the +#' function provides access to the Amazon Web Services Terrain Tiles and the #' Open Topography global datasets API. The function accepts a \code{data.frame} #' of x (long) and y (lat), an \code{sf}, or \code{terra} object as input. A -#' \code{raster} object is returned. +#' \code{RasterLayer} object is returned. In subsequent versions, a \code{SpatRaster} +#' will be returned. #' #' @param locations Either a \code{data.frame} of x (long) and y (lat), an #' \code{sf}, or \code{terra} object as input. @@ -13,11 +14,9 @@ #' details on zoom and resolution see the documentation from Mapzen at #' \url{https://github.com/tilezen/joerd/blob/master/docs/data-sources.md#what-is-the-ground-resolution}. #' The z is not required for the OpenTopography data sources. -#' @param prj A string defining the projection of the locations argument. The -#' string needs to be an acceptable SRS_string for -#' \code{\link[sp]{CRS-class}} for your version of PROJ. If a \code{sf} -#' object, a \code{sp} object or a \code{raster} object -#' is provided, the string will be taken from that. This +#' @param prj A valid input to \code{\link{st_crs}} If a \code{sf} +#' object or a \code{terra} object is provided as the \code{locations}, +#' the prj is optional and will be taken from \code{locations}. This #' argument is required for a \code{data.frame} of locations. #' @param src A character indicating which API to use. Currently supports "aws" #' and "gl3", "gl1", "alos", or "srtm15plus" from the OpenTopography API global @@ -32,7 +31,7 @@ #' The default value is "tile" which returns the full tiles. Other #' options are "bbox" which returns the DEM clipped to the bounding #' box of the original locations (or expanded bounding box if used), -#' or "locations" if the spatials data (e.g. polygons) in the input +#' or "locations" if the spatial data (e.g. polygons) in the input #' locations should be used to clip the DEM. Locations are not used #' to clip input point datasets. Instead the bounding box is used. #' @param verbose Toggles on and off the note about units and coordinate @@ -49,9 +48,10 @@ #' @param ... Extra arguments to pass to \code{httr::GET} via a named vector, #' \code{config}. See #' \code{\link{get_aws_terrain}} for more details. -#' @return Function returns a \code{SpatRaster} in the projection +#' @return Function returns a \code{RasterLayer} in the projection #' specified by the \code{prj} argument or in the projection of the -#' provided locations. +#' provided locations. In subsequent versions, a \code{SpatRaster} +#' will be returned. #' @details Currently, the \code{get_elev_raster} function utilizes the #' Amazon Web Services #' (\url{https://registry.opendata.aws/terrain-tiles/}) terrain @@ -170,12 +170,10 @@ get_elev_raster <- function(locations, z, prj = NULL, #' of the resultant raster is determined by the zoom and latitude. For #' details on zoom and resolution see the documentation from Mapzen at #' \url{https://github.com/tilezen/joerd/blob/master/docs/data-sources.md#what-is-the-ground-resolution} -#' @param prj A string defining the projection of the locations argument. The -#' string needs to be an acceptable SRS_string for -#' \code{\link[sp]{CRS-class}} for your version of PROJ. If a \code{sf} -#' object, a \code{sp} object or a \code{raster} object -#' is provided, the string will be taken from that. This -#' argument is required for a \code{data.frame} of locations. +#' @param prj A valid input to \code{\link{st_crs}} If a \code{sf} +#' object or a \code{terra} object is provided as the \code{locations}, +#' the prj is optional and will be taken from \code{locations}. This +#' argument is required for a \code{data.frame} of locations. #' @param expand A numeric value of a distance, in map units, used to expand the #' bounding box that is used to fetch the terrain tiles. This can #' be used for features that fall close to the edge of a tile and @@ -341,12 +339,10 @@ merge_rasters <- function(raster_list, target_prj, method = "bilinear", returnR #' #' @param locations Either a \code{data.frame} of x (long) and y (lat), an #' \code{sp}, an \code{sf}, or \code{raster} object as input. -#' @param prj A string defining the projection of the locations argument. The -#' string needs to be an acceptable SRS_string for -#' \code{\link[sp]{CRS-class}} for your version of PROJ. If a \code{sf} -#' object, a \code{sp} object or a \code{raster} object -#' is provided, the string will be taken from that. This -#' argument is required for a \code{data.frame} of locations. +#' @param prj A valid input to \code{\link{st_crs}} If a \code{sf} +#' object or a \code{terra} object is provided as the \code{locations}, +#' the prj is optional and will be taken from \code{locations}. This +#' argument is required for a \code{data.frame} of locations. #' @param expand A numeric value of a distance, in map units, used to expand the #' bounding box that is used to fetch the SRTM data. #' @param ... Extra configuration parameters to be passed to httr::GET. Common diff --git a/README.Rmd b/README.Rmd index 6b029c2..324393b 100644 --- a/README.Rmd +++ b/README.Rmd @@ -33,8 +33,6 @@ Version `r version` of this package is currently available from CRAN and may be install.packages("elevatr") ``` -NOTE: As of `r lubridate::today()`, the CRAN version is the older version that does not support `terra`. - The development version (this repo) may installed with `devtools`: ```{r, eval=F} @@ -42,7 +40,7 @@ library(devtools) install_github("jhollist/elevatr") ``` -NOTE: As of `r lubridate::today()`, the development version on GitHub, `r packageVersion("elevatr")`, is the latest version and supports `sf` and `terra`. Support for `sp` and `raster` has been deprecated. +NOTE: As of `r lubridate::today()`, the development version on GitHub, `r packageVersion("elevatr")`, is the latest version and supports `sf` and `terra`. ## Contributions and Use Cases diff --git a/man/bbox_to_sf.Rd b/man/bbox_to_sf.Rd index 4bb7cd1..31eea39 100644 --- a/man/bbox_to_sf.Rd +++ b/man/bbox_to_sf.Rd @@ -8,9 +8,9 @@ sf bbox to poly} bbox_to_sf(bbox, prj = 4326) } \arguments{ -\item{prj}{defaults to "EPSG:4326"} +\item{bbox}{an sf bbox object} -\item{bbx}{an sf bbox object} +\item{prj}{defaults to "EPSG:4326"} } \description{ Assumes geographic projection diff --git a/man/get_aws_terrain.Rd b/man/get_aws_terrain.Rd index a9971fd..668c573 100644 --- a/man/get_aws_terrain.Rd +++ b/man/get_aws_terrain.Rd @@ -21,16 +21,17 @@ get_aws_terrain( ) } \arguments{ +\item{locations}{Either a \code{data.frame} of x (long) and y (lat), an +\code{sp}, \code{sf}, or \code{raster} object as input.} + \item{z}{The zoom level to return. The zoom ranges from 1 to 14. Resolution of the resultant raster is determined by the zoom and latitude. For details on zoom and resolution see the documentation from Mapzen at \url{https://github.com/tilezen/joerd/blob/master/docs/data-sources.md#what-is-the-ground-resolution}} -\item{prj}{A string defining the projection of the locations argument. The -string needs to be an acceptable SRS_string for -\code{\link[sp]{CRS-class}} for your version of PROJ. If a \code{sf} -object, a \code{sp} object or a \code{raster} object -is provided, the string will be taken from that. This +\item{prj}{A valid input to \code{\link{st_crs}} If a \code{sf} +object or a \code{terra} object is provided as the \code{locations}, +the prj is optional and will be taken from \code{locations}. This argument is required for a \code{data.frame} of locations.} \item{expand}{A numeric value of a distance, in map units, used to expand the @@ -48,8 +49,6 @@ usage is to adjust timeout. This is done as \code{config=timeout(x)} where \code{x} is a numeric value in seconds. Multiple configuration functions may be passed as a vector.} - -\item{bbx}{a \code{sf::st_bbox} object that is used to select x,y,z tiles.} } \description{ This function uses the AWS Terrain Tile service to retrieve an elevation diff --git a/man/get_elev_point.Rd b/man/get_elev_point.Rd index 87e09e3..e063b4d 100644 --- a/man/get_elev_point.Rd +++ b/man/get_elev_point.Rd @@ -20,12 +20,9 @@ first column and y (e.g. latitude) as the second column, a Elevation for these points will be returned in the originally supplied class.} -\item{prj}{A string defining the projection of the locations argument. The -string needs to be an acceptable SRS_string for -\code{\link[sp]{CRS-class}} for your version of PROJ. If a \code{sf} -object, a \code{sp} object or a \code{raster} object -is provided, the string will be taken from that. This -argument is required for a \code{data.frame} of locations.} +\item{prj}{A valid input to \code{\link{st_crs}}. This +argument is required for a \code{data.frame} of locations and optional +for \code{sf} locations.} \item{src}{A character indicating which API to use, either "epqs" or "aws" accepted. The "epqs" source is relatively slow for larger numbers @@ -55,9 +52,9 @@ Function returns an \code{sf} object in the projection specified by This function provides access to point elevations using either the USGS Elevation Point Query Service (US Only) or by extracting point elevations from the AWS Terrain Tiles. The function accepts a \code{data.frame} of x -(long) and y (lat) or a \code{SpatialPoints}/\code{SpatialPointsDataFame} as -input. A SpatialPointsDataFrame is returned with elevation as an added -\code{data.frame}. +(long) and y (lat) or a \code{sf} \code{POINT} or \code{MULTIPOINT} object as +input. A \code{sf} \code{POINT} or \code{MULTIPOINT} object is returned with +elevation and elevation units as an added \code{data.frame}. } \examples{ \dontrun{ diff --git a/man/get_elev_raster.Rd b/man/get_elev_raster.Rd index 2922fb2..4bb5289 100644 --- a/man/get_elev_raster.Rd +++ b/man/get_elev_raster.Rd @@ -19,7 +19,7 @@ get_elev_raster( } \arguments{ \item{locations}{Either a \code{data.frame} of x (long) and y (lat), an -\code{sp}, \code{sf}, or \code{raster} object as input.} +\code{sf}, or \code{terra} object as input.} \item{z}{The zoom level to return. The zoom ranges from 1 to 14. Resolution of the resultant raster is determined by the zoom and latitude. For @@ -27,11 +27,9 @@ details on zoom and resolution see the documentation from Mapzen at \url{https://github.com/tilezen/joerd/blob/master/docs/data-sources.md#what-is-the-ground-resolution}. The z is not required for the OpenTopography data sources.} -\item{prj}{A string defining the projection of the locations argument. The -string needs to be an acceptable SRS_string for -\code{\link[sp]{CRS-class}} for your version of PROJ. If a \code{sf} -object, a \code{sp} object or a \code{raster} object -is provided, the string will be taken from that. This +\item{prj}{A valid input to \code{\link{st_crs}} If a \code{sf} +object or a \code{terra} object is provided as the \code{locations}, +the prj is optional and will be taken from \code{locations}. This argument is required for a \code{data.frame} of locations.} \item{src}{A character indicating which API to use. Currently supports "aws" @@ -49,7 +47,7 @@ clip is set to "bbox". Default is NULL.} The default value is "tile" which returns the full tiles. Other options are "bbox" which returns the DEM clipped to the bounding box of the original locations (or expanded bounding box if used), -or "locations" if the spatials data (e.g. polygons) in the input +or "locations" if the spatial data (e.g. polygons) in the input locations should be used to clip the DEM. Locations are not used to clip input point datasets. Instead the bounding box is used.} @@ -72,16 +70,18 @@ can be overriden with this argument set to TRUE.} \code{\link{get_aws_terrain}} for more details.} } \value{ -Function returns a \code{SpatRaster} in the projection +Function returns a \code{RasterLayer} in the projection specified by the \code{prj} argument or in the projection of the - provided locations. + provided locations. In subsequent versions, a \code{SpatRaster} + will be returned. } \description{ Several web services provide access to raster elevation. Currently, this -function provides access to the Amazon Web Services Terrian Tiles and the +function provides access to the Amazon Web Services Terrain Tiles and the Open Topography global datasets API. The function accepts a \code{data.frame} -of x (long) and y (lat), an \code{sp}, or \code{raster} object as input. A -\code{raster} object is returned. +of x (long) and y (lat), an \code{sf}, or \code{terra} object as input. A +\code{RasterLayer} object is returned. In subsequent versions, a \code{SpatRaster} +will be returned. } \details{ Currently, the \code{get_elev_raster} function utilizes the diff --git a/man/get_opentopo.Rd b/man/get_opentopo.Rd index dc83f22..7d97b43 100644 --- a/man/get_opentopo.Rd +++ b/man/get_opentopo.Rd @@ -13,11 +13,9 @@ get_opentopo(locations, src, prj, expand = NULL, ...) \item{locations}{Either a \code{data.frame} of x (long) and y (lat), an \code{sp}, an \code{sf}, or \code{raster} object as input.} -\item{prj}{A string defining the projection of the locations argument. The -string needs to be an acceptable SRS_string for -\code{\link[sp]{CRS-class}} for your version of PROJ. If a \code{sf} -object, a \code{sp} object or a \code{raster} object -is provided, the string will be taken from that. This +\item{prj}{A valid input to \code{\link{st_crs}} If a \code{sf} +object or a \code{terra} object is provided as the \code{locations}, +the prj is optional and will be taken from \code{locations}. This argument is required for a \code{data.frame} of locations.} \item{expand}{A numeric value of a distance, in map units, used to expand the diff --git a/vignettes/introduction_to_elevatr.Rmd b/vignettes/introduction_to_elevatr.Rmd index 72881ea..55e310f 100644 --- a/vignettes/introduction_to_elevatr.Rmd +++ b/vignettes/introduction_to_elevatr.Rmd @@ -39,9 +39,10 @@ knitr::opts_chunk$set(purl = NOT_CRAN, #Sys.setenv(mapzen_key=key) ``` -# Key information about version 1 of `elevatr` +# Key information about version 0.99.0 and upcoming versions of `elevatr` -That stuff goes here. +Several major changes have been made to `elevatr` in response to the retirement of legacy spatial packages (see + for details). Version 0.99.0 has switched to using `sf` and `terra` for all data handling; however, in this version a `raster RasterLayer` is still returned from `get_elev_raster()`. Additional changes are planned for version 1+, most notably the return for `get_elev_raster()` will be a `terra SpatRaster`. Please plan accordingly for your analyses and/or packages account for this change. # Introduction to `elevatr` @@ -79,7 +80,7 @@ examp_df2 <- data.frame(examp_df, cats) examp_sf <- sf::st_as_sf(examp_df2, coords = c("x", "y"), crs = crs_dd) ``` -If a data frame is used it may have additional columns beyond the first two, which must contain the coordinates. The additional columns, along with the returned elevation, will be part of the output SpatialPointsDataFrame. Similarly, an elevation column is added to the data slot of a SpatialPointsDataFrame. +If a data frame is used it may have additional columns beyond the first two, which must contain the coordinates. The additional columns, along with the returned elevation, will be part of the output `POINT` or `MULTIPOINT` `sf` object. Similarly, an elevation and units column is added to the data frame. The USGS Elevation Point Query Service returns a single point at a time. The implementation in `get_elev_point()` will loop through each point, thus can be slow for large number of requests. @@ -132,7 +133,7 @@ everest_aws_elev While point elevations are useful, they will not provide the information required for most elevation based analysis such as hydrologic modeling, viewsheds, etc. To do that requires a raster digital elevation model (DEM). There are several sources for digital elevation models such as the Shuttle Radar Topography Mission (SRTM), the USGS National Elevation Dataset (NED), Global DEM (GDEM), and others. Each of these DEMs has pros and cons for their use. Prior to its closure in January of 2018, Mapzen combined [several of these sources](https://github.com/tilezen/joerd/blob/master/docs/data-sources.md) to create a synthesis elevation product that utilizes the best available elevation data for a given region at given zoom level. Additionally, the elevation data are enhanced with the inclusion of bathymetry in oceans from ETOPO1. Although closed, these data compiled by Mapzen are made available through two separate APIs: the [Nextzen Terrain Tile Service](https://www.nextzen.org#terrain-tiles) and the [Terrain Tiles on Amazon Web Services](https://registry.opendata.aws/terrain-tiles/). Only the Amazon tiles are currently accessible via `elevatr`. -The input for `get_elev_raster()` is a data.frame with x (longitude) and y (latitude) locations as the first two columns, any `sp` object, or any `raster` object and it returns a RasterLayer of the tiles that overlap the bounding box of the input. If multiple tiles are retrieved, the resultant output is a merged Raster Layer. Details for each service and their usage via `get_elev_raster()` are provided below. +The input for `get_elev_raster()` is a data.frame with x (longitude) and y (latitude) locations as the first two columns, any `sp` object, any `sf` object, any `terra` object, or any `raster` object and it returns a `RasterLayer` of the tiles that overlap the bounding box of the input. If multiple tiles are retrieved, the resultant output is a merged `RasterLayer`. Details for each service and their usage via `get_elev_raster()` are provided below. ## Using `get_elev_raster()` to access the Terrain Tiles on AWS. @@ -155,7 +156,7 @@ plot(examp_sf, add = TRUE, col = "black", pch = 19, max.plot = 1) The zoom level determines the resolution of the output raster. More details on resolution and zoom level is still available in the [Mapzen Documentation on ground resolution](https://github.com/tilezen/joerd/blob/master/docs/data-sources.md#what-is-the-ground-resolution). -In addition the the required arguments (`locations`, `z`, and `prj` for data frames), several additional arguments may be passsed to `get_elev_raster()`. First, the `expand` argument is provided to expand the size of the bounding box by a given value in map units. This is useful when bounding box coordinates are near the edge of an xyz tile. For example: +In addition the the required arguments (`locations`, `z`, and `prj` for data frames), several additional arguments may be passed to `get_elev_raster()`. First, the `expand` argument is provided to expand the size of the bounding box by a given value in map units. This is useful when bounding box coordinates are near the edge of an xyz tile. For example: ```{r expand} # Bounding box on edge