Merge pull request #94 from wevertonbio/main

wevertonbio · web-flow · commit 9762bdd76b00 · 2026-03-05T18:10:43.000-03:00
Change vignettes and update version
diff --git a/.Rbuildignore b/.Rbuildignore
@@ -8,3 +8,4 @@
 ^docs$
 ^pkgdown$
 ^\.github$
+^cran-comments\.md$
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,7 +1,7 @@
 Package: kuenm2
 Type: Package
 Title: Detailed Development of Ecological Niche Models
-Version: 0.0.12
+Version: 0.1.0
 Authors@R: c(
     person("Weverton C. F.", "Trindade", email = "wevertonf1993@gmail.com", role = c("aut", "cre"),
     comment = c(ORCID = "0000-0003-2045-4555")),
diff --git a/NEWS.md b/NEWS.md
@@ -0,0 +1,3 @@
+# kuenm2 0.1.0
+
+* Initial CRAN submission.
diff --git a/R/advanced_cleaning.R b/R/advanced_cleaning.R
@@ -21,8 +21,8 @@
 #' @param move_points_inside (logical) whether to move records outside of raster
 #' cells with valid values to the closest cell with values. Default = FALSE.
 #' @param move_limit_distance maximum distance to move records outside cells
-#' with valid values. Default = NULL. Must be defined if \code{move_points_inside}
-#' = TRUE.
+#' with valid values. Default = NULL. Must be defined if
+#' \code{move_points_inside} = TRUE.
 #' @param verbose (logical) whether to print messages of progress. Default =
 #' TRUE.
 #'
diff --git a/R/import_results.R b/R/import_results.R
@@ -268,7 +268,7 @@ import_results <- function(projection,
 
     #Get paths
     p_paths <- projection$paths
-    root_directory = projection$root_directory}
+    root_directory <- projection$root_directory}
 
 
   #Subset scenarios from mop and model projections
diff --git a/R/independent_evaluation.R b/R/independent_evaluation.R
@@ -164,7 +164,7 @@ independent_evaluation <- function(fitted_models, new_data,
            "\nAvailable options for glm fitted_models are 'response' or 'cloglog'.")
     }
     if(type == "cloglog")
-      type = "link"
+      type <- "link"
   }
 
   if(length(extrapolation_type) > 1){
diff --git a/R/plot_explore_partition.R b/R/plot_explore_partition.R
@@ -274,7 +274,7 @@ Please also provide a filled symbol for 'pch_in_range' (choose from 21, 22, 23,
   n_cols <- ceiling(sqrt(n_plots)) } else if (is.null(ncols) & n_plots <= 5){
     n_cols <- n_plots
   } else {
-    n_cols = ncols}
+    n_cols <- ncols}
   n_rows <- ceiling(n_plots / n_cols)
 
 
diff --git a/R/project_selected.R b/R/project_selected.R
@@ -208,7 +208,7 @@ project_selected <- function(models,
            "\nAvailable options for glm models are 'response' or 'cloglog'.")
     }
     if(type == "cloglog")
-      type = "link"
+      type <- "link"
   }
 
   #Save parameters in a list to send to foreach nodes#
diff --git a/cran-comments.md b/cran-comments.md
@@ -0,0 +1,5 @@
+## R CMD check results
+
+0 errors | 0 warnings | 1 note
+
+* This is a new release.
diff --git a/man/advanced_cleaning.Rd b/man/advanced_cleaning.Rd
diff --git a/vignettes/model_predictions.Rmd b/vignettes/model_predictions.Rmd
@@ -30,6 +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)
 
 <hr>
 
@@ -441,3 +442,63 @@ writeRaster(p_maxnet$General_consensus$mean,
             filename = file.path(tempdir(), "Mean_consensus.tif"))
 ```
 
+# Detecting changes between single scenarios
+
+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.
+
+As an example, we will project the fitted model to a **single GCM** representing future climatic conditions:
+
+```{r import var future}
+future_var <- terra::rast(system.file("extdata",
+                                      "wc2.1_10m_bioc_ACCESS-CM2_ssp585_2081-2100.tif",
+                                      package = "kuenm2"))
+plot(future_var)
+```
+
+Next, we need to rename the variables so that they match the variable names used when fitting the models:
+
+```{r}
+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}
+future_var <- c(future_var, var$SoilType)
+```
+
+Now we can generate predictions under future environmental conditions:
+
+```{r}
+# Predict
+p_future <- predict_selected(models = fitted_model_maxnet,
+                             new_variables = future_var, 
+                             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)"))
+
+```
+
+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.
+
+```{r}
+# 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.
+
+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.
+
+For more details on projecting models to 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
@@ -29,6 +29,11 @@ knitr::opts_chunk$set(
 - [Preparing data for projections](#preparing-data-for-projections)
 - [Projecting to multiple scenarios](#projecting-to-multiple-scenarios)
 - [Importing results from projections](#importing-results-from-projections)
+- [Detecting changes in projections](#detecting-changes-in-projections)
+    - [Setting colors for maps](#setting-colors-for-maps)
+    - [Types of results](#types-of-results)
+    - [Importing results](#importing-results)
+    - [Saving results](#saving-results)
 
 <hr>
 
@@ -462,3 +467,135 @@ With the `model_projections` object, we can compute changes in suitable areas (`
 # Reset plotting parameters
 par(original_par) 
 ```
+
+# Detecting changes in projections
+
+When projecting a model to different scenarios (past or future), suitable areas can be classified into three categories relative to the current baseline: **gain**, **loss** and **stability**. The interpretation of these categories depends on the temporal direction of the projection.
+
+**When projecting to future scenarios**:
+
+- *Gain*: Areas currently unsuitable become suitable in the future.
+- *Loss*: Areas currently suitable become unsuitable in the future.
+- *Stability*: Areas remain the same in the future, suitable or unsuitable.
+
+**When projecting to past scenarios**:
+
+- *Gain*: Areas unsuitable in the past are suitable in the present.
+- *Loss*: Areas suitable in the past are unsuitable in the present.
+- *Stability*: Areas remain the same in the present, suitable or unsuitable.
+
+These outcomes may vary across different General Circulation Models (GCMs) within each time scenario (e.g., various Shared Socioeconomic Pathways (SSPs) for the same period).
+
+The `projection_changes()` function summarizes the number of GCMs predicting gain, loss, and stability for each time scenario.
+
+By default, this function writes the summary results to disk (unless `write_results` is set to `FALSE`), but it does not save binary layers for individual GCMs. In the example below, we demonstrate how to configure the function to return the raster layers with changes and write the binary results to disk. 
+
+```{r projection_changes}
+# Run analysis to detect changes in suitable areas
+changes <- projection_changes(model_projections = p, 
+                              output_dir = out_dir, 
+                              write_bin_models = TRUE,  # Write individual binary results
+                              return_raster = TRUE)
+```
+
+<br>
+
+## Setting colors for maps
+
+Before plotting the results, we can use the `colors_for_changes()` function to assign custom colors to areas of gain, loss, and stability. By default, the function uses 'teal green' for gains, 'orange-red' for losses, 'Oxford blue' for areas that remain suitable, and 'grey' for areas that remain unsuitable. However, you can customize these colors as needed.
+
+The intensity of each color is automatically adjusted based on the number of GCMs: highest (as defined by `max_alpha`) when all GCMs agree on a prediction, and decreases progressively (down to `min_alpha`) as fewer GCMs support that outcome.
+
+```{r set colors for change}
+# Set colors for change maps
+changes_col <- colors_for_changes(changes)
+```
+
+The function returns the same `changes_projections` object, but with color tables embedded in its `SpatRasters`. These colors are automatically applied when visualizing the data using `terra::plot()`.
+
+<br>
+
+## Types os results
+
+The `projection_changes()` function returns four types of results: binary model prediction, results by GCM, results by change, and a general summary considering all GCMs:
+
+- **Binary prediction for each GCM**: These are suitable/unsuitable maps for each individual GCM. By default, the omission error threshold used when selecting the best models is used (e.g., 10%). You can specify a different threshold using the `user_threshold` argument.
+
+```{r binarized}
+terra::plot(changes_col$Binarized, cex.main = 0.8)
+```
+
+<br>
+
+- **Results by GCM**: provides the changes identified in comparisons (gain, loss, stability) for each GCM individually.
+
+```{r results by gcm}
+terra::plot(changes_col$Results_by_gcm, cex.main = 0.8)
+```
+
+<br>
+
+- **Results by change**: a list where each `SpatRaster` represents a specific type of change (e.g., gain, loss, stability) across all GCMs for a given scenario.
+
+```{r Results_by_change}
+# Results by change for the scenario of 2041-2060 (ssp126)
+terra::plot(changes_col$Results_by_change$`Future_2041-2060_ssp126`)
+```
+
+<br>
+
+- **Summary changes**: provides a general summary indicating how many GCMs project gain, loss, and stability for each scenario.
+
+```{r summary changes}
+terra::plot(changes_col$Summary_changes, plg = list(cex = 0.75))  # Decrease size of legend text
+```
+
+<br>
+
+## Importing Results
+
+When `return_raster = TRUE` is set, the resulting `SpatRaster` objects are returned within the `changes_projections` object. By default, however, `return_raster = FALSE` and the object only contains the directory path where the results were saved. In that case, the results can be imported using the `import_results()` function. You can specify the type of results to import, along with the target period and emission scenario.
+
+A `changes_projections` object imported using `import_results()` can also be used as input to `colors_for_changes()` to customize the colors used for plotting.
+
+For example, below we import only the general summary for the 2041–2060 period under the SSP5-8.5 scenario:
+
+```{r import general summary}
+# Import changes detected for 2041–2060 SSP5-8.5 
+general_changes <- import_results(projection = changes, 
+                                  future_period = "2041-2060", 
+                                  future_pscen = "ssp585",
+                                  change_types = "summary")
+
+# Set colors
+general_changes <- colors_for_changes(general_changes)
+
+# Plot
+terra::plot(general_changes$Summary, main = names(general_changes$Summary),
+            plg = list(cex = 0.75))  # Decrease size of legend text
+```
+
+<br>
+
+## Saving results
+
+The `changes_projections` object is a list that contains the resulting `SpatRaster` objects (if `return_raster = TRUE`) and the directory path where results were saved (if `write_results = TRUE`).
+
+If results were not written to disk during the initial run, you can save `SpatRaster` objects afterward using the `writeRaster()` function. For example, to save the general summary raster:
+
+```{r save raster changes, eval = FALSE}
+writeRaster(changes$Summary_changes,
+            file.path(out_dir, "Summary_changes.tif"))
+```
+
+<br>
+
+If the results were saved to disk, the `changes_projections` object is automatically stored in a folder named *Projection_changes* inside the specified `output_dir`. You can load it back into R using `readRDS()`:
+
+```{r read changes projection}
+changes <- readRDS(file.path(out_dir, "Projection_changes/changes_projections.rds"))
+```
+
+<br>
+
+After saving, this object can be used to import specific results with the `import_results()` function.
diff --git a/vignettes/variability_and_uncertainty.Rmd b/vignettes/variability_and_uncertainty.Rmd

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# kuenm2 0.1.0`
	`2`	`+`
	`3`	`+* Initial CRAN submission.`
Original file line number	Diff line number	Diff line change
`@@ -164,7 +164,7 @@ independent_evaluation <- function(fitted_models, new_data,`
`164`	`164`	`"\nAvailable options for glm fitted_models are 'response' or 'cloglog'.")`
`165`	`165`	`}`
`166`	`166`	`if(type == "cloglog")`
`167`		`- type = "link"`
	`167`	`+ type <- "link"`
`168`	`168`	`}`
`169`	`169`
`170`	`170`	`if(length(extrapolation_type) > 1){`
Original file line number	Diff line number	Diff line change
`@@ -208,7 +208,7 @@ project_selected <- function(models,`
`208`	`208`	`"\nAvailable options for glm models are 'response' or 'cloglog'.")`
`209`	`209`	`}`
`210`	`210`	`if(type == "cloglog")`
`211`		`- type = "link"`
	`211`	`+ type <- "link"`
`212`	`212`	`}`
`213`	`213`
`214`	`214`	`#Save parameters in a list to send to foreach nodes#`