Merge branch 'vignette' into 'master'

add vignette

See merge request tess/boundaries!20

.Rbuildignore

@@ -11,3 +11,4 @@
 ^\.github$
 ^codecov\.yml$
 ^CONTRIBUTING\.md$
+^vignettes/.lintr$

.buildlibrary

@@ -1,4 +1,4 @@
-ValidationKey: '2225772'
+ValidationKey: '2407200'
 AutocreateReadme: yes
 AcceptedWarnings:
 - 'Warning: package ''.*'' was built under R version'

.gitignore

@@ -1,4 +1,28 @@
-.Rproj.user
+# History files
 .Rhistory
+.Rapp.history
+
+# Session Data files
 .RData
 .Ruserdata
+# Example code in package build process
+*-Ex.R
+# Output files from R CMD build
+/*.tar.gz
+# Output files from R CMD check
+/*.Rcheck/
+# RStudio files
+.Rproj.user/
+# produced vignettes
+vignettes/*.html
+vignettes/*.pdf
+# OAuth2 token, see https://github.com/hadley/httr/releases/tag/v0.3
+.httr-oauth
+# knitr and R markdown default cache directories
+/*_cache/
+/cache/
+# Temporary files created by R markdown
+*.utf8.md
+*.knit.md
+.Rproj.user
+inst/doc

.pre-commit-config.yaml

@@ -3,7 +3,7 @@
 exclude: '^tests/testthat/_snaps/.*$'
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: 2c9f875913ee60ca25ce70243dc24d5b6415598c  # frozen: v4.6.0
+    rev: cef0300fd0fc4d2a87a85fa2093c6b283ea36f4b  # frozen: v5.0.0
     hooks:
     -   id: check-case-conflict
     -   id: check-json
@@ -15,7 +15,7 @@ repos:
     -   id: mixed-line-ending
 
 -   repo: https://github.com/lorenzwalthert/precommit
-    rev: bae853d82da476eee0e0a57960ee6b741a3b3fb7  # frozen: v0.4.3
+    rev: 3b70240796cdccbe1474b0176560281aaded97e6  # frozen: v0.4.3.9003
     hooks:
     -   id: parsable-R
     -   id: deps-in-desc

CITATION.cff

@@ -2,8 +2,8 @@ cff-version: 1.2.0
 message: If you use this software, please cite it using the metadata from this file.
 type: software
 title: 'boundaries: Planetary Boundary Status based on LPJmL simulations'
-version: 1.1.1
-date-released: '2024-11-25'
+version: 1.2.0
+date-released: '2024-12-03'
 abstract: A systematic approach to quantify the status of the terrestrial planetary
   boundaries based on the Dynamic Global Vegetation Model (DGVM) Lund-Potsdam-Jena
   managed Land (LPJmL) hosted at the Potsdam Institute for Climate Impact Research

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: boundaries
 Title: Planetary Boundary Status based on LPJmL simulations
-Version: 1.1.1
+Version: 1.2.0
 Authors@R: c(
     person("Johanna", "Braun", , "braun@pik-potsdam.de", role = c("aut", "cre"), comment = c(ORCID = "0000-0002-8809-1044")),
     person("Jannes", "Breier", , "jannesbr@pik-potsdam.de", role = c("aut"), comment = c(ORCID = "0000-0002-9055-6904")),
@@ -56,9 +56,12 @@ Suggests:
     ggpubr,
     ggrepel,
     scales,
-    tidyterra
+    tidyterra,
+    knitr,
+    rmarkdown
 Remotes:
     github::stenzelf/biospheremetrics,
     github::yjunechoe/ggtrace
 Config/testthat/edition: 3
-Date: 2024-11-25
+VignetteBuilder: knitr
+Date: 2024-12-03

R/biosphere_status.R

@@ -18,7 +18,7 @@
 #' In this case only NPP is required. list(npp = "/temp/npp.bin.json").
 #'
 #' @param spatial_scale character string indicating spatial resolution
-#' either "grid", "subglobal" or "global"
+#' either "grid", "regional" or "global"
 #'
 #' @param time_span_scenario time span to be used for the scenario run, defined
 #' as character string
@@ -57,7 +57,7 @@
 #' @param biocol_option which biocol values to use for aggregation. options:
 #' netsum, only_above_zero, abs
 #'
-#' @param eurasia logical. If `spatial_scale` = `"subglobal"` merge continents
+#' @param eurasia logical. If `spatial_scale` = `"regional"` merge continents
 #' Europe and Asia to avoid arbitrary biome cut at europe/asia border.
 #' Defaults to `TRUE`
 #'
@@ -83,7 +83,7 @@
 biosphere_status <- function(
   files_scenario,
   files_reference,
-  spatial_scale = "subglobal",
+  spatial_scale = "regional",
   time_span_scenario = as.character(1982:2011),
   time_span_reference = NULL,
   approach = "stenzel2023",
@@ -152,7 +152,7 @@ biosphere_status <- function(
   if (spatial_scale == "grid") {
     control_variable_raw <- abs(biocol$biocol_frac_piref)
 
-  } else if (spatial_scale == "subglobal") {
+  } else if (spatial_scale == "regional") {
 
     # classify biomes
     # Filter out approach and thresholds arguments from ellipsis (thresholds

R/bluewater_status.R

@@ -13,9 +13,9 @@
 #' via [`calc_status()`].
 #'
 #' @param spatial_scale character string indicating spatial resolution
-#' options: "global", "subglobal", "grid";
+#' options: "global", "regional", "grid";
 #' for "grid" the approach "gerten2020" is applicable based on EFR calculations;
-#' for "global"/"subglobal" the share (%) of total global/basin area with
+#' for "global"/"regional" the share (%) of total global/basin area with
 #' deviations is calculated
 #'
 #' @param time_span_scenario time span to use output from the scenario run,
@@ -29,7 +29,7 @@
 #' [Gerten et al. 2020](https://doi.org/10.1038/s41893-019-0465-1)
 #' for spatial_scale = "grid" and
 #' "wang_erlandsson2022" as well as "porkka2024" for
-#' spatial_scale = "global" or "subglobal"
+#' spatial_scale = "global" or "regional"
 #'
 #' @param time_series_avg integer. Number of years to be used for the moving
 #' average calculation. If `NULL`, all years are averaged for one status
@@ -84,7 +84,7 @@ bluewater_status <- function(
     approach,
     c("gerten2020", "wang-erlandsson2022", "porkka2024", "rockstroem2009")
   )
-  spatial_scale <- match.arg(spatial_scale, c("global", "subglobal", "grid"))
+  spatial_scale <- match.arg(spatial_scale, c("global", "regional", "grid"))
 
   # apply defined approach
   if (spatial_scale == "grid") {
@@ -107,7 +107,7 @@ bluewater_status <- function(
       cut_min = cut_min
     )
 
-  } else if (spatial_scale %in% c("subglobal", "global")) {
+  } else if (spatial_scale %in% c("regional", "global")) {
     if (approach %in% c("wang-erlandsson2022", "porkka2024")) {
       control_variable <- calc_water_deviations(
         files_scenario = files_scenario,

R/calc_status.R

@@ -18,7 +18,7 @@
 #' reference run
 #'
 #' @param spatial_scale character string indicating spatial resolution
-#' options: "global", "subglobal", "grid";
+#' options: "global", "regional", "grid";
 #'
 #' @param time_span_scenario time span to be used for the scenario run, defined
 #' as an integer (or character) vector, e.g. `1982:2011` (default)
@@ -34,10 +34,11 @@
 #' series.
 #'
 #' @param approach list of methods to be used for each boundary. If `NULL` the
-#' default approach is used
+#' default approach is used, e.g. list(bluewater = "rockstroem2009")
 #'
 #' @param thresholds list of thresholds to be used for each boundary. If `NULL`
-#' the default thresholds are used
+#' the default thresholds are used,
+#' e.g. list(bluewater = list("pb" = 2700, "highrisk" = 4000, "holocene" = 0))
 #'
 #' @param in_parallel logical, if `TRUE` the function uses parallelization
 #' (default) based on the `future` package (asynchronous execution). If `FALSE`
@@ -94,7 +95,7 @@ calc_status <- function(
   # verify available spatial resolution
   spatial_scale <- match.arg(
     spatial_scale,
-    c("global", "subglobal", "grid")
+    c("global", "regional", "grid")
   )
 
   config_scenario <- lpjmlkit::read_config(config_scenario)

R/calc_water_deviations.R

@@ -34,15 +34,15 @@
 #'
 #' @param thresholds list with thresholds to be used to
 #' define the safe, increasing risk and high risk zone,
-#' For spatial_scale = "global" and "subglobal", this refers to the quantiles of
+#' For spatial_scale = "global" and "regional", this refers to the quantiles of
 #' the global/basin area with deviations in the reference period. The default
 #' is: c(holocene = 50, pb = 95, highrisk = NULL).
 #' If set to NULL, the  default is taken from metric_files.yml
 #' For highrisk, the value is currently hard-coded to 0.5
 #' (following Richardson et al. 2023)
 #'
 #' @param spatial_scale character string indicating spatial scale;
-#' "global" or "subglobal" for calculation of the share (%) of total
+#' "global" or "regional" for calculation of the share (%) of total
 #' global/basin area with deviations (either one value per year
 #' (wang-erlandsson2022) or one value per year and month (porkka2024)); "grid"
 #' not yet defined
@@ -61,7 +61,7 @@
 #' @md
 calc_water_deviations <- function(files_scenario,
                                   files_reference,
-                                  spatial_scale = "subglobal",
+                                  spatial_scale = "regional",
                                   time_span_scenario = NULL,
                                   time_span_reference,
                                   approach = "porkka2024",
@@ -97,10 +97,10 @@ calc_water_deviations <- function(files_scenario,
                           approach = approach)
 
   # -------------------------------------------------------------------------- #
-  # calculate the area with dry/wet departures (subglobal and global resolution)
+  # calculate the area with dry/wet departures (regional and global resolution)
 
-  # get basin information for subglobal resolution
-  if (spatial_scale == "subglobal") {
+  # get basin information for regional resolution
+  if (spatial_scale == "regional") {
     cellinfo <- indexing_drainage(drainage_file = files_scenario$drainage)
     if (!is.null(config_args$spatial_subset)) {
       cellinfo <- lpjmlkit::asub(cellinfo, cell = config_args$spatial_subset)
@@ -197,7 +197,7 @@ calc_water_deviations <- function(files_scenario,
       )
     )
 
-  } else if (spatial_scale == "subglobal") {
+  } else if (spatial_scale == "regional") {
 
     if (approach == "porkka2024") {
       # calculate mean yearly area with transgression for each basin
@@ -360,7 +360,7 @@ calc_departures <- function(
   dry_or_wet <- ifelse((dry == 1 | wet == 1), 1, 0)
 
   control_variable <- list()
-  if (spatial_scale == "subglobal") {
+  if (spatial_scale == "regional") {
     # calculate for each basin and year/month: area with wet/dry departures
     dim_remain <- dim(dry)[names(dim(dry)) != "cell"]
     dimnames_remain <- dimnames(dry)[names(dim(dry)) != "cell"]

R/classify_biomes.R

@@ -93,7 +93,7 @@ classify_biomes <- function(config_reference = NULL, # nolint:cyclocomp_linter
     output_files <- list_outputs(
       "biome",
       approach = list("biome" = approach),
-      spatial_scale = "subglobal",
+      spatial_scale = "regional",
       only_first_filename = FALSE
     )
 

R/greenwater_status.R

@@ -12,7 +12,7 @@
 #' [`calc_status()`].
 #'
 #' @param spatial_scale character string indicating spatial resolution
-#' either "grid", "subglobal" or "global" for calculation of the share (%)
+#' either "grid", "regional" or "global" for calculation of the share (%)
 #' of total global area with deviations
 #'
 #' @param time_span_scenario time span to use output from the scenario run,
@@ -84,7 +84,7 @@ greenwater_status <- function(
   approach <- match.arg(approach, c("wang-erlandsson2022", "porkka2024"))
 
   # verify available spatial resolution
-  spatial_scale <- match.arg(spatial_scale, c("global", "subglobal"))
+  spatial_scale <- match.arg(spatial_scale, c("global", "regional"))
 
   # -------------------------------------------------------------------------- #
   # calc deviations for rootmoisture

R/lsc_status.R

@@ -12,7 +12,7 @@
 #' [`calc_status()`].
 #'
 #' @param spatial_scale character. Spatial resolution, available options
-#' are `"subglobal"` (at the biome level, default), `"global"` and `"grid"`
+#' are `"regional"` (at the biome level, default), `"global"` and `"grid"`
 #'
 #' @param time_span_scenario time span to use output from the scenario run,
 #' e.g. `1982:2011`.
@@ -43,7 +43,7 @@
 #' @param config_args list of arguments to be passed on from the model
 #' configuration.
 #'
-#' @param eurasia logical. If `spatial_scale` = `"subglobal"` merge continents
+#' @param eurasia logical. If `spatial_scale` = `"regional"` merge continents
 #' Europe and Asia to avoid arbitrary biome cut at europe/asia border.
 #' Defaults to `TRUE`
 #'
@@ -69,7 +69,7 @@
 lsc_status <- function(
   files_scenario,
   files_reference,
-  spatial_scale = "subglobal",
+  spatial_scale = "regional",
   time_span_scenario = as.character(1982:2011),
   time_span_reference = time_span_scenario,
   approach = "steffen2015",
@@ -102,7 +102,7 @@ lsc_status <- function(
            ellipsis_filtered)
   )
 
-  if (spatial_scale == "subglobal") {
+  if (spatial_scale == "regional") {
     # please R CMD check for use of future operator
     continent_grid <- NULL
     # get continents mask - pass arg of whether to merge europe and asia
@@ -289,7 +289,7 @@ lsc_status <- function(
   deforestation[!is_forest] <- NA
   deforestation <- deforestation * 100 # in percent
 
-  if (spatial_scale == "subglobal") {
+  if (spatial_scale == "regional") {
 
     # create space of combinations to loop over (even though not all make sense)
     comb <- expand.grid(
@@ -334,7 +334,7 @@ lsc_status <- function(
     }
   }
 
-  if (spatial_scale %in% c("grid", "subglobal")) {
+  if (spatial_scale %in% c("grid", "regional")) {
     # init threshold array with NA = no data and initial dimensions + threshold
     # dimension
 

R/utility_functions.R

@@ -13,7 +13,7 @@
 #'       calculate the metric. Or `"all"` to get all approaches (default).
 #'
 #' @param spatial_scale character. Spatial resolution, available options
-#'        are `"subglobal"` (at the biome level), `"global"` and
+#'        are `"regional"` (at the biome level), `"global"` and
 #'        `"grid"` or `"all"` (default).
 #'
 #' @param only_first_filename Logical. If TRUE, only the first file name will be
@@ -27,7 +27,7 @@
 #' list_outputs(
 #'   "biome",
 #'   approach = list("biome" = approach),
-#'   spatial_scale = "subglobal",
+#'   spatial_scale = "regional",
 #'   only_first_filename = FALSE
 #' )
 #' }