% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/TemporalHazard-package.R
\docType{package}
\name{TemporalHazard-package}
\alias{TemporalHazard}
\alias{TemporalHazard-package}
\title{TemporalHazard: Temporal Parametric Hazard Modeling}
\description{
Native R implementation of the multiphase parametric hazard model of
Blackstone, Naftel, and Turner (1986), with a focus on behavioral parity,
transparent numerics, and reproducible validation against the original
\sQuote{C}/\sQuote{SAS} HAZARD program.  The package fits time-varying hazards
as an additive sum of parametric \emph{phases} --- early, constant, and late risk
streams --- each carrying its own covariate effects.
}
\section{The multiphase model}{


The total cumulative hazard decomposes additively across \eqn{J} phases:

\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 (intercept plus
covariate effects) and \eqn{\Phi_j(t)} is the temporal shape contributed by
phase \eqn{j}, with its own parameters depending on the phase \code{type} (see the
phase vocabulary below).  The instantaneous hazard and survival follow
directly:

\deqn{h(t \mid \mathbf{x}) = \sum_{j=1}^{J} \mu_j(\mathbf{x}) \,
      \varphi_j(t), \qquad
      S(t \mid \mathbf{x}) = \exp\!\bigl(-H(t \mid \mathbf{x})\bigr)}

with \eqn{\varphi_j = d\Phi_j/dt}.  Each phase is specified with
\code{\link[=hzr_phase]{hzr_phase()}} and the model is fit by maximum likelihood with \code{\link[=hazard]{hazard()}}.
}

\section{Phase vocabulary}{


\tabular{llll}{
\strong{Phase type} \tab \strong{\eqn{\Phi_j(t)}} \tab \strong{Domain} \tab \strong{Use} \cr
\code{"cdf"} \tab \eqn{G(t)} \tab \eqn{[0, 1]} \tab Early risk that resolves over time \cr
\code{"hazard"} \tab \eqn{-\log(1 - G(t))} \tab \eqn{[0, \infty)} \tab Late or aging risk that accumulates \cr
\code{"g3"} \tab \eqn{G_3(t)} \tab \eqn{[0, \infty)} \tab Unbounded late risk (original C/SAS late phase) \cr
\code{"constant"} \tab \eqn{t} \tab \eqn{[0, \infty)} \tab Flat background rate (no shape parameters) \cr
}

Here \eqn{G(t)} is the generalized temporal decomposition CDF computed by
\code{\link[=hzr_decompos]{hzr_decompos()}}, and \eqn{G_3(t)} is the unbounded late-phase intensity from
\code{\link[=hzr_decompos_g3]{hzr_decompos_g3()}}.  See \code{vignette("mf-mathematical-foundations")} for the
full derivation.
}

\section{SAS/C HAZARD bridge}{


The classic three-phase HAZARD model maps directly onto \code{hzr_phase()} calls:

\tabular{lll}{
\strong{HAZARD phase} \tab \strong{Role} \tab \strong{R equivalent} \cr
G1 (early)    \tab Early resolving risk \tab \code{hzr_phase("cdf", ...)} \cr
G2 (constant) \tab Flat background rate \tab \code{hzr_phase("constant")} \cr
G3 (late)     \tab Rising late risk     \tab \code{hzr_phase("g3", ...)} \cr
}

TemporalHazard generalizes the fixed three-phase structure to \eqn{N} phases
of any type.  \code{\link[=hzr_argument_mapping]{hzr_argument_mapping()}} gives the full parameter translation
table between the SAS/C parameterization and the R arguments.
}

\section{Main entry points}{


\describe{
\item{Model fitting}{\code{\link[=hazard]{hazard()}} --- build and fit single- or multiphase
models; \code{\link[=hzr_phase]{hzr_phase()}} --- specify one phase; \code{\link[=hzr_stepwise]{hzr_stepwise()}} --- forward,
backward, or bidirectional covariate selection.}
\item{Prediction}{\code{predict()} on a fitted \code{hazard} object --- survival,
cumulative hazard, and per-phase decomposed hazard; \code{summary()} ---
coefficient tables with Wald inference.}
\item{Parametric family}{\code{\link[=hzr_decompos]{hzr_decompos()}} --- the early-phase (G1)
decomposition \eqn{G(t)}, \eqn{g(t)}, \eqn{h(t)}; \code{\link[=hzr_decompos_g3]{hzr_decompos_g3()}} ---
the late-phase (G3) intensity; \code{\link[=hzr_phase_cumhaz]{hzr_phase_cumhaz()}} and
\code{\link[=hzr_phase_hazard]{hzr_phase_hazard()}} --- per-phase \eqn{\Phi(t)} and \eqn{\varphi(t)}.}
\item{Diagnostics}{\code{\link[=hzr_kaplan]{hzr_kaplan()}}, \code{\link[=hzr_nelson]{hzr_nelson()}} --- nonparametric
references; \code{\link[=hzr_gof]{hzr_gof()}} --- goodness of fit; \code{\link[=hzr_calibrate]{hzr_calibrate()}},
\code{\link[=hzr_deciles]{hzr_deciles()}} --- calibration; \code{\link[=hzr_bootstrap]{hzr_bootstrap()}} --- resampling CIs;
\code{\link[=hzr_competing_risks]{hzr_competing_risks()}} --- cumulative incidence.}
}
}

\section{Vignettes}{


\describe{
\item{\code{vignette("getting-started")}}{First fit, end to end.}
\item{\code{vignette("mf-mathematical-foundations")}}{The decomposition family
and multiphase model, with derivations.}
\item{\code{vignette("fitting-hazard-models")}}{Single-phase through multiphase
fitting.}
\item{\code{vignette("prediction-visualization")}}{Prediction types and
decomposed-hazard plots.}
\item{\code{vignette("inference-diagnostics")}}{Bootstrap CIs and diagnostics.}
\item{\code{vignette("sas-to-r-migration")}}{Translating SAS/C HAZARD code.}
}
}

\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{
Useful links:
\itemize{
  \item \url{https://ehrlinger.github.io/temporal_hazard/}
  \item \url{https://github.com/ehrlinger/temporal_hazard}
  \item Report bugs at \url{https://github.com/ehrlinger/temporal_hazard/issues}
}

}
\author{
\strong{Maintainer}: John Ehrlinger \email{john.ehrlinger@gmail.com} [copyright holder]

Authors:
\itemize{
  \item John Ehrlinger \email{john.ehrlinger@gmail.com} [copyright holder]
}

}
\keyword{internal}
