% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sensitivity.R
\name{et_sensitivity_profile}
\alias{et_sensitivity_profile}
\title{Sensitivity profile of the environmental uncertainty component}
\usage{
et_sensitivity_profile(
  model,
  newdata,
  response_scale,
  fraction_grid = NULL,
  absolute_grid = NULL,
  env_cov = NULL,
  env_dist = NULL,
  include_env_in_ci = TRUE,
  ci_level = 0.9,
  ci_levels = c(0.5, 0.8, 0.9, 0.95),
  threshold = 1,
  time_col = NULL,
  n_draws = 2000L,
  n_perturb = NULL,
  max_extrapolation_factor = 10,
  verbose = TRUE,
  plausible_range = NULL
)
}
\arguments{
\item{model}{An \code{et_model} from \code{\link{et_fit}}.}

\item{newdata}{\code{data.frame} passed to \code{et_predict}.}

\item{response_scale}{Two-element numeric vector \code{c(min, max)}, as in
\code{\link{shelf_life}}.  The effective range is
\code{diff(response_scale)}.}

\item{fraction_grid}{Optional numeric vector of scalar noise fractions.}

\item{absolute_grid}{Optional \code{list} of \code{env_noise} arguments
(each a named list / vector).  If supplied together with
\code{fraction_grid}, \code{fraction_grid} is ignored.}

\item{env_cov, env_dist}{Passed through to \code{et_predict}.}

\item{include_env_in_ci}{Logical.  If \code{TRUE} (default), credible
intervals — and hence the shelf-life horizon — are computed from
environmentally inflated draws (\code{et_predict(..., include_env_in_ci
= TRUE)}).  Set \code{FALSE} to see how \code{env_var} evolves while
holding the CI fixed at parameter + residual.}

\item{ci_level}{Numeric.  Used for shelf life and CI width tracking
(default 0.90).  Must be in \code{ci_levels}.}

\item{ci_levels}{Numeric vector of CI levels computed per iteration
(default \code{c(0.5, 0.8, 0.9, 0.95)}).}

\item{threshold}{Numeric.  Shelf-life threshold (default 1.0).}

\item{time_col}{Character.  Optional time column for shelf life.}

\item{n_draws, n_perturb}{Passed to \code{et_predict}.}

\item{max_extrapolation_factor}{Passed to \code{shelf_life}.}

\item{verbose}{Logical.  If \code{TRUE} (default), logs each iteration.}

\item{plausible_range}{Deprecated.  Use \code{response_scale} instead.}
}
\value{
An \code{et_sensitivity} object: a \code{data.frame} with one row
  per grid point and columns
  \describe{
    \item{\code{grid_id}}{1-indexed step.}
    \item{\code{label}}{Short descriptor of the env_noise used
      (e.g.\ \code{"fraction = 0.05"}).}
    \item{\code{fraction}}{Scalar fraction when applicable; \code{NA}
      for absolute-grid rows.}
    \item{\code{param_var, env_var, residual_var, total_var}}{Mean across
      forecast observations.}
    \item{\code{env_share}}{\code{env_var / (env_var + total_var)} ---
      the fraction of combined predictive variance attributable to
      predictor noise (bounded in \eqn{[0, 1]}).}
    \item{\code{ci_width_mean, ci_width_max}}{At \code{ci_level}.}
    \item{\code{ratio_mean, ratio_max}}{CI width / plausible range.}
    \item{\code{horizon_type}}{One of \code{"observed"}, \code{"projected"},
      \code{"lower_bound"}.}
    \item{\code{horizon}}{Numeric horizon (observed or projected) or
      \code{NA} for lower-bound rows.}
    \item{\code{horizon_description}}{The long description returned by
      \code{shelf_life}.}
  }
  The returned object carries the original call and \code{response_scale}
  as attributes for use by \code{\link{et_plot_sensitivity}}.
}
\description{
Sweeps a grid of noise magnitudes, re-runs \code{\link{et_predict}} for
each, and summarises how the environmental variance component and the
forecast shelf life respond.  This turns the subjective choice of
\code{env_noise} into an auditable \emph{curve}: instead of reporting a
single shelf life at one (often hand-picked) measurement-error level, the
user sees how the horizon degrades as assumed noise grows.
}
\details{
Three argument styles are supported for the grid:
\itemize{
  \item \code{fraction_grid}: scalar fractions of each predictor's SD in
    \code{newdata}.  These are passed straight to the scalar form of
    \code{\link{et_predict}}'s \code{env_noise}.  Use this for an apples-
    to-apples sweep that scales all predictors together.
  \item \code{absolute_grid}: a \code{list} of named numeric lists /
    vectors; each list element becomes a single \code{env_noise} argument
    (so you can sweep absolute SDs for one predictor while holding others
    fixed).
  \item Neither supplied (\code{NULL}): a default log-spaced fraction grid
    \code{c(0, 0.01, 0.025, 0.05, 0.1, 0.2, 0.4, 0.8)} is used.
}

Each iteration calls \code{et_predict(..., env_noise = g)} then
\code{\link{shelf_life}} and records:
\itemize{
  \item Mean parameter / environmental / residual / total variance across
    forecast observations.
  \item The horizon description (\code{"observed"}, \code{"projected"}, or
    \code{"lower_bound"}) and numeric horizon if any.
  \item Mean / max CI width / plausible-range ratio.
}
}
\seealso{
\code{\link{et_predict}}, \code{\link{shelf_life}},
  \code{\link{et_plot_sensitivity}}
}
