% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/phase-spec.R
\name{hzr_phase}
\alias{hzr_phase}
\alias{print.hzr_phase}
\title{Specify a single hazard phase}
\usage{
hzr_phase(
  type = c("cdf", "hazard", "constant", "g3"),
  t_half = 1,
  nu = 1,
  m = 0,
  tau = 1,
  gamma = 1,
  alpha = 1,
  eta = 1,
  formula = NULL,
  fixed = character(0)
)

\method{print}{hzr_phase}(x, ...)
}
\arguments{
\item{type}{Character; the phase's temporal shape --- one of \code{"cdf"}
(early resolving risk), \code{"hazard"} (accumulating G1 aging risk), \code{"g3"}
(late rising risk, the original C/SAS late phase), or \code{"constant"} (flat
background rate).  See the \strong{Phase types} section for what each means and
when to use it.}

\item{t_half}{Positive scalar; initial half-life (time at which
\eqn{G(t_{1/2}) = 0.5}).  Used for \code{"cdf"} and \code{"hazard"} phases.
SAS early: \code{THALF}/\code{RHO}.}

\item{nu}{Numeric scalar; initial time exponent.  Used for \code{"cdf"} and
\code{"hazard"} phases.  SAS early: \code{NU}.}

\item{m}{Numeric scalar; initial shape exponent.  Used for \code{"cdf"} and
\code{"hazard"} phases.  SAS early: \code{M}.}

\item{tau}{Positive scalar; scale parameter for \code{"g3"} phases.
SAS late: \code{TAU}.}

\item{gamma}{Positive scalar; time exponent for \code{"g3"} phases.
SAS late: \code{GAMMA}.}

\item{alpha}{Non-negative scalar; shape parameter for \code{"g3"} phases.
When \code{alpha > 0}, the generic G3 formula is used; \code{alpha = 0} gives the
exponential limiting case.  SAS late: \code{ALPHA}.}

\item{eta}{Positive scalar; outer exponent for \code{"g3"} phases.
SAS late: \code{ETA}.}

\item{formula}{Optional one-sided formula (e.g. \code{~ age + nyha}) for
phase-specific covariates.  When \code{NULL} (default), the phase inherits
the global formula from \code{\link[=hazard]{hazard()}}.}

\item{fixed}{Character vector naming shape parameters to hold fixed during
optimization.  Valid names for \code{"cdf"}/\code{"hazard"}: \code{"t_half"}, \code{"nu"},
\code{"m"}, or \code{"shapes"} (shorthand for all three).  Valid names for \code{"g3"}:
\code{"tau"}, \code{"gamma"}, \code{"alpha"}, \code{"eta"}, or \code{"shapes"} (shorthand for all
four).  Fixed parameters are held at their starting values; only \code{mu}
(and covariates) are estimated.  Ignored for \code{"constant"} phases.
This mirrors the SAS/C HAZARD workflow where shapes are typically fixed
and only scale parameters are estimated.}

\item{x}{An \code{hzr_phase} object (for \code{print.hzr_phase()}).}

\item{...}{Additional arguments (ignored).}
}
\value{
An S3 object of class \code{"hzr_phase"} with elements:
\describe{
\item{type}{Phase type string.}
\item{t_half}{Initial half-life (cdf/hazard phases).}
\item{nu}{Initial time exponent (cdf/hazard phases).}
\item{m}{Initial shape exponent (cdf/hazard phases).}
\item{tau}{Scale parameter (g3 phases).}
\item{gamma}{Time exponent (g3 phases).}
\item{alpha}{Shape parameter (g3 phases).}
\item{eta}{Outer exponent (g3 phases).}
\item{formula}{Phase-specific formula or \code{NULL}.}
\item{fixed}{Character vector of fixed parameter names (may be empty).}
}
}
\description{
Creates an \code{hzr_phase} object describing one term in a multiphase additive
cumulative hazard model.  Pass a list of these to the \code{phases} argument of
\code{\link[=hazard]{hazard()}} when \code{dist = "multiphase"}.
}
\section{Role in the multiphase model}{


Each phase is one term \eqn{j} in the additive cumulative hazard

\deqn{H(t \mid \mathbf{x}) = \sum_{j=1}^{J} \mu_j(\mathbf{x}) \,
      \Phi_j(t)}

where \eqn{\mu_j(\mathbf{x}) = \exp(\alpha_j + \mathbf{x}_j^\top
\boldsymbol{\beta}_j)} is the phase-specific log-linear scale and
\eqn{\Phi_j(t)} is the temporal shape selected by \code{type} (below).  The
\code{t_half}/\code{nu}/\code{m} (or g3 \code{tau}/\code{gamma}/\code{alpha}/\code{eta}) arguments set the
starting values for that shape; \code{formula} attaches the covariates
\eqn{\mathbf{x}_j} that enter \eqn{\mu_j}.
}

\section{Phase types}{


The \code{type} argument chooses the temporal shape \eqn{\Phi_j(t)} for the phase.
Each captures a qualitatively different pattern of risk over time; a typical
clinical model combines an \emph{early}, a \emph{constant}, and a \emph{late} phase so that
the total hazard can fall, level off, and rise again.

\describe{
\item{\code{"cdf"} --- early, resolving risk}{Named for the \strong{c}umulative
\strong{d}istribution \strong{f}unction: the phase contributes \eqn{\Phi(t) = G(t)},
the bounded CDF of the temporal decomposition (\eqn{0} at \eqn{t = 0},
rising to a ceiling of \eqn{1}).  Because it saturates, the \emph{hazard} it
adds, \eqn{\mu\,g(t)}, peaks early and then decays toward zero --- the
signature of a one-time insult that patients either succumb to or survive
past, e.g. peri-operative mortality.  Shape set by \code{t_half}, \code{nu}, \code{m}.
SAS/C equivalent: the Early (G1) phase.}
\item{\code{"hazard"} --- accumulating aging risk (G1 family)}{Named because the
phase contributes a \strong{cumulative hazard} built from the same G1 family:
\eqn{\Phi(t) = -\log(1 - G(t))}, which is unbounded and monotone
increasing.  Its hazard \eqn{\mu\,h(t)} rises without leveling off, so it
models risk that grows as subjects age.  This is an alternative late-risk
form derived from G1; for the original SAS/C late phase prefer \code{"g3"}.
Shape set by \code{t_half}, \code{nu}, \code{m}.}
\item{\code{"g3"} --- late, rising risk (original C/SAS late phase)}{Named for
the \strong{G3} (third) decomposition family used by the original HAZARD
program for the late phase.  It contributes \eqn{\Phi(t) = G_3(t)} from
\code{\link[=hzr_decompos_g3]{hzr_decompos_g3()}}, an unbounded intensity with its own four-parameter
shape (\code{tau}, \code{gamma}, \code{alpha}, \code{eta}) that is more flexible than the
G1-derived \code{"hazard"} form for capturing accelerating late mortality
(e.g. structural valve deterioration years after surgery).  Use this when
reproducing classic three-phase HAZARD models.  SAS/C equivalent: the
Late (G3) phase.}
\item{\code{"constant"} --- flat background rate}{A time-invariant hazard:
\eqn{\Phi(t) = t}, so the added hazard \eqn{\mu} is constant (the
exponential model).  It represents the steady, ongoing risk present at all
follow-up times, independent of how long ago the time origin was.  Takes
no shape parameters --- only its scale \eqn{\mu} (and any covariates) is
estimated.  SAS/C equivalent: the Constant (G2) phase.}
}

The shape derivative \eqn{\varphi_j = d\Phi_j/dt} (which forms the
instantaneous hazard contribution \eqn{\mu_j\,\varphi_j(t)}) is \eqn{g(t)} for
\code{"cdf"}, \eqn{h(t)} for \code{"hazard"}, \eqn{g_3(t)} for \code{"g3"}, and \eqn{1} for
\code{"constant"}.
}

\examples{
# Classic 3-phase Blackstone pattern
early <- hzr_phase("cdf",      t_half = 0.5, nu = 2, m = 0)
const <- hzr_phase("constant")
late  <- hzr_phase("g3", tau = 1, gamma = 3, alpha = 1, eta = 1)

# Fix all shapes (C/SAS-style: only estimate mu)
early_fixed <- hzr_phase("cdf", t_half = 0.5, nu = 2, m = 0,
                          fixed = "shapes")
late_fixed  <- hzr_phase("g3", tau = 1, gamma = 3, alpha = 1, eta = 1,
                          fixed = "shapes")

# Fix only some parameters
early_partial <- hzr_phase("cdf", t_half = 0.5, nu = 2, m = 0,
                            fixed = c("nu", "m"))

# Phase with specific covariates
early_cov <- hzr_phase("cdf", t_half = 0.5, nu = 2, m = 0,
                        formula = ~ age + shock)

# Use in hazard():
# hazard(Surv(time, status) ~ age, data = dat,
#        dist = "multiphase",
#        phases = list(early = early, constant = const, late = late))

}
\seealso{
\code{\link[=hazard]{hazard()}} for fitting multiphase models,
\code{\link[=hzr_decompos]{hzr_decompos()}} for the underlying parametric family,
\code{\link[=hzr_phase_cumhaz]{hzr_phase_cumhaz()}} and \code{\link[=hzr_phase_hazard]{hzr_phase_hazard()}} for computing
\eqn{\Phi(t)} and \eqn{\phi(t)} from these specifications.

\code{vignette("fitting-hazard-models")} for multiphase fitting examples,
\code{vignette("mf-mathematical-foundations")} for the mathematical framework.
}
