On-demand data product downloading

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: ebirdst
 Title: Access and Analyze eBird Status and Trends Data Products
-Version: 4.2023.0
+Version: 4.2023.1
 Authors@R: c(
     person("Matthew", "Strimas-Mackey", , "mes335@cornell.edu", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0001-8929-7776")),

NAMESPACE

@@ -2,25 +2,18 @@
 
 S3method(print,ebirdst_inventory)
 export("%>%")
-export(abundance_palette)
 export(assign_to_grid)
 export(calculate_mcc_f1)
 export(convert_ppy_to_cumulative)
 export(date_to_st_week)
 export(ebirdst_data_dir)
 export(ebirdst_data_inventory)
 export(ebirdst_delete)
-export(ebirdst_download)
 export(ebirdst_download_data_coverage)
 export(ebirdst_download_status)
 export(ebirdst_download_trends)
-export(ebirdst_extent)
-export(ebirdst_habitat)
 export(ebirdst_palettes)
-export(ebirdst_ppms)
-export(ebirdst_ppms_ts)
 export(ebirdst_regional_stats)
-export(ebirdst_subset)
 export(ebirdst_version)
 export(get_species)
 export(get_species_path)
@@ -30,23 +23,14 @@ export(list_available_pis)
 export(load_config)
 export(load_data_coverage)
 export(load_fac_map_parameters)
-export(load_pds)
 export(load_pi)
-export(load_pis)
 export(load_ppm)
-export(load_predictions)
 export(load_ranges)
 export(load_raster)
 export(load_regional_stats)
-export(load_stixels)
 export(load_trends)
-export(parse_raster_dates)
-export(plot_pds)
-export(plot_pis)
-export(project_extent)
 export(rasterize_trends)
 export(set_ebirdst_access_key)
-export(stixelize)
 export(vectorize_trends)
 importFrom(magrittr,"%>%")
 importFrom(rlang,.data)

NEWS.md

@@ -1,3 +1,24 @@
+# ebirdst 4.2023.1
+
+- Removed all functions previously listed as deprecated or defunct
+  (`abundance_palette()`, `ebirdst_download()`, `ebirdst_extent()`,
+  `ebirdst_habitat()`, `ebirdst_ppms()`, `ebirdst_ppms_ts()`,
+  `ebirdst_subset()`, `load_pds()`, `load_pis()`, `load_predictions()`,
+  `load_stixels()`, `parse_raster_dates()`, `plot_pds()`, `plot_pis()`,
+  `project_extent()`, `stixelize()`); they have been unavailable or erroring
+  since at least v3.2022.1
+- Backend approach to file download has been refactored to an on-demand first approach
+- `list_available_pis()` no longer downloads every predictor importance raster to determine availability, only `pi_rangewide.csv`
+- The http fallback for VPNs that block https now also applies to file downloads, not just file listings. The fallback is only attempted when https fails to reach the server at all, never when the server responds, so the access key isn't sent over an unencrypted connection unnecessarily
+- Errors for data that can't be found on-demand now include function-specific guidance, e.g. pointing to `list_available_pis()`
+- Files are now downloaded to a temporary file and only moved into place once the transfer completes. Previously a transfer that was cut short part way left a partial file behind, which was treated as a completed download and never re-downloaded; a forced re-download that failed also deleted the existing local copy of the file
+- Downloads that fail for a reason other than the data not being available, e.g. a dropped connection, now raise an error saying so rather than reporting the data as missing
+- The access key is no longer included in download error messages. The key is passed to the API in the query string of the request URL, and errors from failed downloads quoted that URL, so users reporting a download problem were inadvertently sharing their private key. Download errors now report the reason for the failure with the key redacted
+- `vectorize_trends()` now assigns the smallest circle radius to locations with zero relative abundance; previously these locations were given a missing radius
+- `ebirdst_palettes()` now requires `n` to be a whole number, rather than accepting a value such as `n = 10.5`
+- `ebirdst_regional_stats()` no longer prints a message while downloading
+- Various small bug fixes and typos
+
 # ebirdst 4.2023.0
 
 - Transition to having all the `load_*()` functions download directly rather than having to call `ebirdst_download_status()`

R/access-key.R

@@ -58,10 +58,12 @@ set_ebirdst_access_key <- function(key, overwrite = FALSE) {
   Sys.setenv(EBIRDST_KEY = key)
 
   message("eBird Status and Trends access key stored in: ", renv_path)
-  invisible(renv_path)
+  return(invisible(renv_path))
 }
 
 
+# internal ----
+
 get_ebirdst_access_key <- function() {
   key <- Sys.getenv("EBIRDST_KEY")
   if (is.na(key) || key == "" || nchar(key) == 0) {
@@ -73,8 +75,8 @@ get_ebirdst_access_key <- function() {
     )
     stop(
       "Valid eBird Status and Trends access key not found. ",
-      "Note that keys expire after 6 month, you may need a new key."
+      "Note that keys expire after 6 months, so you may need a new key."
     )
   }
-  invisible(key)
+  return(invisible(key))
 }

R/data.R

@@ -5,11 +5,11 @@
 #' Trends results for each species.
 #'
 #' For the Status Data Products, the dates defining the boundaries of the
-#' seasons are provided in additional to a quality rating from 0-3 for each
+#' seasons are provided in addition to a quality rating from 0-3 for each
 #' season. These dates and quality ratings are assigned through a process of
 #' [expert review](https://science.ebird.org/status-and-trends/faq#seasons).
-#' expert review. Note that missing dates imply that a season failed expert
-#' review for that species within that season.
+#' Note that missing dates imply that a season failed expert review for that
+#' species within that season.
 #'
 #' Trends Data Products are only available for a subset of species, indicated by
 #' the `has_trends` variable, and for each species the trends is estimated for a
@@ -39,16 +39,16 @@
 #' - `is_resident`: classifies this species a resident or a migrant.
 #' - `breeding_quality`: breeding season quality.
 #' - `breeding_start`: breeding season start date.
-#' - `breeding_end`: breeding season start date.
+#' - `breeding_end`: breeding season end date.
 #' - `nonbreeding_quality`: non-breeding season quality.
 #' - `nonbreeding_start`: non-breeding season start date.
-#' - `nonbreeding_end`: non-breeding season start date.
+#' - `nonbreeding_end`: non-breeding season end date.
 #' - `postbreeding_migration_quality`: post-breeding season quality.
 #' - `postbreeding_migration_start`: post-breeding season start date.
-#' - `postbreeding_migration_end`: post-breeding season start date.
+#' - `postbreeding_migration_end`: post-breeding season end date.
 #' - `prebreeding_migration_quality`: pre-breeding season quality.
 #' - `prebreeding_migration_start`: pre-breeding season start date.
-#' - `prebreeding_migration_end`: pre-breeding season start date.
+#' - `prebreeding_migration_end`: pre-breeding season end date.
 #' - `resident_quality`: resident quality.
 #' - `resident_start`: for resident species, the year-round start date.
 #' - `resident_end`: for resident species, the year-round end date.