% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/npests.R
\name{test_samplediff_indtrunc}
\alias{test_samplediff_indtrunc}
\alias{plot.samplediff_indtrunc_test}
\alias{print.samplediff_indtrunc_test}
\title{Test for survival differences across groups}
\usage{
test_samplediff_indtrunc(
  formula,
  data = NULL,
  test_type = c("survival", "cumhaz"),
  level = 0.95,
  B = 2000,
  restr_times = NULL,
  wt_fn = NULL,
  max_iter = NULL,
  simple_labels = FALSE
)

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

\method{print}{samplediff_indtrunc_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{test_type}{The test statistic to use: \code{"survival"} (default) or
\code{"cumhaz"}.
See below.}

\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{
\code{\link[=test_samplediff_indtrunc]{test_samplediff_indtrunc()}} returns an object of class
\code{samplediff_indtrunc_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.}
\item{pval}{The p-value for the test.}
\item{critval}{The critical value for the test at the user-specified level.}
\item{testresult}{Whether the test results in rejecting the null
hypothesis of no differences across strata.}
\item{sims}{A vector of the \code{B} simulations from the estimated null
distribution of the test statistic.}
\item{test_type}{The matched \code{test_type} value.}
\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 test.}
\item{wt_name}{A string giving the name of the user-supplied \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.samplediff_indtrunc_test]{plot.samplediff_indtrunc_test()}}.}
\item{strata_summary}{Some summary statistics for each stratum.}

The \code{print} method for \code{samplediff_indtrunc_test} objects displays a summary
of the test results, while the \code{plot} method returns a visualization comparing
the stratified and unstratified NPMLE using a uniform confidence band,
generated through \code{\link[ggplot2:ggplot]{ggplot2::ggplot()}}.
}
\description{
Tests for any difference in event time distribution by comparing
the stratified and unstratified estimates obtained using the NPMLE.
}
\details{
Let \eqn{\widehat{S}(t|s)} be the NPMLE for the survival function in stratum
\eqn{s}.
By default, \code{\link[=test_samplediff_indtrunc]{test_samplediff_indtrunc()}} tests for event time distribution
differences through the test statistic
\deqn{\max_s\sup_{\min_i T_i \leq t \leq \max_i T_i} |\widehat{S}(t|s) - \widehat{S}(t)|}
where \eqn{\widehat{S}(t)} is the unstratified NPMLE.
Another option is to compare the stratified cumulative hazards
\eqn{\widehat{\Lambda}(t|s)} with the unstratified NPMLE \eqn{\widehat{\Lambda}(t)}
through the test statistic
\deqn{\max_s\sup_{\min_i T_i \leq t \leq \max_i T_i}
      |\widehat{\Lambda}(t|s) - \widehat{\Lambda}(t)|.}
The p-value in all cases 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}.
}

\examples{
difftest <- test_samplediff_indtrunc(Survdt(incu, ltrunc, rtrunc) ~ age_gp,
                                     data = aids,
                                     restr_times = c(NA, 70))
difftest
plot(difftest)

}
\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[=npmle]{npmle()}}: the nonparametric maximum likelihood estimator which forms the
basis for these tests.
\item \code{vignette("nonparametric-analysis", package = "survdt")}: an illustration
of group tests applied to the \link{aids} data, if vignettes were built when
installing \link{survdt}.
}
}
