% 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}{One of \code{"both"} (default), \code{"forward"},
\code{"backward"}.}

\item{criterion}{One of \code{"wald"} (default) or \code{"aic"}.  SAS-style
p-value thresholds apply to Wald; AIC uses \code{DeltaAIC < 0} uniformly.}

\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.}
}
}
\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)
}

}
