% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/data.R
\docType{data}
\name{et_sim}
\alias{et_sim}
\title{Simulated allele-frequency-change dataset for ErrorTracer tutorials}
\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.
  }
}
}
\source{
Generated by \code{data-raw/generate_et_sim.R} with
  \code{set.seed(111)}.
}
\usage{
et_sim
}
\description{
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).
}
\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

}
\keyword{datasets}
