% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stepwise.R
\name{hzr_stepwise}
\alias{hzr_stepwise}
\alias{print.hzr_stepwise}
\alias{summary.hzr_stepwise}
\alias{print.summary.hzr_stepwise}
\alias{as.data.frame.hzr_stepwise}
\title{Stepwise covariate selection for a parametric hazard model}
\usage{
hzr_stepwise(
  fit,
  scope = NULL,
  data,
  direction = c("both", "forward", "backward"),
  criterion = c("wald", "aic"),
  slentry = 0.3,
  slstay = 0.2,
  max_steps = 50L,
  max_move = 4L,
  force_in = character(),
  force_out = character(),
  trace = TRUE,
  ...
)

\method{print}{hzr_stepwise}(x, ...)

\method{summary}{hzr_stepwise}(object, ...)

\method{print}{summary.hzr_stepwise}(x, ...)

\method{as.data.frame}{hzr_stepwise}(x, ...)
}
\arguments{
\item{fit}{A fitted \code{hazard} object built via the
\verb{formula = Surv(...) ~ predictors, data = df} interface.}

\item{scope}{Candidate set.  \code{NULL} (default) uses every data-frame
column not already in the model for every phase.  For
single-distribution fits, pass a one-sided formula
(\code{~ age + nyha}) or a character vector of names.  For multiphase
fits, pass a named list of one-sided formulas keyed by phase.}

\item{data}{Data frame the base fit was built on.  Required for
refits.}

\item{direction}{Search strategy --- one of \code{"both"} (default),
\code{"forward"}, or \code{"backward"}.  Controls whether variables may only
enter, only leave, or both.  See the \strong{Selection direction and
criterion} section.}

\item{criterion}{Entry / retention rule --- one of \code{"wald"} (default)
or \code{"aic"}.  \code{"wald"} applies SAS-style p-value thresholds
(\code{slentry} / \code{slstay}); \code{"aic"} adds or drops whenever it lowers the
AIC.  See the \strong{Selection direction and criterion} section.}

\item{slentry}{Entry p-value threshold for the Wald criterion.
Default \code{0.30} matches SAS \code{SLENTRY}.}

\item{slstay}{Retention p-value threshold for the Wald criterion.
Default \code{0.20} matches SAS \code{SLSTAY}.}

\item{max_steps}{Hard cap on total accepted actions.  Emits a
\code{warning()} if hit.  Default \code{50}.}

\item{max_move}{Per-variable oscillation cap.  When a variable has
entered + exited more than \code{max_move} times it is frozen for the
remainder of the run.  Default \code{4}.}

\item{force_in}{Character vector of variables that must remain in
the model.  Such variables are still scored and reported in the
selection trace, but are never dropped.}

\item{force_out}{Character vector of variables that may never be
considered as candidates.}

\item{trace}{Logical; print step-by-step progress to the console.
Default \code{TRUE}.}

\item{...}{Unused.}

\item{x}{An \code{hzr_stepwise} object.}

\item{object}{An \code{hzr_stepwise} object.}
}
\value{
An object of class \code{c("hzr_stepwise", "hazard")} -- the
final fit augmented with:
\describe{
\item{\code{steps}}{Data frame with one row per accepted /
frozen action; see Details.}
\item{\code{scope}}{Record of the candidate scope, plus
\code{force_in}, \code{force_out}, and the frozen set.}
\item{\code{criteria}}{Named list of the threshold / direction
settings actually applied.}
\item{\code{trace_msg}}{Character vector of the trace lines,
captured regardless of the \code{trace} flag.}
\item{\code{elapsed}}{\code{difftime} from start to finish.}
\item{\code{final_call}}{The call that produced this result.}
}

\code{print.hzr_stepwise} returns \code{x} invisibly.

\code{summary.hzr_stepwise} returns a \code{summary.hzr_stepwise} object
(extends \code{summary.hazard}) with \verb{$stepwise_steps} and \verb{$stepwise_trace}
appended.

\code{print.summary.hzr_stepwise} returns \code{x} invisibly.

\code{as.data.frame.hzr_stepwise} returns the \verb{$steps} data frame.
}
\description{
Run forward, backward, or two-way stepwise selection on an existing
\code{hazard} fit using Wald p-values or AIC deltas as the entry /
retention criterion.  Phase-specific entry is supported for
multiphase models: a covariate can enter one phase and not another.
}
\details{
The \code{steps} data frame has columns:

\describe{
\item{\code{step_num}}{Integer sequence starting at 1.}
\item{\code{action}}{\code{"enter"}, \code{"drop"}, or \code{"frozen"}.}
\item{\code{variable}}{Variable affected.}
\item{\code{phase}}{Phase name (multiphase) or \code{NA_character_}.}
\item{\code{criterion}}{\code{"wald"} or \code{"aic"}.}
\item{\code{score}}{Winning score used for the decision.}
\item{\code{stat}, \code{df}}{Wald statistic and degrees of
freedom.}
\item{\code{p_value}, \code{delta_aic}}{Always populated when
computable, regardless of the active criterion.}
\item{\code{logLik}, \code{aic}, \code{n_coef}}{Goodness-of-fit
diagnostics of the model \emph{after} this step.}
}
}
\section{Selection direction and criterion}{


Two arguments shape the search.  \code{direction} decides which moves are
allowed at each step; \code{criterion} decides how a candidate move is scored
and whether it is accepted.

\describe{
\item{\code{direction = "forward"}}{Start from the base model and only
\emph{add} variables --- the best eligible candidate enters each step
until none clears the entry rule.  Variables never leave once in.}
\item{\code{direction = "backward"}}{Start from the full candidate model and
only \emph{drop} variables --- the weakest term leaves each step until all
survivors clear the retention rule.}
\item{\code{direction = "both"} (default)}{Two-way stepwise: after each
entry, already-selected variables are re-tested and may be dropped.
This is the SAS \code{SELECTION = STEPWISE} strategy.  \code{max_move} caps how
often a single variable may oscillate before it is frozen.}
}

\describe{
\item{\code{criterion = "wald"} (default)}{Accept moves on SAS-style
significance thresholds, using the Wald \eqn{\chi^2} of the affected
coefficient(s): a candidate enters if its p-value is below \code{slentry}, and
a term is dropped if its p-value rises above \code{slstay}.  Entry candidates
are scored from a refit that adds the candidate (so its new coefficient
can be tested); drop candidates are scored from the \emph{current} model's
Wald p-values without a per-candidate refit, and a single refit is run
only after a drop is chosen.  Note this differs algorithmically from
C/SAS HAZARD, which selects on a \emph{score} (Q) statistic evaluated without
refitting; the two can take different step paths even when they converge
to a similar final model.}
\item{\code{criterion = "aic"}}{Accept any move with
\eqn{\Delta\mathrm{AIC} < 0} (a strictly better penalised fit), ignoring
\code{slentry} / \code{slstay}.  Entry candidates use the actual
\eqn{\Delta\mathrm{AIC}} from the candidate refit; drop candidates use a
Wald-to-likelihood-ratio approximation,
\eqn{\Delta\mathrm{AIC} \approx W - 2\,\mathrm{df}}, computed from the
current model without a per-candidate refit (the chosen drop is refit
afterwards).  Use this for a non-significance-based,
information-criterion search.}
}
}

\examples{
data(avc)
avc <- na.omit(avc)
base <- hazard(survival::Surv(int_dead, dead) ~ age,
               data = avc, dist = "weibull", fit = TRUE)
\donttest{
sw <- hzr_stepwise(base, scope = ~ age + nyha,
                   data = avc, direction = "forward",
                   control = list(n_starts = 1))
print(sw)
}

}
\seealso{
\code{\link[=hazard]{hazard()}} for the base model and \code{\link[=hzr_phase]{hzr_phase()}} for multiphase
scopes; \code{\link[=stepwise_trace]{stepwise_trace()}} to retrieve the captured selection log.
}
