CRAN compliance

- Updated documentation
- Updated package framework
- Package structure and verbose updated

Author: 8Ginette8

DESCRIPTION

@@ -1,10 +1,10 @@
 Package: gbif.range
 Version: 1.6.3
-Title: Tools for GBIF Retrieval and Ecoregion-Based Species Range Mapping
+Title: Species Range Mapping from GBIF Using Ecoregion Constraints
 Depends: R (>= 4.0.0)
 Imports: terra, rgbif, CoordinateCleaner, sf, ClusterR, FNN, geometry,
- cluster, rnaturalearth, mclust, methods, utils, zip, class,
- NMOF
+ cluster, mclust, methods, utils, zip, class, NMOF, stats, tools,
+ graphics, grDevices
 Suggests:
     data.table,
     knitr,
@@ -25,8 +25,9 @@ Description: Provides a workflow to retrieve, filter, and analyze 'GBIF'
  et al. 2007 <doi:10.1641/B570707>), and freshwater (Abell et al. 2008
  <doi:10.1641/B580507>) realms. The 'GBIF' API is accessed via the
  'rgbif' package, and coordinate cleaning uses 'CoordinateCleaner'
- (Zizka et al. 2019 <doi:10.1111/2041-210X.13152>).
-License: GPL (>= 3) | file LICENCE
+ (Zizka et al. 2019 <doi:10.1111/2041-210X.13152>). The 'GBIF' API is
+ described at <https://www.gbif.org/developer/summary>.
+License: GPL (>= 3)
 URL: https://github.com/8Ginette8/gbif.range,
     https://8ginette8.github.io/gbif.range/
 BugReports: https://github.com/8Ginette8/gbif.range/issues

LICENCE

@@ -3,9 +3,12 @@
 S3method(plot,gbifPackedSpatRaster)
 S3method(plot,gbifPackedSpatVector)
 export(check_and_get_ecoreg)
+export(cscl)
 export(cv_range)
 export(ecoreg_list)
 export(evaluate_range)
+export(fig_label)
+export(getGBIF)
 export(get_doi)
 export(get_ecoreg)
 export(get_gbif)
@@ -20,6 +23,7 @@ export(read_ecoreg)
 export(read_range_rds)
 export(species_csvs_to_ranges)
 export(split_gbif_by_species)
+exportClasses(getRange)
 importFrom(ClusterR,KMeans_rcpp)
 importFrom(CoordinateCleaner,cd_ddmm)
 importFrom(CoordinateCleaner,cd_round)

NAMESPACE

@@ -6,7 +6,11 @@
 #' Stores the original arguments used to build a range map and the resulting
 #' spatial output.
 #'
-#' @keywords internal
+#' @return A generator object of reference class \code{"getRange"}, used to
+#' instantiate objects with two fields: \code{init.args} (the original
+#' arguments used to build the range map) and \code{rangeOutput} (the
+#' resulting spatial output).
+#' @export
 getRange <- setRefClass("getRange",
                         fields = list(
                           init.args = "ANY",
@@ -23,8 +27,8 @@ getRange <- setRefClass("getRange",
 #' in the package.
 #'
 #' @param df A data frame containing GBIF occurrence records.
-#' @return An object of class \code{getGBIF}.
-#' @keywords internal
+#' @return An object of class \code{c("getGBIF", "data.frame")}.
+#' @export
 getGBIF <- function(df) {
     if (!is.data.frame(df)) {
         stop("Input must be a data.frame")

R/classes.R

@@ -15,15 +15,17 @@
 #' @param temp_dir Character string giving the temporary directory used for
 #' intermediate convex-hull files.
 #' @param g Optional ecoregion identifier used in status messages.
-#' @keywords internal
+#' @param verbose Logical. Should status messages be printed?
 #' @importFrom terra crds buffer aggregate vect crs
 #' @importFrom sf st_polygon
+#' @noRd
 conv_function <- function (sp_coord,
                            bwp,
                            bipl,
                            bwpo,
                            temp_dir,
-                           g = NULL){
+                           g = NULL,
+                           verbose = TRUE) {
 
   # Preps and convert degrees to meters
   x <- terra::crds(sp_coord)
@@ -55,12 +57,14 @@ conv_function <- function (sp_coord,
     if (all(abs(is.line) == 0)) { 
 
       # Print
-      cat(
-        '\n[ecoreg =',g,nrow(x),
-        'points lying on one line. Using buffer width of ',
-        bwp.bipl.m/1000,
-        'km]\n'
-      )
+      if (isTRUE(verbose)) {
+        message(
+          "[ecoreg = ", g, "] ", nrow(x),
+          " points lying on one line. Using buffer width of ",
+          bwp.bipl.m / 1000,
+          " km"
+        )
+      }
 
       # Buffer
       rtn <- terra::buffer(

R/conv_function.R

@@ -16,6 +16,7 @@
 #' the total number of spatial blocks as \code{nfolds * nblocks}.
 #' @param backpoints Numeric. Number of regularly spaced background points used
 #' as pseudo-absences. Default is \code{10000}.
+#' @param verbose Logical. Should fold progress messages be printed?
 #' @details The function rebuilds the range map \code{nfolds} times. In each
 #' iteration, one fold is reserved for evaluation and the remaining folds are
 #' used for training.
@@ -31,23 +32,26 @@
 #' columns \code{TP}, \code{FA}, \code{TA}, \code{FP}, \code{Precision},
 #' \code{Sensitivity}, \code{Specificity}, and \code{TSS}.
 #' @references
-#' Roberts, D. R., Bahn, V., Ciuti, S., Boyce, M. S., Elith, J., Guillera‐
-#' Arroita, G., ... & Dormann, C. F. (2017). Cross‐validation strategies
+#' Roberts, D. R., Bahn, V., Ciuti, S., Boyce, M. S., Elith, J., Guillera-
+#' Arroita, G., ... & Dormann, C. F. (2017). Cross-validation strategies
 #' for data with temporal, spatial, hierarchical, or phylogenetic structure.
-#' Ecography, 40(8), 913-929.
-#' 
+#' Ecography, 40(8), 913-929. \doi{10.1111/ecog.02881}
+#'
 #' Chauvier, Y., Zimmermann, N. E., Poggiato, G., Bystrova, D., Brun, P.,
 #' & Thuiller, W. (2021). Novel methods to correct for observer and sampling
-#' bias in presence‐only species distribution models. Global Ecology and
-#' Biogeography, 30(11), 2312-2325.
+#' bias in presence-only species distribution models. Global Ecology and
+#' Biogeography, 30(11), 2312-2325. \doi{10.1111/geb.13383}
+#' @seealso \code{\link{get_range}}() to build the range map being evaluated,
+#' and \code{\link{make_blocks}}() for the underlying fold-assignment logic.
 #' @example inst/examples/cv_range_help.R
 #' @importFrom terra ext extract
 #' @export
 cv_range <- function(range_object = NULL,
                      cv = 'random-cv',
                      nfolds = 5,
                      nblocks = 2,
-                     backpoints = 1e4){
+                     backpoints = 1e4,
+                     verbose = TRUE) {
 
   ######################################################
   ### Stop messages
@@ -64,6 +68,7 @@ cv_range <- function(range_object = NULL,
   check_numeric(nfolds, "nfolds")
   check_numeric(nblocks, "nblocks")
   check_numeric(backpoints, "backpoints")
+  check_logical(verbose, "verbose")
 
 
   ######################################################
@@ -132,7 +137,7 @@ cv_range <- function(range_object = NULL,
   # Run nfolds time the get_range function + evaluation
   for (i in 1:nfolds)
   {
-    cat("...fold", i, sep="")
+    if (isTRUE(verbose)) message("...fold", i, appendLF = FALSE)
 
     # Extract all but %nfolds
     xy.fit <- all.xy[!cv.strat %in% i,]
@@ -182,7 +187,7 @@ cv_range <- function(range_object = NULL,
       cv.df[i, "Sensitivity"] + cv.df[i, "Specificity"] - 1
   }
 
-  cat("","\n")
+  if (isTRUE(verbose)) message("")
 
   # Finalize average
   cv.df[nfolds+1, ] <- apply(cv.df[1:nfolds, ], 2, mean, na.rm = TRUE)

R/cv_range.R

@@ -14,4 +14,4 @@
 #' @source Calculated with the \code{gbif.range} package.
 #' @docType data
 #' @name area_data
-NULL
+NULL

R/data.R

@@ -34,14 +34,17 @@
 #' per-species evaluation statistics, and \code{overlay_list}, a list of raster
 #' overlays used for plotting and inspection.
 #' @references
-#' Pinkert, S., Sica, Y. V., Winner, K., & Jetz, W. (2023). The potential of 
-#' ecoregional range maps for boosting taxonomic coverage in ecology and 
-#' conservation. Ecography, 12, e06794.
+#' Pinkert, S., Sica, Y. V., Winner, K., & Jetz, W. (2023). The potential of
+#' ecoregional range maps for boosting taxonomic coverage in ecology and
+#' conservation. Ecography, 12, e06794. \doi{10.1111/ecog.06794}
+#' @seealso \code{\link{get_range}}() to generate the range maps being
+#' evaluated, and \code{\link{cv_range}}() for cross-validation against the
+#' original occurrence data instead of external validation data.
 #' @example inst/examples/evaluate_range_help.R
 #' @importFrom terra rast ext crs project aggregate rasterize crop extend resample values classify ncol nrow plot
 #' @importFrom sf st_read st_as_sf st_union st_drop_geometry st_transform
 #' @importFrom grDevices dev.off pdf
-#' @importFrom graphics legend par
+#' @importFrom graphics legend
 #' @export
 evaluate_range <- function(root_dir = NULL,
                        valData_dir = NULL,
@@ -143,35 +146,33 @@ evaluate_range <- function(root_dir = NULL,
     ))
   }
 
-  cat("-Note-", "\n")
   if (valData_type == "TIFF") {
     f.list.matches <- intersect(f.list.eco, basename(f.list.valRM))
-    cat(
-      sprintf(
-        paste(
-          "%.2f%% (%d) of the species names of ecoregions",
-          "match with names of the validation data files"
-        ),
-        100 * length(f.list.matches) / length(f.list.valRM),
-        length(f.list.matches)
-      )
+    match_msg <- sprintf(
+      paste(
+        "%.2f%% (%d) of the species names of ecoregions",
+        "match with names of the validation data files"
+      ),
+      100 * length(f.list.matches) / length(f.list.valRM),
+      length(f.list.matches)
     )
-
   } else {
     f.list.matches <- intersect(f.list.eco, f.list.valRM)
-    cat(
-      sprintf(
-        paste(
-          "%.2f%% (%d) of the species names of ecoregions",
-          "match with those in the validation data column 'sci_name'"
-        ),
-        100 * length(f.list.matches) / length(f.list.valRM),
-        length(f.list.matches)
-      )
+    match_msg <- sprintf(
+      paste(
+        "%.2f%% (%d) of the species names of ecoregions",
+        "match with those in the validation data column 'sci_name'"
+      ),
+      100 * length(f.list.matches) / length(f.list.valRM),
+      length(f.list.matches)
     )
   }
 
-  cat("------", "\n")
+  if (isTRUE(verbose)) {
+    message("-Note-")
+    message(match_msg)
+    message("------")
+  }
 
   df.eval <- data.frame(
     species = f.list.matches,
@@ -188,7 +189,7 @@ evaluate_range <- function(root_dir = NULL,
 
   # Process each species
   for (i in seq_along(f.list.matches)) {
-    if (verbose) cat(i, " Species: ", f.list.matches[i], "\n")
+    if (isTRUE(verbose)) message(i, " Species: ", f.list.matches[i])
 
     if (is.null(mask)) {
       domain.raster <- NULL
@@ -321,7 +322,7 @@ evaluate_range <- function(root_dir = NULL,
       df.eval$Sen_ecoRM[i] + df.eval$Spec_ecoRM[i] - 1
 
     # Plot the overlay raster
-    if (verbose && print_map) {
+    if (isTRUE(verbose) && print_map) {
 
       if (!dir.exists(file.path(root_dir, "eval_output"))) {
         dir.create(file.path(root_dir, "eval_output"))
@@ -331,11 +332,10 @@ evaluate_range <- function(root_dir = NULL,
       colors <- c("gray", "red", "blue", "purple")
       breaks <- c(-0.5, 0.5, 1.5, 2.5, 3.5)
 
-      pdf(file = file.path(root_dir,"eval_output",
+      grDevices::pdf(file = file.path(root_dir,"eval_output",
         paste0("Evaluation_map_", f.list.matches[i], ".pdf")),
         height = (11 * aspect.r)+3, width = 11
       )
-      par(mfrow = c(1, 1))
       terra::plot(
         overlay.raster,
         col = colors,
@@ -352,7 +352,7 @@ evaluate_range <- function(root_dir = NULL,
       )
 
       # Adding a legend
-      legend("bottomright",
+      graphics::legend("bottomright",
         legend = c(
           "Abs in both (TA)",
           "Pres in ecoRM only (FP)",
@@ -364,22 +364,22 @@ evaluate_range <- function(root_dir = NULL,
         box.col = NA,
         inset = c(0,0.1)
       )
-      dev.off()
+      grDevices::dev.off()
     }
   }
 
-  if (verbose) {
-    cat("Cross-species mean Prec & Sensitivity:",
+  if (isTRUE(verbose)) {
+    message(
+      "Cross-species mean Prec & Sensitivity: ",
       round(
-        mean(rowMeans(df.eval[, c("Prec_ecoRM", "Sen_ecoRM")],na.rm = TRUE)),
-        digits = 2),
-      "\n"
+        mean(rowMeans(df.eval[, c("Prec_ecoRM", "Sen_ecoRM")], na.rm = TRUE)),
+        digits = 2)
     )
   }
 
-  if (print_map) {
-    cat("### Maps have been saved to:",
-      file.path(root_dir, "eval_output"), "###\n")
+  if (isTRUE(verbose) && print_map) {
+    message("### Maps have been saved to: ",
+      file.path(root_dir, "eval_output"), " ###")
   }
 
   output <- list(df_eval = df.eval, overlay_list = overlay.list)

R/evaluate_range.R

@@ -23,4 +23,4 @@
 #' @docType package
 #' @example inst/examples/gbif.range-package_help.R
 #' @keywords package
-"_PACKAGE"
+"_PACKAGE"