build_temporal_hv: Build Temporal Hypervolume Models Across Cross-Validation Folds

Description

Modeling function that constructs hypervolume models for each cross-validation fold using either Gaussian kernel density estimation or one-class SVM. Each hypervolume reserves one fold as testing data and uses the remaining folds as training data. The returned object follows the same structure as build_temporal_glm, build_temporal_gam, and build_temporal_rf, and is accepted directly by generate_spatiotemporal_predictions.

Usage

build_temporal_hv(partition_result, model_vars, method,
                  hypervolume_params = list(),
                  output_dir = file.path(tempdir(), "Hypervolume_Models"),
                  create_plot = TRUE, overwrite = FALSE,
                  plot_palette = "Dark 2", verbose = TRUE)

Value

A list with class "TemporalHypervolume" containing:

models: Named list of fitted Hypervolume objects, one per fold, named fold1, fold2, etc. This naming convention matches the other build_temporal_*() functions and is required by generate_spatiotemporal_predictions.
volumes: Named numeric vector of hypervolume sizes (units depend on the number of dimensions and bandwidth).
overlaps: Named list of pairwise percent volume overlaps between all fold combinations.
method: Character string recording the method used.
model_vars: Character vector of predictor names used.
fold_training_data: Named list of training data frames used to fit each fold model, retained for consistency with the other model types and for downstream use.
fold_test_metrics: Data frame of E-space inclusion metrics computed on the held-out test points for each fold. Columns: fold, n_test, volume, tp, fn, sensitivity, Sensitivity. Printed as a summary table at the end of model building.
output_dir: Path to the output directory.
model_type: Character string "hypervolume", used by generate_spatiotemporal_predictions.
plots: List of recorded plot objects (if create_plot = TRUE). Plots can be replayed with grDevices::replayPlot().

Arguments

partition_result: List or character. Output from spatiotemporal_partition or path to an .rds file containing that output.
model_vars: Character vector. Names of predictor columns to use in hypervolume construction. All variables must be present as columns in the occurrence data produced by temporally_explicit_extraction.
method: Character. Hypervolume method. One of "gaussian" for Gaussian kernel density estimation or "svm" for one-class support vector machine. Required.
hypervolume_params: Named list. Additional parameters passed to hypervolume_gaussian or hypervolume_svm. For Gaussian models, valid keys are kde.bandwidth, quantile.requested, quantile.requested.type, chunk.size, verbose, and samples.per.point. For SVM models, valid keys are svm.nu, svm.gamma, chunk.size, verbose, and samples.per.point. Default is an empty list, which uses the built-in defaults.
output_dir: Character. Directory to write output files including saved hypervolume objects and plots. Default is file.path(tempdir(), "Hypervolume_Models").
create_plot: Logical. If TRUE, generates pairplot visualisations of each fold's hypervolume and a combined comparison plot. Default is TRUE.
overwrite: Logical. If TRUE, overwrites existing saved hypervolume files. If FALSE, loads existing files when available. Default is FALSE.
plot_palette: Character. Name of an HCL or RColorBrewer palette used to color folds in diagnostic plots. Accepts any HCL palette name (see hcl.pals) or, if RColorBrewer is installed, any Brewer palette name. Default is "Dark 2".
verbose: Logical. If TRUE (default), prints progress messages during processing. Includes per-fold hypervolume construction progress, volume summaries, and overlap statistics.

Details

For N folds, constructs N hypervolumes where each fold reserves one group of points for testing and uses the remaining N-1 groups for training. Pairwise overlap statistics quantify similarity between hypervolumes across folds, with low overlap indicating that the environmental space sampled differs substantially across folds.

Hypervolume objects are saved as a combined .rds file in output_dir. If the file already exists and overwrite = FALSE, the saved file is loaded rather than re-fitting.

The returned object is accepted directly by generate_spatiotemporal_predictions, which uses the model_type field to dispatch hypervolume-specific projection logic via hypervolume_project.

Examples

Run this code

data(tmr_partition_small, package = "TemporalModelR")

build_temporal_hv(
  partition_result = tmr_partition_small,
  model_vars       = c("elevation", "forest_cover"),
  method           = "svm",
  output_dir       = tempdir(),
  create_plot      = FALSE,
  verbose          = FALSE
)