last modifications to updated vignettes

marlonecobos · marlonecobos · commit 5743fd11ab71 · 2026-03-06T10:34:48.000-05:00
diff --git a/vignettes/model_predictions.Rmd b/vignettes/model_predictions.Rmd
@@ -30,7 +30,7 @@ knitr::opts_chunk$set(
   - [No extrapolation](#no-extrapolation)
 - [Binarize predictions](#binarize-predictions)
 - [Saving Predictions](#saving-predictions)
-- [Detecting changes between single scenarios](#detecting-changes-between-single-scenarios)
+- [Detecting changes in predictions](#detecting-changes-in-predictions)
 
 <hr>
 
@@ -91,7 +91,7 @@ fitted_model_glm
 
 # Model predictions
 
-To predict selected models for a single scenario, you need a `fitted_models` object and the corresponding predictor variables. These predictor variables can be provided as either a `SpatRaster` or a `data.frame`. The names of the variables (or columns in the `data.frame`) must precisely match those used for model calibration or those used when running PCA (if `do_pca = TRUE` was set in the `prepare_data()` function; see [Prepare Data for Model Calibration](prepare_data.html) for more details).
+To predict selected models for a single scenario, you need a `fitted_models` object and the corresponding variables. These variables can be provided as either a `SpatRaster` or a `data.frame`. The names of the variables (or columns in the `data.frame`) must precisely match those used for model calibration or those used when running PCA (if `do_pca = TRUE` was set in the `prepare_data()` function; see [Prepare Data for Model Calibration](prepare_data.html) for more details).
 
 <br> 
 
@@ -254,7 +254,7 @@ terra::plot(p_raw$General_consensus$mean, main = "Raw", zlim = c(0, 1))
 
 ## Clamping variables
 
-By default, predictions are performed with free extrapolation (`extrapolation_type = "E"`). This can be problematic when the peak of suitability occurs at the extremes of a predictor's range. For example, let's examine the response curve of the Maxnet model for `bio_7` (Temperature Annual Range):
+By default, predictions are performed with free extrapolation (`extrapolation_type = "E"`). This can be problematic when the peak of suitability occurs at the extremes of a variable's range. For example, let's examine the response curve of the Maxnet model for `bio_7` (Temperature Annual Range):
 
 ```{r response bio_7}
 response_curve(models = fitted_model_maxnet, variable = "bio_7", 
@@ -327,7 +327,7 @@ terra::plot(new_bio7, main = "Hypothetical bio_7", type = "interval")
 
 Note that when we clamp the variables, regions with extremely low values of (the hypothetical) `bio_7` exhibit lower predicted suitability values compared to when free extrapolation is allowed.
 
-By default, when `extrapolation_type = "EC"` is set, all predictor variables are clamped. You can specify which variables to clamp using the `var_to_restrict` argument.
+By default, when `extrapolation_type = "EC"` is set, all variables are clamped. You can specify which variables to clamp using the `var_to_restrict` argument.
 
 <br>
 
@@ -357,7 +357,7 @@ terra::plot(new_bio7, main = "Hypothetical bio_7", type = "interval")
 
 In this example, a large portion of the predicted area shows zero suitability. This is because, in this hypothetical scenario, much of the region has `bio_7` values lower than those in the training data, which has a minimum of 15ºC. Suitability values greater than zero are only in areas where `bio_7` falls within the training range.
 
-By default, when `extrapolation_type = "NE"` is set, all predictor variables are considered for this process. You can specify a subset of variables to be considered for extrapolation using the `var_to_restrict` argument.
+By default, when `extrapolation_type = "NE"` is set, all variables are considered for this process. You can specify a subset of variables to be considered for extrapolation using the `var_to_restrict` argument.
 
 <br>
 
@@ -438,38 +438,45 @@ p_save <- predict_selected(models = fitted_model_maxnet,
 Alternatively, we can use `writeRaster()` to save specific output predictions manually. For example, to save only the mean layer from the general consensus results:
 
 ```{r writeRaster, eval = FALSE}
-writeRaster(p_maxnet$General_consensus$mean, 
-            filename = file.path(tempdir(), "Mean_consensus.tif"))
+terra::writeRaster(p_maxnet$General_consensus$mean, 
+                   filename = file.path(tempdir(), "Mean_consensus.tif"))
 ```
 
-# Detecting changes between single scenarios
+<br> 
+
+# Detecting changes in predictions
 
-To compare predictions from two single scenarios representing different time periods (e.g., present vs. future or present vs. past), the function `prediction_changes()` can be used to identify areas of **loss (contraction)**, **gain (expansion)**, and **stability (no change)** in suitable conditions.
+To compare predictions between two single scenarios representing different time periods (e.g., present vs. future or present vs. past), the function `prediction_changes()` can be used. This function helps to identify **loss (contraction)**, **gain (expansion)**, and **stability (no change)** of suitable areas.
 
 As an example, we will project the fitted model to a **single GCM** representing future climatic conditions:
 
 ```{r import var future}
+# Read layers representing future conditions
 future_var <- terra::rast(system.file("extdata",
                                       "wc2.1_10m_bioc_ACCESS-CM2_ssp585_2081-2100.tif",
                                       package = "kuenm2"))
-plot(future_var)
+
+# Plot future layers
+terra::plot(future_var)
 ```
 
-Next, we need to rename the variables so that they match the variable names used when fitting the models:
+<br> 
+
+Next, we need to rename the variables so that they match the variable names used when fitting the models. After that, we will also apappend the static soil variable to the set of future variables.
 
 ```{r}
+# renaming layers to match names of variables used to fit the model
 names(future_var) <- sub("bio0", "bio", names(future_var))
 names(future_var) <- sub("bio", "bio_", names(future_var))
 names(var)
 names(future_var)
-```
 
-We also need to append the static soil variable to the set of future predictors:
-
-```{r}
+# Adding soil layer to future variable set
 future_var <- c(future_var, var$SoilType)
 ```
 
+<br> 
+
 Now we can generate predictions under future environmental conditions:
 
 ```{r}
@@ -479,26 +486,28 @@ p_future <- predict_selected(models = fitted_model_maxnet,
                              progress_bar = FALSE)
 
 # Plot consensus (mean)
-plot(c(p_maxnet$General_consensus$mean,
-       p_future$General_consensus$mean),
-     main = c("Present", "Future (SSP 585, 2081-2100)"))
-
+terra::plot(c(p_maxnet$General_consensus$mean,
+              p_future$General_consensus$mean),
+            main = c("Present", "Future (SSP 585, 2081-2100)"))
 ```
 
-To identify how suitable areas change between scenarios, we can use `prediction_changes()`. This function binarizes the predictions using the threshold stored in the fitted models and then classifies each cell as gain, loss, or stable suitability.
+<br> 
+
+To identify how suitable areas change between scenarios, we can use `prediction_changes()`. This function computes binary layers from the predictions using the threshold stored in the fitted models, compares current and future predictions, and then classifies each cell as gain, loss, or stable.
 
-```{r}
+```{r detect changes}
 # Compute changes between scenarios
 p_changes <- prediction_changes(current_predictions = p_maxnet$General_consensus$mean,
                                 new_predictions = p_future$General_consensus$mean,
                                 fitted_models = fitted_model_maxnet,
                                 predicted_to = "future")
+
 # Plot result
 terra::plot(p_changes)
 ```
 
-In this example, we are comparing current predictions with future predictions, so the argument `predicted_to = "future"` is used. If the comparison were with past predictions, this argument should be set accordingly to ensure that gains and losses are classified correctly.
+<br> 
 
-The `prediction_changes()` function is designed to compute changes between single scenarios, meaning that the new scenario is represented by one GCM. If projections include multiple GCMs, the function `projection_changes()` should be used instead.
+In this example, we are comparing current and future predictions, so we set `predicted_to = "future"`. If a comparison with past predictions is needed, this argument should be set accordingly to ensure that categories of change or stability are assigned correctly.
 
-For more details on projecting models to multiple scenarios, see the vignette [6. Project Models to Multiple Scenarios](model_projections.html). 
+The `prediction_changes()` function is designed to compute changes between single scenarios, meaning that the new scenario is represented by one set of layers. If projections include multiple GCMs, the function `projection_changes()` should be used instead. For more details on projecting models and detecting changes with summaries across multiple scenarios, see the vignette [6. Project Models to Multiple Scenarios](model_projections.html). 
diff --git a/vignettes/model_projections.Rmd b/vignettes/model_projections.Rmd
@@ -21,11 +21,11 @@ knitr::opts_chunk$set(
 - [Description](#description)
 - [Getting ready](#getting-ready)
 - [Fitted models](#fitted-models)
-- [Predictors for projections](#predictors-for-projections)
-  - [Preparing predictors from WorldClim](#preparing-predictors-from-worldclim)
-    - [Format for renaming](#format-for-renaming)
-    - [Static variables](#static-variables)
-    - [Organizing files](#organizing-files)
+- [Variables for projections](#variables-for-projections)
+  - [Variables from WorldClim](#variables-from-worldclim)
+  - [Format for renaming](#format-for-renaming)
+  - [Static variables](#static-variables)
+  - [Organizing files](#organizing-files)
 - [Preparing data for projections](#preparing-data-for-projections)
 - [Projecting to multiple scenarios](#projecting-to-multiple-scenarios)
 - [Importing results from projections](#importing-results-from-projections)
@@ -80,15 +80,15 @@ fitted_model_maxnet
 
 <br> 
 
-# Predictors for projections
+# Variables for projections
 
-Predicting models for a single scenario requires a single `SpatRaster` object containing the predictor variables (as detailed in [Predict Models to a Single Scenario](model_predictions.html)). In contrast, projecting models to multiple scenarios requires a folder that stores predictor variables for each scenario organized in a certain way.
+Predicting models for a single scenario requires a single `SpatRaster` object containing the variables (as detailed in [Predict Models to a Single Scenario](model_predictions.html)). In contrast, projecting models to multiple scenarios requires a folder that stores variables for each scenario organized in a certain way.
 
 To ensure the following automated process can correctly track variables, the data must follow a strict hierarchical directory structure. At the top level, a *Base Directory* serves as the primary container for all project data. Inside this base folder, the first level of organization consists of subfolders for distinct *Time Periods*, such as future years (e.g., "2070", "2100") or paleoclimate eras (e.g., "Mid-holocene", "LGM"). Within each period folder, *if applicable*, you should include subfolders at the second level for each *Emission Scenario* (e.g., "ssp126", "ssp585"). Finally, within each emission scenario or time period folder, the third level should include a separate folder for each *General Circulation Model* (GCM) (e.g., "BCC-CSM2-MR", "MIROC6") to house the actual raster variables. This structured organization enables the function to automatically access and process the data according to period, emission scenario, and GCM.
 
 <br> 
 
-## Preparing predictors from WorldClim
+## Variables from WorldClim
 
 The package provides a function to import future climate variables downloaded from WorldClim (version 2.1). This function renames the files and organizes them into folders categorized by period/year, emission scenario (Shared Socioeconomic Pathways; SSPs), and General Circulation Model (GCM). This simplifies the preparation of climate data, ensuring all required variables are properly structured for modeling projections.
 
@@ -97,7 +97,7 @@ To use this function, download the [future raster variables from WorldClim 2.1](
 The package also provides an example of raw variables downloaded from WorldClim 2.1. This example includes bioclimatic predictions for the periods "2041-2060" and "2081-2100", for two SSPs (125 and 585) and two GCMs (ACCESS-CM2 and MIROC6), at 10 arc-minutes resolution.
 
 ```{r}
-# See raster files with future predictors provided as example
+# See raster files with future variables provided as example
 # The data is located in the "inst/extdata" folder.
 in_dir <- system.file("extdata", package = "kuenm2")
 list.files(in_dir)
@@ -165,7 +165,7 @@ Now, we can organize and structure the files using the `organize_future_worldcli
 
 <br> 
 
-### Format for renaming
+## Format for renaming
 
 The argument `name_format` defines the format for renaming variables. The names of the variables in the `SpatRaster` must precisely match those used when preparing data, even if a PCA was performed internally (if `do_pca = TRUE`; see [Prepare Data for Model Calibration](prepare_data.html) for details). If the variables used to create the models were "bio_1", "bio_2", etc., the variables representing other scenarios must be "bio_1", "bio_2", etc. However, if the names don't match exactly, projections can fail (always check uppercase letters or zeros before single-digit numbers (e.g., "Bio_01", "Bio_02", etc.). The function `organize_future_worldclim()` provides four renaming options:
 
@@ -186,7 +186,7 @@ The variables follow the standards of the first option (`"bio_"`).
 
 <br> 
 
-### Static variables
+## Static variables
 
 When predicting to other times, some variables could be static (i.e., they remain unchanged in scenarios of projections). The `static_variables` argument allows users to append static variables alongside the Bioclimatic ones. First, let's bring `soilType`, which will remain static in future scenarios (we will use it in a later step). 
 
@@ -200,7 +200,7 @@ soiltype <- var$SoilType
 
 <br> 
 
-### Organizing files
+## Organizing files
 
 Now, let's organize the WorldClim files with the `organize_future_worldclim()` function:
 
@@ -264,7 +264,7 @@ After organizing variables, the next step is to create an object that prepares t
 
 To prepare data for model projections across multiple scenarios, storing the paths to the raster layers representing each scenario, we use the function `prepare_projection()`.
 
-In contrast to `predict_selected()`, which requires a `SpatRaster` object, when projecting to multiple scenarios, we need the paths to the folders where the raster files are stored. This includes the variables for the present time, which were used to calibrate and fit the models. Currently, we only have the future climate files. The present-day predictor variables must reside in the same base directory as the processed future variables. Let's copy the raster layers used for model fitting to a folder we can easily direct the function that runs the next step:
+In contrast to `predict_selected()`, which requires a `SpatRaster` object, when projecting to multiple scenarios, we need the paths to the folders where the raster files are stored. This includes the variables for the present time, which were used to calibrate and fit the models. Currently, we only have the future climate files. The present-day variables must reside in the same base directory as the processed future variables. Let's copy the raster layers used for model fitting to a folder we can easily direct the function that runs the next step:
 
 ```{r copy present}
 # Create a "Current_raw" folder in a temporary directory
@@ -300,7 +300,7 @@ pr <- prepare_projection(models = fitted_model_maxnet,
 
 <br> 
 
-The `projection_data` object summarizes information about all the scenarios we will project to, and shows the root directory where the predictors are stored:
+The `projection_data` object summarizes information about all the scenarios we will project to, and shows the root directory where the variables are stored:
 
 ```{r print pr}
 pr
@@ -312,7 +312,7 @@ If we check the structure of the `prepared_projection` object, we can see it's a
 
 * Paths to all variables representing distinct scenarios in subfolders.
 * The pattern used to identify the format of raster files within the folders (by default, `*.tif`).
-* The names of the predictors.
+* The names of the variables.
 * A list of class `prcomp` if a Principal Component Analysis (PCA) was performed on the set of variables with `prepare_data()`.
 
 ```{r str pr, eval = FALSE}
@@ -461,12 +461,7 @@ terra::plot(p_2060_ssp126, cex.main = 0.8)
 
 With the `model_projections` object, we can compute changes in suitable areas (`projection_changes()`), explore variability patterns coming from replicates, parameterizations, and GCMs (`projection_variability()`), and perform analysis of extrapolation risks (`projection_mop()`). For more details, check [Explore Variability and Uncertainty in Projections](variability_and_uncertainty.html).
 
-<br> 
-
-```{r par_reset}
-# Reset plotting parameters
-par(original_par) 
-```
+<br>
 
 # Detecting changes in projections
 
@@ -599,3 +594,10 @@ changes <- readRDS(file.path(out_dir, "Projection_changes/changes_projections.rd
 <br>
 
 After saving, this object can be used to import specific results with the `import_results()` function.
+
+<br> 
+
+```{r par_reset}
+# Reset plotting parameters
+par(original_par) 
+```
diff --git a/vignettes/variability_and_uncertainty.Rmd b/vignettes/variability_and_uncertainty.Rmd
@@ -81,7 +81,7 @@ For more details about model projections, see ["Project Models to a Single Scena
 # Import calib_results_maxnet
 data("fitted_model_maxnet", package = "kuenm2")
 
-# Import path to raster files with future predictors provided as example
+# Import path to raster files with future variables provided as example
 # The data is located in the "inst/extdata" folder.
 in_dir <- system.file("extdata", package = "kuenm2")
 
