Merge model chains into Hmsc and coda objects

These functions merge posterior chains from multiple runs of Hmsc models into unified Hmsc and coda objects, facilitating further analysis. They check for missing or incomplete chains, optionally report these issues, and save the processed results to disk. mod_merge_chains handles regular models, while mod_merge_chains_CV is designed for cross-validated models.

Usage

mod_merge_chains(
  model_dir = NULL,
  n_cores = 8L,
  strategy = "multisession",
  model_info_name = NULL,
  print_incomplete = TRUE,
  from_JSON = FALSE,
  out_extension = "qs2"
)

mod_merge_chains_CV(
  model_dir = NULL,
  n_cores = 8L,
  strategy = "multisession",
  CV_names = c("CV_Dist", "CV_Large"),
  from_JSON = FALSE,
  out_extension = "qs2"
)

Arguments

model_dir

Character. Path to the root directory where the model was fitted. For mod_merge_chains, subdirectories Model_Fitted and Model_Coda are created within this path to store the merged Hmsc and coda objects, respectively. For mod_merge_chains_CV, merged objects are stored under Model_Fitting_CV/Model_Fitted.

n_cores

Integer. Number of CPU cores to use for parallel processing. Defaults to 8L.

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.

model_info_name

Character. Name of the file (without extension) where updated model information is saved. If NULL, overwrites the existing Model_Info.RData file in model_dir directory. If specified, creates a new .RData file with this name in model_dir directory. Applies only to mod_merge_chains.

print_incomplete

Logical. If TRUE, prints the names of model variants that failed to merge due to missing or incomplete chains. Defaults to TRUE.

from_JSON

Logical. Whether to convert loaded models from JSON format before reading. Defaults to FALSE.

out_extension

Character. File extension (without dot) for output files containing merged Hmsc and coda objects. Options are qs2 (faster read/write via the qs2 package) or RData (standard R format). Defaults to qs2.

CV_names

Character vector. Names of cross-validation strategies to merge, matching those used during model setup. Defaults to c("CV_Dist", "CV_Large"). The names should be one of CV_Dist, CV_Large, or CV_SAC. Applies only to mod_merge_chains_CV.

Value

Both functions return invisible(NULL) and save processed model information and merged objects to disk in the specified locations.

Details

• mod_merge_chains merges posterior chains from multiple runs of an Hmsc model fitted without cross-validation. It checks for missing or incomplete chains, aligns posteriors (using alignPost = TRUE, falling back to FALSE if alignment fails), and saves a merged Hmsc object and a coda object for MCMC diagnostics. It also records fitting time and memory usage from progress files.

• mod_merge_chains_CV performs a similar merging process for cross-validated Hmsc models, processing each fold of the specified CV_names separately. It saves merged Hmsc objects per fold but does not generate coda objects.

Author

Ahmed El-Gabbas