### This file documents the pre-built workflow objects stored in data/ and
### the bundled raster / point files stored in inst/extdata/.
### Documentation is generated from roxygen2 tags below.


### Seasonal workflow .rda objects --------------------------------------------

#' Pre-built spatiotemporal partition (seasonal workflow)
#'
#' Output from \code{\link{spatiotemporal_partition}} run on the synthetic
#' occurrence dataset bundled in \code{inst/extdata/}. Built with
#' \code{n_spatial_folds = 2} and \code{n_temporal_folds = 2}, producing
#' four cross-validation folds (2 spatial + 2 temporal). Points span 15
#' years and the seasons Spring, Summer, and Autumn on a 15 x 30 cell
#' study area (3000 m x 1500 m, 100 m pixels) in a custom synthetic local
#' CRS. Predictors attached to each point are \code{forest_cover},
#' \code{prseas} (seasonal precipitation), and \code{elevation}, all
#' z-scored. Loaded with \code{data(tmr_partition)}.
#'
#' @format A list as returned by \code{\link{spatiotemporal_partition}},
#'   containing \code{$folds}, \code{$points_sf}, \code{$voronoi_blocks},
#'   \code{$voronoi_folds}, \code{$summary}, and \code{$plots}.
"tmr_partition"

#' Pre-built spatiotemporal partition, small version (seasonal workflow)
#'
#' A subsampled version of \code{\link{tmr_partition}} retaining
#' approximately half the points per fold, for use in examples and tests
#' where runtime is a concern. Built by sampling
#' \code{ceiling(n / 2)} rows from each fold of \code{tmr_partition$points_sf}.
#' Loaded with \code{data(tmr_partition_small)}.
#'
#' @format A list with the same structure as \code{\link{tmr_partition}},
#'   containing \code{$folds}, \code{$points_sf}, \code{$voronoi_blocks},
#'   \code{$voronoi_folds}, \code{$summary}, and \code{$plots}.
#' @seealso \code{\link{tmr_partition}}
"tmr_partition_small"

#' Pre-built pseudoabsence result (seasonal workflow)
#'
#' Output from \code{\link{generate_absences}} using the buffer method with
#' a 300 m buffer (3 pixels at the synthetic landscape's 100 m resolution)
#' and a 2:1 pseudoabsence-to-presence ratio. Pseudoabsences are stratified
#' by fold from \code{tmr_partition} and have \code{forest_cover},
#' \code{prseas}, and \code{elevation} extracted at each location's
#' year-season combination. Loaded with \code{data(tmr_absences)}.
#'
#' @format A list as returned by \code{\link{generate_absences}}, containing
#'   \code{$pseudoabsences} (an sf object with attached predictor columns),
#'   \code{$plots}, and \code{$summary}.
"tmr_absences"

#' Pre-built GLM result (seasonal workflow)
#'
#' Output from \code{\link{build_temporal_glm}} fit to \code{tmr_partition}
#' and \code{tmr_absences} with the formula
#' \code{~ forest_cover + prseas + elevation}, a logit link, and TSS-based
#' threshold selection. One model per fold. Loaded with
#' \code{data(tmr_glm)}.
#'
#' @format A list of class \code{"TemporalGLM"} as returned by
#'   \code{\link{build_temporal_glm}}, containing \code{$models},
#'   \code{$thresholds}, \code{$threshold_method}, \code{$model_formula},
#'   \code{$link}, \code{$model_vars}, \code{$fold_training_data},
#'   \code{$fold_test_metrics}, \code{$output_dir}, \code{$model_type},
#'   and \code{$plots}.
"tmr_glm"

#' Pre-built spatiotemporal predictions (seasonal workflow)
#'
#' Output from \code{\link{generate_spatiotemporal_predictions}} projecting
#' \code{tmr_glm} across 15 years for the Spring season only (one
#' prediction layer per year-season combination, 15 total). Loaded with
#' \code{data(tmr_predictions)}.
#'
#' Note that \code{$prediction_files} stores the absolute paths used at
#' build time. To work with the per-timestep rasters on a user machine,
#' regenerate them via \code{\link{generate_spatiotemporal_predictions}}
#' or use the bundled prediction set in \code{inst/extdata/predictions/}.
#'
#' @format A list as returned by
#'   \code{\link{generate_spatiotemporal_predictions}}, containing
#'   \code{$timestep_metrics}, \code{$overall_summary},
#'   \code{$prediction_files}, and \code{$model_type}.
"tmr_predictions"


### Annual workflow .rda objects --------------------------------------------

#' Pre-built spatiotemporal partition (annual workflow)
#'
#' Annual variant of \code{tmr_partition}. Built from points rarefied with
#' \code{time_cols = "year"} only (one point per pixel per year) and
#' extracted against annual predictors. Predictors attached to each point
#' are \code{forest_cover}, \code{pr_ann} (annual precipitation), and
#' \code{elevation}, all z-scored. Uses
#' \code{n_spatial_folds = 2} and \code{n_temporal_folds = 2} for four
#' folds. Loaded with \code{data(tmr_partition_annual)}.
#'
#' @format A list as returned by \code{\link{spatiotemporal_partition}}.
"tmr_partition_annual"

#' Pre-built pseudoabsence result (annual workflow)
#'
#' Annual variant of \code{tmr_absences}. Buffer method with 300 m buffer
#' and 2:1 ratio, generated against \code{tmr_partition_annual} with the
#' annual predictor set (\code{forest_cover}, \code{pr_ann},
#' \code{elevation}). Loaded with \code{data(tmr_absences_annual)}.
#'
#' @format A list as returned by \code{\link{generate_absences}}.
"tmr_absences_annual"

#' Pre-built GLM result (annual workflow)
#'
#' Annual variant of \code{tmr_glm}. Fit with the formula
#' \code{~ forest_cover + pr_ann + elevation}, a logit link, and
#' TSS-based threshold selection. One model per fold. Loaded with
#' \code{data(tmr_glm_annual)}.
#'
#' @format A list of class \code{"TemporalGLM"}.
"tmr_glm_annual"

#' Pre-built spatiotemporal predictions (annual workflow)
#'
#' Annual variant of \code{tmr_predictions}. Projects \code{tmr_glm_annual}
#' across 15 years on a single (year-only) time axis. Loaded with
#' \code{data(tmr_predictions_annual)}.
#'
#' @format A list as returned by
#'   \code{\link{generate_spatiotemporal_predictions}}.
"tmr_predictions_annual"


#' Pre-built user_data pseudoabsences (seasonal workflow)
#'
#' Output of \code{\link{generate_absences}} run with
#' \code{method = "user_data"} against \code{\link{tmr_partition}}, using
#' \code{inst/extdata/points/synthetic_user_presences.csv} as the supplied
#' absence locations. The CSV contains occurrence-formatted points for a
#' 'related speecies' to that data of interest to be used as a proxy for survey
#' effort for the species of interest, serving as an alternative method for
#' generating pseudoabsences.
#'
#' @format A list as returned by \code{\link{generate_absences}}, containing
#'   \code{$pseudoabsences} (an sf object with attached predictor columns),
#'   \code{$plots}, and \code{$summary}.
#'
"tmr_absences_user"


### Bundled extdata --------------------------------------------------------

#' Bundled rasters, point files, and prediction outputs
#'
#' Several non-R objects ship in \code{inst/extdata/} for use in function
#' examples and the package vignette. They cannot be portably serialized
#' as \code{.rda} files, so they are stored as GeoTIFF and CSV files and
#' loaded via \code{\link[base]{system.file}}.
#'
#' \describe{
#'   \item{\code{extdata/rasters_raw/}}{Raw synthetic environmental rasters
#'     before alignment. Includes \code{elevation.tif},
#'     \code{forest_cover_1.tif} through \code{forest_cover_15.tif},
#'     \code{pr_ann_1.tif} through \code{pr_ann_15.tif}, and
#'     \code{prseas_<year>_<season>.tif} for each of 15 years and 4
#'     seasons (60 files).}
#'   \item{\code{extdata/rasters_aligned/}}{Same rasters after
#'     \code{\link{raster_align}} has reprojected and masked them to the
#'     reference grid.}
#'   \item{\code{extdata/rasters_scaled/}}{Aligned rasters z-scored using
#'     the scaling parameters from the seasonal extraction. Used by
#'     examples and modeling functions that work with the seasonal
#'     predictor set.}
#'   \item{\code{extdata/rasters_scaled_annual/}}{Aligned rasters z-scored
#'     using the scaling parameters from the annual extraction. Used by
#'     examples and modeling functions that work with the annual
#'     predictor set (\code{pr_ann} instead of \code{prseas}).}
#'   \item{\code{extdata/points/synthetic_occurrence_points.csv}}{The raw
#'     synthetic presence dataset: 150 points with \code{x}, \code{y},
#'     \code{year}, \code{season}, and \code{pres = 1}.}
#'   \item{\code{extdata/points/synthetic_occurrence_points.shp}}{Same
#'     points as a shapefile.}
#'   \item{\code{extdata/points/synthetic_user_presences.csv}}{A second-species
#'     presence dataset for demonstrating \code{method = "user_data"} in
#'     \code{\link{generate_absences}}. Points were derived from buffer-
#'     constrained environmental pseudoabsences of the primary species and
#'     reformatted as presences (\code{pres = 1}). Same column structure as
#'     \code{synthetic_occurrence_points.csv} (\code{x}, \code{y},
#'     \code{year}, \code{season}, \code{pres}).}
#'   \item{\code{extdata/points/extracted_seasonal_*.csv}}{Outputs from
#'     \code{\link{temporally_explicit_extraction}} using the seasonal
#'     predictor set: \code{_Raw_Values.csv}, \code{_Scaled_Values.csv},
#'     and \code{_Scaling_Parameters.csv}.}
#'   \item{\code{extdata/points/extracted_annual_*.csv}}{Same outputs but
#'     using the annual predictor set.}
#'   \item{\code{extdata/predictions/}}{Per-timestep fold-vote rasters
#'     from the seasonal workflow's
#'     \code{\link{generate_spatiotemporal_predictions}} call. Fifteen
#'     files (\code{Prediction_<year>_Spring.tif}) suitable for direct
#'     input to \code{\link{summarize_raster_outputs}}.}
#'   \item{\code{extdata/binary/consensus_stack.tif}}{Multi-layer
#'     GeoTIFF of binary suitable / unsuitable rasters produced by
#'     \code{\link{summarize_raster_outputs}} with \code{consensus = 3}.
#'     Fifteen layers, one per year, ordered 1 through 15.}
#'   \item{\code{extdata/binary/frequency_raster.tif}}{Companion
#'     single-layer raster giving the proportion of years each pixel was
#'     classified as suitable.}
#'   \item{\code{extdata/precomputed/}}{Precomputed prediction outputs read
#'     directly by the modeling vignettes (V3a-V3d) so that
#'     \code{\link{generate_spatiotemporal_predictions}} does not need to be
#'     rerun at vignette build time. One subdirectory per model type
#'     (\code{glm/}, \code{gam/}, \code{rf/}, \code{hv/}), each containing
#'     \code{preds.rds} and a \code{pred_tifs/} folder. \code{preds.rds} is
#'     the list returned by
#'     \code{\link{generate_spatiotemporal_predictions}} for that model
#'     (\code{$timestep_metrics}, \code{$overall_summary},
#'     \code{$prediction_files}, and \code{$model_type}), with
#'     \code{$prediction_files} reduced to bare file names rather than
#'     absolute build-time paths. \code{pred_tifs/} holds the 60
#'     per-timestep fold-vote rasters
#'     (\code{Prediction_<year>_<season>.tif}, 15 years x 4 seasons)
#'     projected from that model. The vignettes load \code{preds.rds} and
#'     rebuild \code{$prediction_files} from \code{pred_tifs/} via
#'     \code{\link[base]{system.file}}.}
#' }
#'
#' Example load patterns:
#' \preformatted{
#'   ### Aligned raster directory
#'   aln_dir <- system.file("extdata/rasters_aligned",
#'                          package = "TemporalModelR")
#'
#'   ### Consensus stack (multi-layer)
#'   binary_stack <- terra::rast(system.file(
#'     "extdata/binary/consensus_stack.tif", package = "TemporalModelR"
#'   ))
#'
#'   ### Frequency raster
#'   frequency_rast <- terra::rast(system.file(
#'     "extdata/binary/frequency_raster.tif", package = "TemporalModelR"
#'   ))
#'
#'   ### Per-timestep prediction directory
#'   pred_dir <- system.file("extdata/predictions",
#'                           package = "TemporalModelR")
#'
#'   ### Precomputed GLM prediction object and its rasters
#'   glm_preds <- readRDS(system.file(
#'     "extdata/precomputed/glm/preds.rds", package = "TemporalModelR"
#'   ))
#'   glm_pred_files <- list.files(
#'     system.file("extdata/precomputed/glm/pred_tifs",
#'                 package = "TemporalModelR"),
#'     pattern = "\\.tif$", full.names = TRUE
#'   )
#' }
#'
#' @name extdata
#' @docType data
NULL
