% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cox.rvph.R
\name{cox.rvph}
\alias{cox.rvph}
\title{cox.rvph (Remedy for Violations of the Proportional Hazards Assumption of Cox regression)}
\usage{
cox.rvph(
  data,
  time,
  event,
  covariate,
  adjust_vars = NULL,
  method = c("step", "timev"),
  g_candidates = NULL,
  max_K = 4,
  p_threshold = 0.05,
  verbose = TRUE
)
}
\arguments{
\item{data}{dataset}

\item{time}{time variable}

\item{event}{event indicator}

\item{covariate}{covariate that violates the proportional hazards assumption}

\item{adjust_vars}{optional adjustment variables}

\item{method}{"step" or "timev"}

\item{g_candidates}{A list of candidate time functions
used in the time-varying coefficient method.
If NULL, a default set of candidate functions
(linear, log, sqrt, quadratic, inverse, and scaled)
is used. Users may also supply custom transformation functions.}

\item{max_K}{maximum number of segments}

\item{p_threshold}{threshold for PH test}

\item{verbose}{logical; whether to print progress messages}
}
\value{
list containing model results
}
\description{
Stepwise or time-varying remedies for proportional hazards assumption violations of a cox regression model
}
\details{
Users should first assess the proportional hazards (PH) assumption
using \code{cox.zph()} before applying \code{cox.rvph()}.
Variables showing evidence of non-proportional hazards may then be modeled using stepwise or time-varying remedies.

The \code{step} method performs segmented modeling by searching
for optimal cut points in time by maximizing the partial likelihood. 
The selected cut points are incorporated into the Cox model
through time-dependent interval-specific covariates using the
counting-process formulation.
If the resulting model satisfies
the PH assumption with relatively few cut points, hazard ratios (HRs)
may be interpreted within each estimated time interval.

However, if many cut points are required or PH violations persist,
a smooth time-varying effect may be more appropriate. In such cases,
the \code{timev} method fits several candidate time-transformation
functions \eqn{g(t)} and selects the model with the smallest AIC.
By default, the following candidate functions are evaluated:
linear (\eqn{t}),
log (\eqn{\log(t+1)}),
sqrt (\eqn{\sqrt{t}}),
quadratic (\eqn{t^2}),
inverse (\eqn{1/(t+1)}),
and scaled (\eqn{t/\max(t)}).
Users may alternatively provide their own candidate functions
through the g_candidates argument.

For the selected time-varying model, the hazard ratio at time
\eqn{t} is given by:

\deqn{
HR(t) = \exp(\beta + \gamma g(t))
}

where \eqn{\beta} is the baseline coefficient and
\eqn{\gamma} represents the time-varying interaction effect.
Users may evaluate this expression at clinically relevant time points
to interpret how the hazard ratio changes over time.

Interpretation:
For the \code{step} method, hazard ratios are interpreted
separately within each estimated time interval.

Example output (method: step):

\preformatted{
$K
[1] 2

$tau
[1] 2.35

$p_value

[1] 0.7042976

$zph
                chisq df    p
covariate_seg1 0.0546  1 0.82
covariate_seg2 0.1630  1 0.69
age            1.2196  1 0.27
GLOBAL         1.4053  3 0.70

$fit
Call:
survival::coxph(formula = as.formula(f_str_final), data = final_data)

                   coef exp(coef) se(coef)     z        p
covariate_seg1 0.90130   2.46281  0.21302 4.231 2.33e-05
covariate_seg2 0.06103   1.06293  0.21348 0.286    0.775
}

Interpretation (method: step):

For the \code{step} method, hazard ratios are interpreted
separately within each estimated time interval.
Interpretation:

\verb{covariate_seg1  HR = 2.46}

\verb{covariate_seg2  HR = 1.06}

If the estimated cut point is \eqn{\tau = 2.35}, this indicates
that before time 2.35 the hazard is approximately 2.46 times higher,
whereas after time 2.35 the hazard ratio decreases to approximately 1.06.

Example output (method: timev):

\preformatted{
$selected_g
[1] "sqrt"

$fit

                 coef exp(coef)  se(coef)      z        p
protime      0.693216  2.000137  0.132824  5.219 1.80e-07
tt(protime) -0.013456  0.986634  0.003959 -3.399 0.000677
bili         0.118716  1.126050  0.012860  9.231  < 2e-16
.
.

}

Interpretation (method: timev):

For the \code{timev} method, hazard ratios vary continuously over time.

Example model:

\deqn{
HR(t) = \exp(0.693 - 0.013 \sqrt{t})
}

This indicates that the hazard ratio decreases gradually over time.
Users may substitute clinically meaningful values of \eqn{t}
to estimate hazard ratios at specific time points.
}
\examples{
if (requireNamespace("KMsurv", quietly = TRUE)) {
  data(larynx, package = "KMsurv")

  cox.rvph(
    data = larynx,
    time = "time",
    event = "delta",
    covariate = "stage",
    adjust_vars = "age",
    method = "step"
  )
}
}
