% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/npests.R
\name{test_quasiindep_covariates}
\alias{test_quasiindep_covariates}
\alias{plot.quasiindep_strat_test}
\alias{print.quasiindep_strat_test}
\title{Test for dependence between truncation times and the event time or covariates}
\usage{
test_quasiindep_covariates(
  formula,
  data = NULL,
  level = 0.95,
  B = 2000,
  restr_times = NULL,
  wt_fn = NULL,
  max_iter = NULL,
  simple_labels = FALSE
)

\method{plot}{quasiindep_strat_test}(x, level, ...)

\method{print}{quasiindep_strat_test}(x, ...)
}
\arguments{
\item{formula}{A formula with a \code{Survdt} response and stratification variables
on the right hand side.
Note that subtraction will not remove stratification variables here.
Subjects with missing values are discarded.
See \code{\link[=Survdt]{Survdt()}}.}

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

\item{level}{The confidence level for the test (default 0.95).}

\item{B}{The number of simulations from the estimated null distribution used
to compute the p-value (default 2000).}

\item{restr_times}{An optional numerical vector of length two giving a time
window to restrict the test statistic.
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{wt_fn}{An optional function that takes a numerical vector of times as
input and returns a vector of weights to apply in the test statistic.
If unspecified, all times have equal weight of 1.}

\item{max_iter}{The maximum number of iterations to use within each call to
\code{\link[=npmle]{npmle()}}. If missing then the default setting of \code{\link[=npmle]{npmle()}} is used.}

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

\item{x}{Any R object.}

\item{...}{Additional arguments passed to other methods.}
}
\value{
An object of class \code{quasiindep_strat_test}, i.e. a list with the following
components:
\item{n}{The complete case sample size.}
\item{n_unique}{The number of unique event times among complete cases.}
\item{n_miss}{The number of discarded observations (with missing values).}
\item{teststat}{The value of the observed test statistic for the across-strata
test (stage 2).}
\item{pval}{The p-value for the across-strata test.}
\item{critval}{The critical value for the across-strata test at the
user-specified level.}
\item{testresult}{Whether the across-strata test results in rejecting the null
hypothesis of quasi-independence.}
\item{sims}{A vector of the \code{B} simulations from the estimated null distribution
of the across-strata test statistic.}
\item{level}{The user-supplied \code{level}.}
\item{B}{The number of simulations specified by the user.}
\item{timerange}{A vector with the minimum and maximum times used in the
across-strata test.}
\item{wt_name}{A string giving the name of the user-suppled \code{wt_fn}, if any.}
\item{eventrange}{A vector with the unrestricted range of observed event times.}
\item{strata_ests}{A data frame of estimates to be used by
\code{\link[=plot.quasiindep_strat_test]{plot.quasiindep_strat_test()}}.}
\item{strata_ctau}{A data frame of the within-strata test results (stage 1).
Includes stratum-specific tests by conditional Kendall's tau as well as the
aggregate p-value for testing within-strata quasi-independence in all strata
simultaneously.}

The \code{print} method for \code{quasiindep_strat_test} objects displays a summary of the
test results, while the \code{plot} method returns a visualization comparing the
stratified and unstratified NPMLE from stage 2 using a uniform confidence band,
generated through \code{\link[ggplot2:ggplot]{ggplot2::ggplot()}}.
}
\description{
Implements a two-stage test for dependence between the truncation times and
the event time and covariates that first tests within covariate strata and then
across strata.

Typically used to check the underlying assumptions for inverse probability
weighted regression with NPMLE weights, e.g. as used in \code{\link[=coxph_indtrunc]{coxph_indtrunc()}}.
}
\details{
Implements a nonparametric test for dependent truncation to check if the
selection probability depends on either the event times or covariates.
The test has two stages:
\enumerate{
\item Test for dependence between event and truncation times stratified by
covariate groups using conditional Kendall's tau
(see \code{\link[=test_quasiindep_ctau]{test_quasiindep_ctau()}}).
The aggregate p-value for this stage is computed from a chi-squared
distribution.
\item Test whether the selection probability depends on covariates by comparing
the stratified and unstratified selection probabilities estimated using the
NPMLE.
Let \eqn{\widehat{\pi}(t|s)} be the estimate in stratum \eqn{s}, and
\eqn{\widehat{\pi}(t)} be the unstratified estimate.
Both are left-continuous step functions with jumps at observed truncation
times.
By default, \code{\link[=test_quasiindep_covariates]{test_quasiindep_covariates()}} uses the test statistic
\deqn{\max_s\sup_{\min_i T_i\leq t \leq \max_i T_i}
         |\widehat{\pi}(t|s)-\widehat{\pi}(t)|}
to compare selection probabilities across strata.
The p-value for this stage is computed by simulating from the estimated
asymptotic null distribution.
}
}
\section{Restricted time window and weighted tests}{

When the NPMLE has high variance at extreme event times, the test may suffer
from reduced power.
One possible remedy is to restrict the time range of the test to some interval
\eqn{[\tau_1, \tau_2]} contained in \eqn{[\min_i T_i, \max_i T_i]}.
Another option is to down-weight event times with large variance through a
weight function \eqn{w(t)}.
The stabilized test statistic will have the form
\deqn{\sup_{\tau_1 \leq t \leq \tau_2} |w(t)(\widehat{h}(t) - h(t))|}
where \eqn{\widehat{h}(t)} is the NPMLE without assuming the null hypothesis
holds and \eqn{h(t)} is the reference value under the null.
See \code{vignette("nonparametric-analysis", package = "survdt")} for an illustration
with the \link{aids} data assuming vignettes were built when installing \link{survdt}.
}

\section{No effective truncation}{

A doubly truncated sample has no effective truncation when
\eqn{\max_i L_i < \min_i T_i} and \eqn{\max_i T_i \leq \min_i R_i}.
The estimated selection probability is equal to one across all event times
in this case, and its standard errors may not be reliable.
Typically one would conclude that the truncation mechanism is ignorable in
these types of samples, so standard methods can be applied for data analysis.
}

\examples{
indtest <- test_quasiindep_covariates(Survdt(incu, ltrunc, rtrunc) ~ age_gp,
                                      data = aids)
indtest
plot(indtest)

}
\references{
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[=test_quasiindep_ctau]{test_quasiindep_ctau()}}: the conditional Kendall's tau test for quasi-dependence
without covariates, which is the basis for stage 1.
\item \code{\link[=npmle]{npmle()}}: the nonparametric maximum likelihood estimator which is the basis
for stage 2.
\item \code{vignette("cox-regression-quasiindep", package = "survdt")}: an illustration
of this quasi-independence test applied to the \link{aids} data, if vignettes were
built when installing \link{survdt}.
}
}
