% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ipw_ests.R
\name{coxph_indtrunc}
\alias{coxph_indtrunc}
\alias{vcov.coxph_indtrunc}
\alias{coef.coxph_indtrunc}
\alias{confint.coxph_indtrunc}
\alias{residuals.coxph_indtrunc}
\alias{print.coxph_indtrunc}
\title{Cox regression under quasi-independent double truncation.}
\usage{
coxph_indtrunc(
  formula,
  data = NULL,
  strata_formula = NULL,
  ipw_type = c("W-asurv", "W-surv", "W-1", "W-a"),
  se = TRUE,
  robust_se = TRUE,
  basehaz = FALSE,
  restr_times = NULL,
  npmle_fit = NULL,
  robust_infl = NULL,
  simple_labels = FALSE,
  keep_x = FALSE
)

\method{vcov}{coxph_indtrunc}(object, ...)

\method{coef}{coxph_indtrunc}(object, ...)

\method{confint}{coxph_indtrunc}(object, parm, level = 0.95, ...)

\method{residuals}{coxph_indtrunc}(
  object,
  type = c("martingale", "deviance"),
  per_subject = type == "deviance",
  ...
)

\method{print}{coxph_indtrunc}(x, ...)
}
\arguments{
\item{formula}{A model formula with a \code{Survdt} or \code{Survdt2} response.
Subjects with any missing values are discarded.
See \code{\link[=Survdt]{Survdt()}} and \code{\link[=Survdt2]{Survdt2()}}.}

\item{data}{An optional data frame used to evaluate \code{formula} and
\code{strata_formula}.}

\item{strata_formula}{An optional one-sided formula with stratification
variables on the right hand side, to fit a stratified Cox model.}

\item{ipw_type}{Type of inverse probability weights.
\enumerate{
\item \code{"W-asurv"} (the default): stabilized robust time-varying weights based
on the NPMLE survival function.
\item \code{"W-surv"}: robust time-varying weights based on the NPMLE survival function.
\item \code{"W-1"}: standard weights with no time-varying component (Rennert and Xie, 2018)
\item \code{"W-a"}: stabilized weights (Mandel et al., 2018)
\item For custom time-varying weights, provide a function that takes a numerical
vector of times as input and returns a numerical vector of positive weights.
}}

\item{se}{Whether to calculate standard errors (default \code{TRUE}).}

\item{robust_se}{Whether to calculate standard errors that are robust to
model misspecification (default \code{TRUE}).
Ignored if \code{se}=\code{FALSE}.}

\item{basehaz}{Whether to return the baseline hazard estimate
(default \code{FALSE}).}

\item{restr_times}{An optional numerical vector of length two giving a time
window to restrict the score function.
Values of \code{NA} are replaced with the minimum and maximum observed event
time respectively, i.e. no restriction.
The default setting is no restriction.}

\item{npmle_fit}{An optional pre-computed \code{npmle} object fit on the complete
cases.
If it was fit with \code{ainv}=\code{FALSE} (or \code{infl}=\code{FALSE} when \code{se}=\code{TRUE}) then
it is ignored and a new NPMLE is fit.
See \code{\link[=npmle]{npmle()}}.}

\item{robust_infl}{A square matrix of influence values for the event weight,
with one column per individual and one row per follow up time, both in the
order that the subject appears in the response variable.
Only used if \code{ipw_type} is a function and \code{robust_se}=\code{TRUE}.}

\item{simple_labels}{Whether to drop the factor names from the stratum labels
(Default \code{FALSE}).}

\item{keep_x}{Whether to include the model matrix in the \code{cox_fit} component
of the return value (Default \code{FALSE}).}

\item{object, x}{A \code{coxph_indtrunc} object.}

\item{...}{Additional arguments passed to other methods.}

\item{parm}{A numeric or character vector specifying a set of model
parameters.
Defaults to all identifiable (non-missing) coefficients.}

\item{level}{Confidence level for confidence intervals.}

\item{type}{The type of residuals to return.}

\item{per_subject}{Whether to return per-subject residuals as opposed to
per-observation residuals, for models with \code{Survdt2} data.
Defaults to \code{TRUE} for deviance residuals and \code{FALSE} otherwise.}
}
\value{
\code{\link[=coxph_indtrunc]{coxph_indtrunc()}} returns an object of class \code{coxph_indtrunc}, i.e. a list
with the following components:
\item{n}{The complete case sample size.}
\item{n_miss}{The number of individuals removed due to missing data.}
\item{n_event}{The number of observed events in the score function.}
\item{coef}{A four-column matrix containing the estimated coefficients,
standard errors, z-statistics, and p-values. Coefficient values of \code{NA}
indicate collinearity.}
\item{var_matrix}{The estimated variance matrix for the coefficient estimates.
Values of \code{NA} indicate collinearity.}
\item{robust_se}{The input value for \code{robust_se}.}
\item{offset}{The offsets from the model formula for complete case observations.}
\item{ipw}{The estimated inverse probability of non-truncation for each
complete case observation.}
\item{time_wt}{The time-varying component of the inverse probability weights
for each complete case observation.}
\item{cc_indx}{A logical index vector for the complete cases in the original
data.}
\item{id_indx}{A vector of ids matching each observation with a subject among
the complete cases.}
\item{sort_indx}{A numerical vector to sort the complete cases into the order
they are used in \code{cox_fit} (see below).}
\item{s}{The stratum value for each complete case observation if a stratified
Cox model was fit.
Otherwise \code{NULL}.}
\item{martingale_resid}{The weighted martingale residuals for the complete
cases, with one entry per observation.}
\item{deviance_resid}{The weighted deviance residuals for the complete cases,
with one entry per subject.}
\item{basehaz}{For input \code{basehaz}=\code{TRUE}, a list with first element \code{s}
containing the stratum values and one additional element for each stratum,
in the order of \code{s}.
Each contains a matrix with following columns:
\code{time}, \code{cumhaz} with the cumulative baseline hazard value (baseline at x=0),
\code{var_logcumhaz} with the estimated variance of the log(cumhaz), and
additional columns, labeled by predictor names, with the estimated covariance
between the log(cumhaz) and the regression coefficients.
For input \code{basehaz}=\code{FALSE}, \code{NULL}.}
\item{timerange}{A vector with the minimum and maximum times used in the
score function.}
\item{eventrange}{A vector with the unrestricted range of observed event times.}
\item{wt_name}{A string giving the name of the weights used in \code{ipw_type}.}
\item{cox_fit}{The \code{coxph} object used to obtain the estimates.
Note that the data was sorted by strata and time before fitting the model,
and the offset may include an additional term of \code{-log(time_wt)}.}
\item{strata_summary}{Some summary statistics for each stratum, computed
prior to applying \code{restr_times}.}
\item{call_}{The call to \code{\link[=coxph_indtrunc]{coxph_indtrunc()}}.}

\code{coxph_indtrunc} objects have methods for \code{vcov} to extract the variance matrix
of estimated coefficients, \code{coef} to extract the estimated coefficients,
\code{confint} to compute confidence intervals for coefficients, \code{residuals} for
model diagnostics, and \code{print} to display a summary of the fitted model.

\code{residuals} returns per-subject residuals in the order that the subject first
appeared in the original data.
The deviance residuals are computed as
\eqn{\text{sign}(\widehat{M}_{wi})\sqrt{
-2[\widehat{M}_{wi} +
\delta_{wi}\log(1 - \widehat{M}_{wi}/\delta_{wi})]}}
where \eqn{\widehat{M}_{wi}} is the weighted martingale residual and
\eqn{\delta_{wi}} is the weighted event indicator, following
Therneau et al. (1990).
}
\description{
Computes an inverse probability weighted Cox regression estimator using
nonparametric weights (see \code{\link[=npmle]{npmle()}}).
Includes options for robust estimators with time-varying weights, which
introduce an event time stabilization weight (see below).
}
\details{
Given a sample of doubly truncated data with event times \eqn{T_i}, truncation
times \eqn{L_i} and \eqn{R_i}, and potentially time-varying covariates
\eqn{X_i(t)}, let \eqn{N_i(t)=1(T_i \leq t)} be the usual counting process
and \eqn{Y_i(t)=1(T_i \geq t)} be the at-risk process.

\code{\link[=coxph_indtrunc]{coxph_indtrunc()}} fits a Cox model by maximizing an inverse probability
weighted partial likelihood, where the double truncation bias is accounted
for through nonparametric estimates of
\eqn{a(t)^{-1}=P(L<T \leq R)/P(L<T \leq R|T=t)} (see \code{\link[=npmle]{npmle()}}).
Assuming \code{strata_formula=NULL} for sake of illustration, setting
\code{ipw_type="W-1"} specifies non-time-varying weights, so the model is fitted by
finding the root of the weighted score function
\deqn{\sum_{i}\int \frac{1}{\widehat{a}(T_i)}
      [X_i(t) - \overline{X}_{\widehat{a}}(t,\beta)]dN_i(t)}
\deqn{\text{where } \overline{X}_{\widehat{a}}(t,\beta)
      = \frac{\sum_j X_j(t)\widehat{a}(T_j)^{-1}Y_j(t)\exp(X_j(t)^T\beta)}
             {\sum_j \widehat{a}(T_j)^{-1}Y_j(t)\exp(X_j(t)^T\beta)}.}

More generally, \code{\link[=coxph_indtrunc]{coxph_indtrunc()}} allows for time-varying weights with a
stabilization component \eqn{\widehat{w}(t)} that determines the relative
importance of each event time.
This can improve robustness and numerical convergence without introducing any
bias, in contrast to weight truncation, for example.
The weighted score function becomes
\deqn{\sum_{i}\int \frac{\widehat{w}(t)}{\widehat{a}(T_i)}
      [X_i(t) - \overline{X}_{\widehat{a}}(t,\beta)]dN_i(t).}
Several choices of time-varying weights are available:
\itemize{
\item \code{ipw_type="W-surv"}: \eqn{\widehat{w}(t)=\widehat{S}(t-)}, where
\eqn{\widehat{S}(t)} is the marginal survival function estimated by
\code{\link[=npmle]{npmle()}}.
Can increase robustness to outliers.
\item \code{ipw_type="W-a"}: \eqn{\widehat{w}(t)=\widehat{a}(t)}.
Can reduce the influence of extreme inverse probability weights.
\item \code{ipw_type="W-asurv"}: \eqn{\widehat{w}(t)=\widehat{a}(t)\widehat{S}(t-)}.
Combines the benefits of both weights.
\item Custom stabilization weights \eqn{\widehat{w}(t)} can be specified by
supplying a function as the input to \code{ipw_type}.
If \code{robust_se=TRUE}, this also requires the influence values for
\eqn{\widehat{w}(t)} to be supplied in \code{robust_infl}, in order to account
for its variability in the standard errors.
}
}
\section{Stratified Cox model}{


A stratified Cox model is specified through \code{strata_formula}.
The formula should look like \code{~svar1 + svar2}... where \code{svar1} and \code{svar2} are
factor variables defining the strata.
This allows the baseline hazard to differ across strata.
}

\section{Restricted time window in score function}{

The user can choose to restrict the time range of the score function during
estimation.
This may be useful when extreme event times have very large weights.
Setting the input argument \code{restr_times=c(t1,t2)} will restrict the range of
the integrals in the score function to the interval \eqn{[}\code{t1}, \code{t2}\eqn{]}
instead of the entire event time range.
Notably, this time restriction will not introduce any bias in the fitted model.
}

\examples{
coxph_indtrunc(Survdt(incu, ltrunc, rtrunc) ~ age_gp,
               data = aids)

}
\references{
Mandel, M., de Uña-Álvarez, J., Simon, D. K., & Betensky, R. A. (2018).
Inverse probability weighted Cox regression for doubly truncated data.
\emph{Biometrics}, \strong{74}(2), 481--487.

Rennert, L., & Xie, S. X. (2018). Cox regression model with doubly truncated
data. \emph{Biometrics}, \strong{74}(2), 725--733.

Therneau, T. M., Grambsch, P. M., & Fleming, T. R. (1990). Martingale-based
residuals for survival models. \emph{Biometrika}, \strong{77}(1), 147--160.

Vazquez, O., & Xie, S. X. (2025). Robust inverse probability weighted
estimators for doubly truncated Cox regression with closed-form standard
errors. \emph{Lifetime Data Analysis}, \strong{31}(2), 364–-393.
}
\seealso{
\itemize{
\item \code{\link[=plot_coxsurv]{plot_coxsurv()}}: compute/plot estimates and pointwise confidence intervals
for the conditional survival function or cumulative hazard from a fitted Cox
model.
\item \code{\link[=positivity_sens_indtrunc]{positivity_sens_indtrunc()}}: sensitivity analysis for positivity violations
in the Cox model.
\item \code{\link[=test_quasiindep_covariates]{test_quasiindep_covariates()}}: test for dependence between truncation times
and the event time or covariates.
The nonparametric weights used by \code{\link[=coxph_indtrunc]{coxph_indtrunc()}} requires quasi-independence.
\item \code{vignette("cox-regression-quasiindep", package = "survdt")}: an
illustration of Cox regression and related diagnostics applied to the
\link{aids} data, if vignettes were built when installing \link{survdt}.
}
}
