Merge pull request #174 from inbo/n2khab_data

Use new function locate_n2khab_data() for read functions

NAMESPACE

@@ -7,6 +7,7 @@ export(download_zenodo)
 export(expand_types)
 export(fileman_folders)
 export(fileman_up)
+export(locate_n2khab_data)
 export(md5sum)
 export(n2khab_options)
 export(read_GRTSmh)
@@ -81,6 +82,8 @@ importFrom(purrr,map_lgl)
 importFrom(rlang,.data)
 importFrom(rlang,na_lgl)
 importFrom(rprojroot,find_root)
+importFrom(rprojroot,find_root_file)
+importFrom(rprojroot,has_dir)
 importFrom(rprojroot,is_git_root)
 importFrom(rprojroot,is_rstudio_project)
 importFrom(sf,"st_crs<-")

R/GRTSmh.R

@@ -325,7 +325,7 @@ convert_base4frac_to_dec <-
 #' @importFrom stringr str_c
 read_GRTSmh <-
   function(file = file.path(
-             fileman_up("n2khab_data"),
+             locate_n2khab_data(),
              c(
                "10_raw/GRTSmaster_habitats/GRTSmaster_habitats.tif",
                "20_processed/GRTSmh_brick/GRTSmh_brick.tif"
@@ -460,7 +460,7 @@ read_GRTSmh <-
 #' @export
 read_GRTSmh_base4frac <-
   function(file = file.path(
-             fileman_up("n2khab_data"),
+             locate_n2khab_data(),
              "20_processed/GRTSmh_base4frac/GRTSmh_base4frac.tif"
            )) {
     if (isTRUE(n2khab_using_raster())) {
@@ -618,7 +618,7 @@ read_GRTSmh_base4frac <-
 #' read_sf
 #' st_crs<-
 read_GRTSmh_diffres <-
-  function(dir = file.path(fileman_up("n2khab_data"), "20_processed/GRTSmh_diffres"),
+  function(dir = file.path(locate_n2khab_data(), "20_processed/GRTSmh_diffres"),
            level,
            polygon = FALSE) {
     if (!(level %in% 1:9 & level %% 1 == 0)) {

R/filemanagement.R

@@ -353,6 +353,45 @@ fileman_up <- function(name,
 
 
 
+#' Locate the \code{n2khab_data} directory
+#'
+#' Returns the absolute path of the \code{n2khab_data} directory by searching
+#' upwards in the directory hierarchy (starting in the working directory); the
+#' first hit will be returned.
+#'
+#' If the \code{n2khab_data_path} option (or environment variable
+#' \code{N2KHAB_DATA_PATH}) is set, that value will be returned instead (see
+#' [`n2khab_options()`]).
+#'
+#' See the data management advice in the
+#' vignette on data storage (run \code{vignette("v020_datastorage")})
+#' for more information.
+#'
+#' @md
+#'
+#' @family functions regarding file management for N2KHAB projects
+#'
+#' @examples
+#' \dontrun{
+#' locate_n2khab_data()
+#' }
+#'
+#' @importFrom rprojroot
+#' find_root_file
+#' has_dir
+#'
+#' @export
+locate_n2khab_data <- function() {
+  opt <- n2khab_data_path()
+  if (!is.na(opt)) {
+    return(opt)
+  }
+  find_root_file("n2khab_data", criterion = has_dir("n2khab_data"))
+}
+
+
+
+
 #' Calculate file checksums
 #'
 #' The functions calculate the checksum (digest; hash value) of

R/options.R

@@ -4,29 +4,30 @@
 #' The package can be configured by means of options or environment variables.
 #' These will influence the behaviour of certain functions.
 #' Each option has its sibling environment variable. When both have a value,
-#' the option will be given priority.
+#' the _option_ will be given priority.
 #'
 #' This function queries these options and environment variables, and returns
 #' the resulting state for each of them (not distinguishing between options or
 #' environment variables as the source).
 #'
 #' @details
 #' Options are typically harder to
-#' isolate from the R code that you collaborate on, and share through a
+#' isolate from the R code that you collaborate on and share through a
 #' repository.
 #' This is especially the case when using `renv`: it requires
 #' `.Rprofile` as part of your project in the working directory, which prevents
 #' `.Rprofile` files elsewhere on the system from being used.
 #'
 #' Consequently, it is advised to:
 #'
-#' - use [options()] where this affects behaviour that must be the same across
+#' - use [`options()`] where this affects behaviour that must be the same across
 #' users and machines for reproducibility.
 #' Put these inside your script, or at least in an `.Rprofile` file that is
 #' shared together with the other project files.
 #' Example: which package to use to represent raster objects.
 #' - use environment variables where behaviour must be machine-specific, e.g.
-#' to override the default location of the `n2khab_data` directory.
+#' to override the default location of the `n2khab_data` directory (can also be
+#' needed when using [`reprex::reprex()`]).
 #' For example, you can create an `.Renviron` file in your working directory
 #' and ignore it in distributed version control.
 #' Or you can set the environment variable at a higher level, e.g. in an
@@ -36,7 +37,7 @@
 #' @section Description of options and environment variables:
 #' **option** | **environment variable** | **type**  | **description**
 #' --- | --- | --- | ---
-#' `n2khab_data_path` | `N2KHAB_DATA_PATH` | string | Path of the `n2khab_data` directory
+#' `n2khab_data_path` | `N2KHAB_DATA_PATH` | string | Path of the `n2khab_data` directory. Takes priority over the default locations where reading functions expect this directory.
 #' `n2khab_use_raster` | `N2KHAB_USE_RASTER` | logical | Should the `raster` package be used to return raster objects? The `terra` package is used by default.
 #'
 #' @returns
@@ -96,6 +97,13 @@ n2khab_data_path <- function() {
       dir.exists(opt),
       msg = "Option 'n2khab_data_path' must be an existing directory."
     )
+    assert_that(
+      identical(basename(opt), "n2khab_data"),
+      msg = paste(
+        "Option 'n2khab_data_path' must point to a directory",
+        "named 'n2khab_data'."
+      )
+    )
   }
   opt
 }

R/read_admin_areas.R

@@ -57,7 +57,7 @@
 #' @export
 read_admin_areas <-
   function(file = file.path(
-             fileman_up("n2khab_data"),
+             locate_n2khab_data(),
              c(
                "10_raw/flanders",
                "10_raw/provinces",

R/read_ecoregions.R

@@ -39,7 +39,7 @@
 #' @importFrom rlang .data
 #' @export
 read_ecoregions <-
-  function(file = file.path(fileman_up("n2khab_data"), "10_raw/ecoregions")) {
+  function(file = file.path(locate_n2khab_data(), "10_raw/ecoregions")) {
     suppressWarnings(
       ecoregions <- read_sf(file,
         crs = 31370

R/read_habitatdata.R

@@ -156,7 +156,7 @@
 #'
 read_habitatmap_stdized <-
   function(file = file.path(
-             fileman_up("n2khab_data"),
+             locate_n2khab_data(),
              "20_processed/habitatmap_stdized/habitatmap_stdized.gpkg"
            ),
            version = c(
@@ -354,7 +354,7 @@ read_habitatmap_stdized <-
 #'
 read_watersurfaces_hab <-
   function(file = file.path(
-             fileman_up("n2khab_data"),
+             locate_n2khab_data(),
              "20_processed/watersurfaces_hab/watersurfaces_hab.gpkg"
            ),
            interpreted = FALSE,
@@ -589,12 +589,12 @@ read_watersurfaces <-
     if (missing(file)) {
       if (version != "watersurfaces_v1.0") {
         file <- file.path(
-          fileman_up("n2khab_data"),
+          locate_n2khab_data(),
           "10_raw/watersurfaces/watersurfaces.gpkg"
         )
       } else {
         file <- file.path(
-          fileman_up("n2khab_data"),
+          locate_n2khab_data(),
           "10_raw/watersurfaces/watersurfaces.shp"
         )
       }
@@ -935,7 +935,7 @@ read_watersurfaces <-
 #' starts_with
 #'
 read_habitatmap <-
-  function(file = file.path(fileman_up("n2khab_data"), "10_raw/habitatmap"),
+  function(file = file.path(locate_n2khab_data(), "10_raw/habitatmap"),
            filter_hab = FALSE,
            version = c(
              "habitatmap_2020",
@@ -948,7 +948,7 @@ read_habitatmap <-
     if (filter_hab) {
       # version control: version habitatmap == version habitatmap_stdized
       xxh64sum_habitatmap_stdized_present <- xxh64sum(file.path(
-        fileman_up("n2khab_data"),
+        locate_n2khab_data(),
         "20_processed/habitatmap_stdized/habitatmap_stdized.gpkg"
       ))
 
@@ -1205,7 +1205,7 @@ read_habitatmap <-
 #' relocate
 read_habitatmap_terr <-
   function(file = file.path(
-             fileman_up("n2khab_data"),
+             locate_n2khab_data(),
              "20_processed/habitatmap_terr/habitatmap_terr.gpkg"
            ),
            keep_aq_types = TRUE,
@@ -1399,7 +1399,7 @@ read_habitatmap_terr <-
 #' @export
 read_habitatstreams <-
   function(file = file.path(
-             fileman_up("n2khab_data"),
+             locate_n2khab_data(),
              "10_raw/habitatstreams"
            ),
            source_text = FALSE) {
@@ -1599,7 +1599,7 @@ read_habitatstreams <-
 #' @export
 read_habitatsprings <-
   function(file = file.path(
-             fileman_up("n2khab_data"),
+             locate_n2khab_data(),
              "10_raw/habitatsprings/habitatsprings.geojson"
            ),
            filter_hab = FALSE,
@@ -1814,7 +1814,7 @@ read_habitatsprings <-
 #' @export
 read_habitatquarries <-
   function(file = file.path(
-             fileman_up("n2khab_data"),
+             locate_n2khab_data(),
              "10_raw/habitatquarries/habitatquarries.gpkg"
            ),
            filter_hab = FALSE,

R/read_raster_runif.R

@@ -45,7 +45,7 @@
 
 read_raster_runif <-
   function(file = file.path(
-             fileman_up("n2khab_data"),
+             locate_n2khab_data(),
              "10_raw/raster_runif/raster_runif.tif"
            ),
            version = "raster_runif_v1") {

R/read_shallowgroundwater.R

@@ -194,7 +194,7 @@
 #' @export
 read_shallowgroundwater <-
   function(file = file.path(
-             fileman_up("n2khab_data"),
+             locate_n2khab_data(),
              "10_raw/shallowgroundwater/shallowgroundwater.gpkg"
            )) {
     assert_that(file.exists(file))

R/read_soilmap.R

@@ -270,10 +270,10 @@
 #' @export
 read_soilmap <-
   function(file = file.path(
-             fileman_up("n2khab_data"),
+             locate_n2khab_data(),
              "20_processed/soilmap_simple/soilmap_simple.gpkg"
            ),
-           file_raw = file.path(fileman_up("n2khab_data"), "10_raw/soilmap"),
+           file_raw = file.path(locate_n2khab_data(), "10_raw/soilmap"),
            use_processed = TRUE,
            version_processed = "soilmap_simple_v2",
            standardize_coastalplain = FALSE,

R/read_watercourses.R

@@ -101,7 +101,7 @@
 #' read_sf
 read_watercourse_100mseg <-
   function(file = file.path(
-             fileman_up("n2khab_data"),
+             locate_n2khab_data(),
              "20_processed/watercourse_100mseg/watercourse_100mseg.gpkg"
            ),
            element = NULL,