% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/decomposition.R
\name{hzr_decompos}
\alias{hzr_decompos}
\title{Generalized temporal decomposition}
\usage{
hzr_decompos(time, t_half, nu, m)
}
\arguments{
\item{time}{Numeric vector of times (must be > 0).}

\item{t_half}{Half-life: time at which \eqn{G(t_{1/2}) = 0.5}.
Must be > 0.}

\item{nu}{Time exponent controlling rate dynamics.
SAS early: \code{NU}.  SAS late: relates to \code{GAMMA}/\code{ETA}.}

\item{m}{Shape exponent controlling the distributional form.
SAS early: \code{M}.  SAS late: relates to \code{GAMMA}/\code{ALPHA}.}
}
\value{
A named list with three numeric vectors, each the same length
as \code{time}:
\describe{
\item{G}{Cumulative distribution \eqn{G(t) \in [0, 1]}.}
\item{g}{Density \eqn{g(t) = dG/dt \ge 0}.  The "early" phase
temporal pattern.}
\item{h}{Hazard \eqn{h(t) = g(t)/(1 - G(t)) \ge 0}.  The "late"
phase temporal pattern.}
}
}
\description{
Computes the cumulative distribution \eqn{G(t)}, density \eqn{g(t)}, and
hazard \eqn{h(t) = g(t)/(1 - G(t))} for the parametric family defined by
half-life, time exponent, and shape.  This single function generates all
temporal phase shapes used in multiphase hazard models.
}
\section{Parameter mapping from SAS/C HAZARD}{


The original C code used separate parameterizations for early (DELTA,
RHO/THALF, NU, M) and late (TAU, GAMMA, ALPHA, ETA) phases.  Both
collapse onto the three parameters here.  See
\code{\link[=hzr_argument_mapping]{hzr_argument_mapping()}} for the full translation table.
}

\section{Valid parameter combinations}{


Six cases are defined by the signs of \code{nu} and \code{m}:

\tabular{lll}{
\strong{Case} \tab \strong{Sign} \tab \strong{Behavior} \cr
1     \tab m > 0, nu > 0 \tab Standard sigmoidal \cr
1L    \tab m = 0, nu > 0 \tab Exponential-like (Weibull CDF) \cr
2     \tab m < 0, nu > 0 \tab Heavy-tailed \cr
2L    \tab m < 0, nu = 0 \tab Exponential decay \cr
3     \tab m > 0, nu < 0 \tab Bounded cumulative \cr
3L    \tab m = 0, nu < 0 \tab Bounded exponential \cr
}

The combination m < 0 \strong{and} nu < 0 is undefined and raises an error.
\code{nu = 0} is supported only with m < 0 (Case 2L, the exponential-decay
limit); \code{nu = 0} with m >= 0 has no usable limiting form and raises an
error.
}

\section{Mathematical form}{


The construction fixes a rate \eqn{\rho} so that \eqn{G(t_{1/2}) = 0.5}
exactly.  For the base case (\eqn{m > 0,\ \nu > 0}):

\deqn{\rho = \nu \, t_{1/2} \left(\frac{2^m - 1}{m}\right)^{\!\nu},
      \qquad b(t) = \frac{\nu t}{\rho}}

The CDF and density are then

\deqn{G(t) = \bigl(1 + m \, b(t)^{-1/\nu}\bigr)^{-1/m}, \qquad
      g(t) = \bigl(1 + m \, b(t)^{-1/\nu}\bigr)^{-1/m - 1}
             \, b(t)^{-1/\nu - 1} / \rho}

and the hazard is \eqn{h(t) = g(t) / (1 - G(t))}.  The remaining five cases
in the table above arise as limits (\eqn{m \to 0}, \eqn{\nu \to 0}) or sign
reflections of this base form; the implementation dispatches to the
appropriate branch after inspecting the signs of \code{nu} and \code{m}.  See
\code{vignette("mf-mathematical-foundations")} for the full derivation of every
case.
}

\examples{
t_grid <- seq(0.1, 10, by = 0.1)

# Case 1: standard sigmoidal (m > 0, nu > 0)
d1 <- hzr_decompos(t_grid, t_half = 3, nu = 2, m = 1)
plot(t_grid, d1$G, type = "l", main = "CDF (m=1, nu=2)")

# Case 1L: Weibull-like (m = 0, nu > 0)
d1L <- hzr_decompos(t_grid, t_half = 3, nu = 2, m = 0)

# Case 2: heavy-tailed (m < 0, nu > 0)
d2 <- hzr_decompos(t_grid, t_half = 3, nu = 2, m = -1)

}
\references{
Blackstone EH, Naftel DC, Turner ME Jr. The decomposition of time-varying
hazard into phases, each incorporating a separate stream of concomitant
information. \emph{J Am Stat Assoc.} 1986;81(395):615--624.
\doi{10.1080/01621459.1986.10478314}

Rajeswaran J, Blackstone EH, Ehrlinger J, Li L, Ishwaran H, Parides MK.
Probability of atrial fibrillation after ablation: Using a parametric
nonlinear temporal decomposition mixed effects model. \emph{Stat Methods Med Res.}
2018;27(1):126--141. \doi{10.1177/0962280215623583}
}
\seealso{
\code{\link[=hzr_phase_cumhaz]{hzr_phase_cumhaz()}} for the phase-level cumulative hazard
contribution, \code{\link[=hzr_argument_mapping]{hzr_argument_mapping()}} for SAS/C parameter mapping,
\code{\link[=hzr_phase]{hzr_phase()}} for specifying phases in \code{\link[=hazard]{hazard()}} models.

\code{vignette("mf-mathematical-foundations")} for the full derivation.
}
