diff --git a/DESCRIPTION b/DESCRIPTION index 38fd32c..5838dc9 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -40,7 +40,6 @@ Imports: License: MIT + file LICENSE Encoding: UTF-8 LazyData: true -RoxygenNote: 7.2.3 Suggests: testthat, knitr, @@ -48,3 +47,4 @@ Suggests: formatR, progress VignetteBuilder: knitr +RoxygenNote: 7.3.2 diff --git a/NEWS.md b/NEWS.md index e8014d0..52f5c23 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,8 +1,8 @@ -elevatr 0.99.0 (2024-0x-xx) +elevatr 1.0.0 (2024-0x-xx) ============= # API Changes - add argument for specifying temp directory for download files. Allows users to specify a specific location. (Thanks, @andrew-caudillo: https://github.com/jhollist/elevatr/issues/95) - +- exposed ncpu argument so user can control. Defaults to 2 if more than 2 cores available. Thanks to @courtiol for finding this issue and the suggestion! elevatr 0.99.0 (2023-09-11) ============= diff --git a/R/get_elev_point.R b/R/get_elev_point.R index 3e6da20..f2fb56b 100644 --- a/R/get_elev_point.R +++ b/R/get_elev_point.R @@ -22,7 +22,9 @@ #' of points (e.g. > 500). The "aws" source may be quicker in these #' cases provided the points are in a similar geographic area. The #' "aws" source downloads a DEM using \code{get_elev_raster} and then -#' extracts the elevation for each point. +#' extracts the elevation for each point. +#' @param ncpu Number of CPU's to use when downloading aws tiles. Defaults to 2 +#' if more than two available, 1 otherwise. #' @param overwrite A logical indicating that existing \code{elevation} and #' \code{elev_units} columns should be overwritten. Default is #' FALSE and \code{get_elev_point} will error if these columns @@ -73,7 +75,8 @@ #' mts_elev #' } #' -get_elev_point <- function(locations, prj = NULL, src = c("epqs", "aws"), +get_elev_point <- function(locations, prj = NULL, src = c("epqs", "aws"), + ncpu = ifelse(future::availableCores() > 2, 2, 1), overwrite = FALSE, ...){ # First Check for internet @@ -98,13 +101,13 @@ get_elev_point <- function(locations, prj = NULL, src = c("epqs", "aws"), # Pass of reprojected to epqs or aws to get data as spatialpointsdataframe if (src == "epqs"){ - locations_prj <- get_epqs(locations, ...) + locations_prj <- get_epqs(locations, ncpu = ncpu, ...) units <- locations_prj[[2]] locations_prj <- locations_prj[[1]] } if(src == "aws"){ - locations_prj <- get_aws_points(locations, verbose = FALSE, ...) + locations_prj <- get_aws_points(locations, ncpu = ncpu, verbose = FALSE, ...) units <- locations_prj[[2]] locations_prj <- locations_prj[[1]] } @@ -149,6 +152,8 @@ get_elev_point <- function(locations, prj = NULL, src = c("epqs", "aws"), #' the second column is Latitude. #' @param units Character string of either meters or feet. Conversions for #' 'epqs' are handled by the API itself. +#' @param ncpu Number of CPU's to use when downloading aws tiles. Defaults to 2 +#' if more than two available, 1 otherwise. #' @param ncpu Number of CPU's to use when downloading epqs data. #' @param serial Logical to determine if API should be hit in serial or in #' parallel. TRUE will use purrr, FALSE will use furrr. @@ -159,7 +164,7 @@ get_elev_point <- function(locations, prj = NULL, src = c("epqs", "aws"), #' @importFrom purrr map_dbl #' @keywords internal get_epqs <- function(locations, units = c("meters","feet"), - ncpu = future::availableCores() - 1, + ncpu = ifelse(future::availableCores() > 2, 2, 1), serial = NULL){ ll_prj <- "EPSG:4326" @@ -310,16 +315,19 @@ get_epqs <- function(locations, units = c("meters","feet"), #' @param units Character string of either meters or feet. Conversions for #' 'aws' are handled in R as the AWS terrain tiles are served in #' meters. +#' @param ncpu Number of CPU's to use when downloading aws tiles. Defaults to 2 +#' if more than two available, 1 otherwise. #' @param verbose Report back messages. #' @param ... Arguments to be passed to \code{get_elev_raster} #' @return a list with a SpatialPointsDataFrame or sf POINT or MULTIPOINT object with #' elevation added to the data slot and a character of the elevation units #' @export #' @keywords internal -get_aws_points <- function(locations, z = 5, units = c("meters", "feet"), +get_aws_points <- function(locations, z = 5, units = c("meters", "feet"), + ncpu = ifelse(future::availableCores() > 2, 2, 1), verbose = TRUE, ...){ units <- match.arg(units) - dem <- get_elev_raster(locations, z, verbose = verbose, ...) + dem <- get_elev_raster(locations, z, ncpu = ncpu, verbose = verbose, ...) dem <- methods::as(dem, "SpatRaster") elevation <- units::set_units(terra::extract(dem, locations)[,2], "m") if(units == "feet"){ diff --git a/R/get_elev_raster.R b/R/get_elev_raster.R index 2ae7ca4..eef4275 100644 --- a/R/get_elev_raster.R +++ b/R/get_elev_raster.R @@ -48,7 +48,9 @@ #' @param tmp_dir The location to store downloaded raster files. Defaults to a #' temporary location. Alternatively, the user may supply an #' existing path for these raster files. New folders are not -#' created by \code{get_elev_raster}. +#' created by \code{get_elev_raster}. +#' @param ncpu Number of CPU's to use when downloading aws tiles. Defaults to 2 +#' if more than two available, 1 otherwise. #' @param ... Extra arguments to pass to \code{httr::GET} via a named vector, #' \code{config}. See #' \code{\link{get_aws_terrain}} for more details. @@ -89,7 +91,9 @@ get_elev_raster <- function(locations, z, prj = NULL, src = c("aws", "gl3", "gl1", "alos", "srtm15plus"), expand = NULL, clip = c("tile", "bbox", "locations"), verbose = TRUE, neg_to_na = FALSE, - override_size_check = FALSE, tmp_dir = tempdir(), ...){ + override_size_check = FALSE, tmp_dir = tempdir(), + ncpu = ifelse(future::availableCores() > 2, 2, 1), + ...){ # First Check for internet if(!curl::has_internet()) { message("Please connect to the internet and try again.") @@ -130,7 +134,7 @@ get_elev_raster <- function(locations, z, prj = NULL, # Pass of locations to APIs to get data as raster if(src == "aws") { raster_elev <- get_aws_terrain(locations, z, prj = prj, expand = expand, - tmp_dir = tmp_dir, ...) + tmp_dir = tmp_dir, ncpu = ncpu, ...) } else if(src %in% c("gl3", "gl1", "alos", "srtm15plus")){ raster_elev <- get_opentopo(locations, src, prj = prj, expand = expand, tmp_dir = tmp_dir, ...) @@ -185,7 +189,8 @@ get_elev_raster <- function(locations, z, prj = NULL, #' 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 #' additional area around the feature is desired. Default is NULL. -#' @param ncpu Number of CPU's to use when downloading aws tiles. +#' @param ncpu Number of CPU's to use when downloading aws tiles. Defaults to 2 +#' if more than two available, 1 otherwise. #' @param serial Logical to determine if API should be hit in serial or in #' parallel. TRUE will use purrr, FALSE will use furrr. #' @param tmp_dir The location to store downloaded raster files. Defaults to a @@ -202,7 +207,7 @@ get_elev_raster <- function(locations, z, prj = NULL, #' @keywords internal get_aws_terrain <- function(locations, z, prj, expand=NULL, - ncpu = future::availableCores() - 1, + ncpu = ifelse(future::availableCores() > 2, 2, 1), serial = NULL, tmp_dir = tempdir(), ...){ # Expand (if needed) and re-project bbx to dd diff --git a/man/get_aws_points.Rd b/man/get_aws_points.Rd index 601587c..2e8061c 100644 --- a/man/get_aws_points.Rd +++ b/man/get_aws_points.Rd @@ -8,6 +8,7 @@ get_aws_points( locations, z = 5, units = c("meters", "feet"), + ncpu = ifelse(future::availableCores() > 2, 2, 1), verbose = TRUE, ... ) @@ -30,6 +31,9 @@ default value is 5 is supplied.} 'aws' are handled in R as the AWS terrain tiles are served in meters.} +\item{ncpu}{Number of CPU's to use when downloading aws tiles. Defaults to 2 +if more than two available, 1 otherwise.} + \item{verbose}{Report back messages.} \item{...}{Arguments to be passed to \code{get_elev_raster}} diff --git a/man/get_aws_terrain.Rd b/man/get_aws_terrain.Rd index fc8e004..3bb8dc2 100644 --- a/man/get_aws_terrain.Rd +++ b/man/get_aws_terrain.Rd @@ -15,7 +15,7 @@ get_aws_terrain( z, prj, expand = NULL, - ncpu = future::availableCores() - 1, + ncpu = ifelse(future::availableCores() > 2, 2, 1), serial = NULL, tmp_dir = tempdir(), ... @@ -40,7 +40,8 @@ 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 additional area around the feature is desired. Default is NULL.} -\item{ncpu}{Number of CPU's to use when downloading aws tiles.} +\item{ncpu}{Number of CPU's to use when downloading aws tiles. Defaults to 2 +if more than two available, 1 otherwise.} \item{serial}{Logical to determine if API should be hit in serial or in parallel. TRUE will use purrr, FALSE will use furrr.} diff --git a/man/get_elev_point.Rd b/man/get_elev_point.Rd index e063b4d..fa5dc89 100644 --- a/man/get_elev_point.Rd +++ b/man/get_elev_point.Rd @@ -8,6 +8,7 @@ get_elev_point( locations, prj = NULL, src = c("epqs", "aws"), + ncpu = ifelse(future::availableCores() > 2, 2, 1), overwrite = FALSE, ... ) @@ -31,6 +32,9 @@ cases provided the points are in a similar geographic area. The "aws" source downloads a DEM using \code{get_elev_raster} and then extracts the elevation for each point.} +\item{ncpu}{Number of CPU's to use when downloading aws tiles. Defaults to 2 +if more than two available, 1 otherwise.} + \item{overwrite}{A logical indicating that existing \code{elevation} and \code{elev_units} columns should be overwritten. Default is FALSE and \code{get_elev_point} will error if these columns diff --git a/man/get_elev_raster.Rd b/man/get_elev_raster.Rd index 7d69cd0..85fec22 100644 --- a/man/get_elev_raster.Rd +++ b/man/get_elev_raster.Rd @@ -15,6 +15,7 @@ get_elev_raster( neg_to_na = FALSE, override_size_check = FALSE, tmp_dir = tempdir(), + ncpu = ifelse(future::availableCores() > 2, 2, 1), ... ) } @@ -71,6 +72,9 @@ temporary location. Alternatively, the user may supply an existing path for these raster files. New folders are not created by \code{get_elev_raster}.} +\item{ncpu}{Number of CPU's to use when downloading aws tiles. Defaults to 2 +if more than two available, 1 otherwise.} + \item{...}{Extra arguments to pass to \code{httr::GET} via a named vector, \code{config}. See \code{\link{get_aws_terrain}} for more details.} diff --git a/man/get_epqs.Rd b/man/get_epqs.Rd index a1f9a22..580a173 100644 --- a/man/get_epqs.Rd +++ b/man/get_epqs.Rd @@ -7,7 +7,7 @@ get_epqs( locations, units = c("meters", "feet"), - ncpu = future::availableCores() - 1, + ncpu = ifelse(future::availableCores() > 2, 2, 1), serial = NULL ) } diff --git a/vignettes/introduction_to_elevatr.Rmd b/vignettes/introduction_to_elevatr.Rmd index 55e310f..02abe09 100644 --- a/vignettes/introduction_to_elevatr.Rmd +++ b/vignettes/introduction_to_elevatr.Rmd @@ -1,12 +1,8 @@ --- -title: "Accessing elevation data in R with the elevatr package, version 1" +title: "Introduction to elevatr" author: "Jeffrey W. Hollister" date: '`r Sys.Date()`' -output: - html_document: - theme: readable - toc: yes - toc_float: yes +output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Introduction to elevatr} %\VignetteEncoding{UTF-8}