# R/data.R — Documentation for bundled datasets

#' Simulated allele-frequency-change dataset for ErrorTracer tutorials
#'
#' A named list containing training data, forecast predictors, validation
#' responses, and ground-truth parameters for two synthetic SNP clusters (A
#' and B) at a hypothetical mountain plant site.  The dataset is designed to
#' exercise every step of the ErrorTracer pipeline and to support
#' parameter-recovery validation (true coefficients are known).
#'
#' @format A named \code{list} with seven elements:
#' \describe{
#'   \item{\code{train}}{
#'     \code{data.frame} with 100 rows and 6 columns (2 clusters \eqn{\times}
#'     50 training years, 1970–2019):
#'     \describe{
#'       \item{year}{Integer. Calendar year.}
#'       \item{cluster_id}{Character. SNP cluster identifier: \code{"A"} or
#'         \code{"B"}.}
#'       \item{Tmean}{Numeric. Standardised mean growing-season temperature
#'         (original unit: °C; standardised using training-period mean and SD).}
#'       \item{PPT}{Numeric. Standardised total growing-season precipitation
#'         (original unit: mm).}
#'       \item{SWE}{Numeric. Standardised peak snow water equivalent
#'         (original unit: mm).}
#'       \item{z_diff}{Numeric. Simulated allele-frequency change on the
#'         arcsin-sqrt scale (\eqn{\arcsin(\sqrt{f})} transformation).
#'         This transformation is unbounded and has no fixed
#'         [\eqn{-1}, 1] constraint; the plausible range should be derived
#'         from the training data or from the theoretical bounds
#'         (\eqn{[0,\, \pi/2]}\ on the arcsin scale).}
#'     }
#'   }
#'   \item{\code{forecast}}{
#'     \code{data.frame} with 30 rows and 5 columns (2 clusters \eqn{\times}
#'     15 forecast years, 2020–2034).  Same columns as \code{train} except
#'     \code{z_diff} is absent — these are the prediction targets.  Predictors
#'     are standardised using the training-period statistics stored in
#'     \code{standardization}.
#'   }
#'   \item{\code{validation}}{
#'     \code{data.frame} with 30 rows and 3 columns (\code{year},
#'     \code{cluster_id}, \code{z_diff}).  True response values for the
#'     forecast period; used with \code{\link{et_calibrate}} to assess
#'     posterior predictive coverage.
#'   }
#'   \item{\code{true_params}}{
#'     Named \code{list} with one element per cluster.  Each element is a named
#'     numeric vector of the true data-generating parameters:
#'     \code{intercept}, \code{Tmean}, \code{PPT}, \code{SWE}, and
#'     \code{sigma} (residual SD).
#'     \describe{
#'       \item{Cluster A}{\code{intercept = 0.00}, \code{Tmean = 0.50},
#'         \code{PPT = -0.30}, \code{SWE = 0.20}, \code{sigma = 0.30}}
#'       \item{Cluster B}{\code{intercept = 0.10}, \code{Tmean = 0.30},
#'         \code{PPT = -0.20}, \code{SWE = -0.25}, \code{sigma = 0.35}}
#'     }
#'   }
#'   \item{\code{env_noise}}{
#'     Named \code{list}.  Suggested per-predictor environmental noise SDs (on
#'     the standardised scale) for use with the \code{env_noise} argument of
#'     \code{\link{et_predict}}: \code{Tmean = 0.30}, \code{PPT = 0.20},
#'     \code{SWE = 0.15}.
#'   }
#'   \item{\code{standardization}}{
#'     Named \code{list} with one element per predictor.  Each element is a
#'     named numeric vector \code{c(mean = ..., sd = ...)} giving the
#'     training-period statistics used to standardise the data.  Needed if you
#'     wish to back-transform predictions to the original (unstandardised)
#'     scale with \code{\link{unstandardize}}.
#'   }
#'   \item{\code{description}}{
#'     Character string.  Human-readable description of the dataset and how it
#'     was generated.
#'   }
#' }
#'
#' @details
#' The climate time series are simulated as AR(1) processes with a warming
#' trend in \code{Tmean} (+0.015 °C yr\eqn{^{-1}}, cumulating to ~0.30 SD
#' above the training mean over the 15-year forecast window).  \code{SWE}
#' is generated with a weak dependence on \code{Tmean} (negative coupling)
#' and \code{PPT} (positive coupling) plus a dominant independent noise
#' component, so that the three predictors have only mild pairwise
#' correlation (|R| < 0.2 on the training subset).  This makes all
#' regression coefficients reliably identifiable in a single replicate.
#' All predictors are standardised using training-period statistics only.
#'
#' In addition to the three real climate predictors, the dataset includes
#' ten independent standardised nuisance predictors \code{d1}, ..., \code{d10}
#' with zero true effect on the response.  They give the regularized-prior
#' extraction step a real selection job: cv.glmnet (alpha = 0.5) is expected
#' to identify the three real predictors and shrink the ten dummies toward
#' zero.  Without them, regularization on three well-identified predictors
#' merely biases the true coefficients without selecting anything.
#'
#' Responses are generated from a linear model with Gaussian noise:
#' \deqn{z\_diff_t = \alpha + \beta_1 Tmean_t + \beta_2 PPT_t +
#'       \beta_3 SWE_t + \varepsilon_t, \quad \varepsilon_t \sim
#'       \mathcal{N}(0, \sigma^2)}
#' The true parameters are stored in \code{et_sim$true_params} for
#' parameter-recovery validation.
#'
#' The dataset was generated with \code{set.seed(111)}.  The full generation
#' script is at \code{data-raw/generate_et_sim.R}.
#'
#' @examples
#' data(et_sim)
#'
#' # Inspect structure
#' str(et_sim, max.level = 2)
#'
#' # Training data
#' head(et_sim$train)
#'
#' # True parameters for cluster A
#' et_sim$true_params$A
#'
#' # Suggested noise SDs for et_predict()
#' et_sim$env_noise
#'
#' @source Generated by \code{data-raw/generate_et_sim.R} with
#'   \code{set.seed(111)}.
"et_sim"
