% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/build_temporal_hv.R
\name{build_temporal_hv}
\alias{build_temporal_hv}
\title{Build Temporal Hypervolume Models Across Cross-Validation Folds}
\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)
}
\arguments{
\item{partition_result}{List or character. Output from
\code{\link{spatiotemporal_partition}} or path to an \code{.rds}
file containing that output.}

\item{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 \code{\link{temporally_explicit_extraction}}.}

\item{method}{Character. Hypervolume method. One of \code{"gaussian"} for
Gaussian kernel density estimation or \code{"svm"} for one-class support
vector machine. Required.}

\item{hypervolume_params}{Named list. Additional parameters passed to
\code{\link[hypervolume]{hypervolume_gaussian}} or
\code{\link[hypervolume]{hypervolume_svm}}. For Gaussian models, valid
keys are \code{kde.bandwidth}, \code{quantile.requested},
\code{quantile.requested.type}, \code{chunk.size}, \code{verbose}, and
\code{samples.per.point}. For SVM models, valid keys are \code{svm.nu},
\code{svm.gamma}, \code{chunk.size}, \code{verbose}, and
\code{samples.per.point}. Default is an empty list, which uses the
built-in defaults.}

\item{output_dir}{Character. Directory to write output files including saved
hypervolume objects and plots. Default is \code{file.path(tempdir(), "Hypervolume_Models")}.}

\item{create_plot}{Logical. If \code{TRUE}, generates pairplot visualisations
of each fold's hypervolume and a combined comparison plot. Default is
\code{TRUE}.}

\item{overwrite}{Logical. If \code{TRUE}, overwrites existing saved
hypervolume files. If \code{FALSE}, loads existing files when available.
Default is \code{FALSE}.}

\item{plot_palette}{Character. Name of an HCL or RColorBrewer palette used
to color folds in diagnostic plots. Accepts any HCL palette name (see
\code{\link[grDevices]{hcl.pals}}) or, if \pkg{RColorBrewer} is installed,
any Brewer palette name. Default is \code{"Dark 2"}.}

\item{verbose}{Logical. If \code{TRUE} (default), prints progress
messages during processing. Includes per-fold hypervolume construction
progress, volume summaries, and overlap statistics.}
}
\value{
A list with class \code{"TemporalHypervolume"} containing:
\itemize{
  \item \code{models}: Named list of fitted \code{Hypervolume} objects, one
    per fold, named \code{fold1}, \code{fold2}, etc. This naming convention
    matches the other \code{build_temporal_*()} functions and is required by
    \code{\link{generate_spatiotemporal_predictions}}.
  \item \code{volumes}: Named numeric vector of hypervolume sizes (units
    depend on the number of dimensions and bandwidth).
  \item \code{overlaps}: Named list of pairwise percent volume overlaps
    between all fold combinations.
  \item \code{method}: Character string recording the method used.
  \item \code{model_vars}: Character vector of predictor names used.
  \item \code{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.
  \item \code{fold_test_metrics}: Data frame of E-space inclusion metrics
    computed on the held-out test points for each fold. Columns: \code{fold},
    \code{n_test}, \code{volume}, \code{tp}, \code{fn}, \code{sensitivity},
    \code{Sensitivity}. Printed as a summary table at the end of
    model building.
  \item \code{output_dir}: Path to the output directory.
  \item \code{model_type}: Character string \code{"hypervolume"}, used by
    \code{\link{generate_spatiotemporal_predictions}}.
  \item \code{plots}: List of recorded plot objects (if
    \code{create_plot = TRUE}). Plots can be replayed with
    \code{grDevices::replayPlot()}.
}
}
\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 \code{\link{build_temporal_glm}}, \code{\link{build_temporal_gam}},
and \code{\link{build_temporal_rf}}, and is accepted directly by
\code{\link{generate_spatiotemporal_predictions}}.
}
\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 \code{.rds} file in
\code{output_dir}. If the file already exists and \code{overwrite = FALSE},
the saved file is loaded rather than re-fitting.

The returned object is accepted directly by
\code{\link{generate_spatiotemporal_predictions}}, which uses the
\code{model_type} field to dispatch hypervolume-specific projection logic
via \code{\link[hypervolume]{hypervolume_project}}.
}
\examples{
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
)
}
\seealso{
Preprocessing: \code{\link{spatiotemporal_partition}}

Modeling: \code{\link{build_temporal_glm}}, \code{\link{build_temporal_gam}},
  \code{\link{build_temporal_rf}},
  \code{\link{generate_spatiotemporal_predictions}}

External: \code{\link[hypervolume]{hypervolume_gaussian}},
  \code{\link[hypervolume]{hypervolume_svm}}
}
