Skip to contents

Predict habitat suitability of Hmsc models

Source: R/mod_predict_maps.R, R/mod_predict_maps_CV.R
Predict_Maps.Rd

This package provides two functions for predicting habitat suitability of Hmsc models in the IASDT framework. predict_maps generates current and future habitat suitability maps (mean, sd, cov) from a full Hmsc model fit. predict_maps_CV predicts and evaluates cross-validated Hmsc models for current climate conditions. For more details, see the respective function documentation and the details section below.

Usage

predict_maps(
  path_model = NULL,
  hab_abb = NULL,
  env_file = ".env",
  n_cores = 8L,
  strategy = "multisession",
  clamp_pred = TRUE,
  fix_efforts = "q90",
  fix_rivers = "q90",
  pred_new_sites = TRUE,
  use_TF = TRUE,
  TF_environ = NULL,
  TF_use_single = FALSE,
  LF_n_cores = n_cores,
  LF_check = FALSE,
  LF_temp_cleanup = TRUE,
  LF_only = FALSE,
  LF_commands_only = FALSE,
  temp_dir = "TEMP_Pred",
  temp_cleanup = TRUE,
  tar_predictions = TRUE,
  CC_models = c("GFDL-ESM4", "IPSL-CM6A-LR", "MPI-ESM1-2-HR", "MRI-ESM2-0",
    "UKESM1-0-LL"),
  CC_scenario = c("ssp126", "ssp370", "ssp585")
)

predict_maps_CV(
  model_dir = NULL,
  CV_name = NULL,
  CV_fold = NULL,
  n_cores = 8L,
  strategy = "multisession",
  env_file = ".env",
  use_TF = TRUE,
  TF_environ = NULL,
  TF_use_single = FALSE,
  LF_n_cores = n_cores,
  LF_check = FALSE,
  LF_temp_cleanup = TRUE,
  LF_only = FALSE,
  LF_commands_only = FALSE,
  temp_cleanup = TRUE
)

Arguments

path_model

Character. Path to fitted Hmsc model object.

hab_abb

Character. Habitat abbreviation indicating the specific SynHab habitat type. Valid values: 0, 1, 2, 3, 4a, 4b, 10, 12a, 12b. See Pysek et al. for details.

env_file

Character. Path to the environment file containing paths to data sources. Defaults to .env.

n_cores

Integer. Number of CPU cores to use for parallel processing. Default: 8.

strategy

Character. The parallel processing strategy to use. Valid options are "sequential", "multisession" (default), "multicore", and "cluster". See future::plan() and ecokit::set_parallel() for details.

clamp_pred

Logical indicating whether to clamp the sampling efforts at a single value. If TRUE (default), the fix_efforts argument must be provided.

fix_efforts

Numeric or character. When clamp_pred = TRUE, fixes the sampling efforts predictor at this value during predictions. If numeric, uses the value directly (on log10 scale). If character, must be one of median, mean, max, or q90 (90% quantile). Using max may reflect extreme sampling efforts from highly sampled locations, while q90 captures high sampling areas without extremes. Required if clamp_pred = TRUE.

fix_rivers

Numeric, character, or NULL. Similar to fix_efforts, but for the river length predictor. If NULL, the river length is not fixed. Default: q90.

pred_new_sites

Logical. Whether to predict suitability at new sites. Default: TRUE.

use_TF

Logical. Whether to use TensorFlow for calculations. Defaults to TRUE.

TF_environ

Character. Path to the Python environment. This argument is required if use_TF is TRUE under Windows. Defaults to NULL.

TF_use_single

Logical. Whether to use single precision for the TensorFlow calculations. Defaults to FALSE.

LF_n_cores

Integer. Number of cores to use for parallel processing of latent factor prediction. Defaults to 8L.

LF_check

Logical. If TRUE, the function checks if the output files are already created and valid. If FALSE, the function will only check if the files exist without checking their integrity. Default is FALSE.

LF_temp_cleanup

Logical. Whether to delete temporary files in the temp_dir directory after finishing the LF predictions.

LF_only

Logical. Whether to predict only the latent factor. This is useful for distributing processing load between GPU and CPU. When LF_only = TRUE, latent factor prediction needs to be computed separately on GPU. When computations are finished on GPU, the function can later be rerun with LF_only = FALSE (default) to predict habitat suitability using the already-computed latent factor predictions.

LF_commands_only

Logical. If TRUE, returns the command to run the Python script. Default is FALSE.

temp_dir

Character. Path for temporary storage of intermediate files.

temp_cleanup

Logical. Whether to clean up temporary files. Defaults to TRUE.

tar_predictions

Logical. Whether to compress the add files into a single *.tar file (without compression). Default: TRUE.

CC_models

Character vector. Climate models for future predictions. Available options are c("GFDL-ESM4", "IPSL-CM6A-LR", "MPI-ESM1-2-HR", "MRI-ESM2-0", "UKESM1-0-LL") (default).

CC_scenario

Character vector. Climate scenarios for future predictions. Available options are: c("ssp126", "ssp370", "ssp585") (default).

model_dir

Character. Path to the directory containing cross-validated models.

CV_name

Character. Cross-validation strategy. Valid values are CV_Dist, CV_Large, or CV_SAC.

CV_fold

Integer. The cross-validation fold number.

Details

  • predict_maps: Generates habitat suitability maps for Hmsc models fitted on the full dataset, for both current and future climate options. It produces maps for mean, standard deviation (sd), and coefficient of variation (cov) of suitability for each species and overall species richness. It evaluate model's explanatory power using various metrics. For future predictions, it also generates anomaly maps (future - current). The function supports ensemble predictions across multiple climate models and prepares data for upload to the OPeNDAP server for use in the IASDT Shiny App.

  • predict_maps_CV: Computes predictions for cross-validated Hmsc models using only the testing folds. It evaluates model performance (predictive power) with various metrics and plots evaluation results for predictive and explanatory power. Unlike predict_maps, this function does not perform clamping and does not generate future climate predictions.

See also

predict_hmsc

Author

Ahmed El-Gabbas