Exposed ncpu and set default to 2 or 1 (depending on available cpus). c…

…loses #100

DESCRIPTION

@@ -40,11 +40,11 @@ Imports:
 License: MIT + file LICENSE
 Encoding: UTF-8
 LazyData: true
-RoxygenNote: 7.2.3
 Suggests: 
     testthat,
     knitr,
     rmarkdown,
     formatR,
     progress
 VignetteBuilder: knitr
+RoxygenNote: 7.3.2

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)
 =============

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"){

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
 

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}