% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/npests.R
\name{test_ignorability_indtrunc}
\alias{test_ignorability_indtrunc}
\alias{plot.ignorability_indtrunc_test}
\alias{print.ignorability_indtrunc_test}
\title{Test for non-ignorable sampling bias}
\usage{
test_ignorability_indtrunc(
  y,
  data = NULL,
  test_type = c("sel_prob", "cdf"),
  level = 0.95,
  B = 2000,
  restr_times = NULL,
  wt_fn = NULL
)

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

\method{print}{ignorability_indtrunc_test}(x, ...)
}
\arguments{
\item{y}{A \code{Survdt} object or expression, or an \code{npmle} object. Observations
with missing values are discarded.
See \code{\link[=Survdt]{Survdt()}} and \code{\link[=npmle]{npmle()}}.}

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

\item{test_type}{The test statistic to use: \code{"sel_prob"} (default) or \code{"cdf"}.
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{x}{Any R object.}

\item{...}{Additional arguments passed to other methods.}
}
\value{
\code{\link[=test_ignorability_indtrunc]{test_ignorability_indtrunc()}} returns an object of class
\code{ignorability_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 resulted in rejecting the null hypothesis
of ignorable sampling bias.}
\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{ests}{A data frame of estimates to be used by
\code{\link[=plot.ignorability_indtrunc_test]{plot.ignorability_indtrunc_test()}}.}

The \code{print} method for \code{ignorability_indtrunc_test} objects displays a summary
of the test results, while the \code{plot} method returns a visualization comparing
the NPMLE and its reference value under the null hypothesis using a uniform
confidence band, generated through \code{\link[ggplot2:ggplot]{ggplot2::ggplot()}}.
}
\description{
Implements two possible nonparametric tests for non-ignorable sampling bias
based on the NPMLE:
\enumerate{
\item check for non-constant selection probabilities across the event time range;
\item check for a difference between the estimated event time cumulative
distribution functions adjusted and not adjusted for double truncation.
}

Typically used to determine if a doubly truncated sample must be analyzed
with methods that account for truncation bias.
}
\details{
The sampling bias from double truncation is called ignorable when the
selection (non-truncation) probability is constant over all possible event
times.
Since all event times have an equal probability of being included in the sample,
the sampling mechanism does not alter their distribution, so standard analysis
methods can be applied to the data.

Define the normalized selection probability at any time \eqn{t} by
\eqn{a(t) = P(L<T \leq R|T=t)/P(L<T \leq R)}.
Its estimate \eqn{\widehat{a}(t)} is a left-continuous step function with
jumps at the observed truncation times.
By default, \code{\link[=test_ignorability_indtrunc]{test_ignorability_indtrunc()}} tests for non-ignorable sampling
bias through the test statistic
\deqn{\sup_{\min_i T_i \leq t \leq \max_i T_i} |\widehat{a}(t) - 1|}
with the p-value computed by simulating from the estimated asymptotic null
distribution.
Another option is to compare two estimated event time cdfs: the NPMLE
\eqn{\widehat{F}(t)} which adjusts for double truncation and the empirical
cdf \eqn{\widehat{F}^*(t)} which does not adjust for double truncation.
The test statistic would then be
\deqn{\sup_t |\widehat{F}(t) - \widehat{F}^*(t)|.}
}
\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{
igtest <- test_ignorability_indtrunc(Survdt(incu, ltrunc, rtrunc),
                                     data = aids)
igtest
plot(igtest)

}
\references{
de Uña‐Álvarez, J. (2023). Testing for an ignorable sampling bias under random
double truncation. \emph{Statistics in Medicine}, \strong{42}(20), 3732--3744.

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 ignorability tests applied to the \link{aids} data, if vignettes were built
when installing \link{survdt}.
}
}
