% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot_model_assessment.R
\name{plot_model_assessment}
\alias{plot_model_assessment}
\title{Visualize Model Assessment Metrics Across Time}
\usage{
plot_model_assessment(predictions, time_column,
                      secondary_time_mode = "combine", model_result = NULL,
                      cbp_threshold = 0.05, plot_palette = "Dark 2",
                      verbose = TRUE)
}
\arguments{
\item{predictions}{List returned by
\code{\link{generate_spatiotemporal_predictions}}, or a named list with
at least a \code{timestep_metrics} element. The \code{timestep_metrics}
element may also be a path to a \code{Timestep_Assessment_Metrics.csv}
file produced by \code{\link{generate_spatiotemporal_predictions}}.}

\item{time_column}{Character. Name of the primary time column in
\code{timestep_metrics} to use as the x axis (e.g. \code{"year"}).
When predictions span multiple time columns (e.g. \code{"year"} and
\code{"season"}), provide all relevant column names as a character
vector and control how secondary columns are handled via
\code{secondary_time_mode}.}

\item{secondary_time_mode}{Character. How to handle secondary time columns
when \code{time_column} has length > 1. One of:
\itemize{
  \item \code{"combine"} (default): secondary time values are appended to
    the primary value to form a single ordered x-axis label
    (e.g. \code{1_Spring}, \code{1_Summer}, \code{2_Spring}, ...).
  \item \code{"facet"}: a separate plot is produced for each unique
    combination of secondary time values, with the primary time column
    as the x axis on every panel.
}}

\item{model_result}{List or character. Optional. Output from a
\code{build_temporal_*()} function or path to its \code{.rds} file. When
supplied, overall sensitivity and specificity from
\code{model_result$fold_test_metrics} are added as per-fold reference
lines. Default is \code{NULL}.}

\item{cbp_threshold}{Numeric. Significance threshold for CBP. Default is
\code{0.05}.}

\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.}
}
\value{
Invisibly returns a named list containing:
\itemize{
  \item \code{pct_suitable}: Recorded plot of proportion of study area
    predicted suitable per time step.
  \item \code{sensitivity}: Recorded plot of per-timestep sensitivity.
  \item \code{specificity}: Recorded plot of per-timestep specificity
    (only present when pseudoabsence data were used).
  \item \code{cbp}: Recorded plot of cumulative binomial probability per
    time step on a log scale.
  \item \code{tp_fn}: Recorded plot of true positives and false negatives
    per time step.
  \item \code{tn_fp}: Recorded plot of true negatives and false positives
    per time step (only present when pseudoabsence data were used).
  \item \code{timestep_summary}: Data frame of per-time-step cross-fold
    mean and SD for each metric.
  \item \code{overall_summary}: Data frame from
    \code{predictions$overall_summary}, when present.
}
}
\description{
Generates diagnostic plots from the per-timestep assessment table produced
by \code{\link{generate_spatiotemporal_predictions}}, optionally overlaying
overall reference values from the model result object.
}
\details{
Plots per-fold and per-timestep diagnostic plots for data produced by
\code{\link{generate_spatiotemporal_predictions}}. These quick visuals can
be used by users to assess model performance and significance and decide
if the model's performance warrants further interpretation of the results
through post-processing analyses.
}
\examples{
data(tmr_predictions, package = "TemporalModelR")

plot_model_assessment(
  predictions         = tmr_predictions,
  time_column         = c("year", "season"),
  secondary_time_mode = "combine",
  verbose             = FALSE
)
}
\seealso{
Preprocessing: \code{\link{spatiotemporal_partition}},
  \code{\link{generate_absences}}

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

Post-processing: \code{\link{generate_spatiotemporal_predictions}},
  \code{\link{summarize_raster_outputs}}
}
