% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ipw_ests.R
\name{positivity_sens_indtrunc}
\alias{positivity_sens_indtrunc}
\alias{print.coxph_pos_indtrunc}
\alias{plot.coxph_pos_indtrunc}
\title{Sensitivity analysis for positivity violations in a Cox model with
quasi-independent double truncation.}
\usage{
positivity_sens_indtrunc(
  formula,
  data = NULL,
  strata_formula = NULL,
  trunc_mass = seq(0, 0.9, by = 0.1),
  ipw_type = c("W-asurv", "W-surv", "W-1", "W-a"),
  se = TRUE,
  level = 0.95,
  restr_times = NULL,
  npmle_fit = NULL,
  robust_infl = NULL,
  max_iter = 100,
  error = 1e-07,
  beta_init = NULL,
  center_covariates = FALSE,
  simple_labels = FALSE
)

\method{print}{coxph_pos_indtrunc}(x, ...)

\method{plot}{coxph_pos_indtrunc}(x, parm, level, hazratio = FALSE, dropNA = TRUE, ...)
}
\arguments{
\item{formula}{A model formula with a \code{Survdt} response.
Subjects with missing values are discarded.
Time-varying covariates are not supported.
See \code{\link[=Survdt]{Survdt()}}.}

\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, for stratified Cox models.}

\item{trunc_mass}{A numerical vector containing the grid of truncated
baseline mass values to use in the sensitivity analysis.}

\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 (robust) standard errors (default \code{TRUE}).}

\item{level}{Confidence level for constructing sensitivity intervals
(default 0.95).}

\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 they appear in the data.
Only used if \code{ipw_type} is a function and \code{se}=\code{TRUE}.}

\item{max_iter}{Maximum number of iterations before non-convergence
is declared at a given truncated mass (default 100).}

\item{error}{Tolerance for determining numerical convergence of coefficient
estimates (default \code{1e-7}).}

\item{beta_init}{Optional numerical vector with initial values for each
coefficient estimate.}

\item{center_covariates}{Whether to center the covariates before the
sensitivity analysis (default \code{FALSE}).
Covariates with values of 0/1 are not centered.}

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

\item{x}{A \code{coxph_pos_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{hazratio}{Whether to plot the hazard ratios exp(beta) and their
sensitivity intervals instead of the regression coefficients beta (default
\code{FALSE}).}

\item{dropNA}{Whether to remove truncation masses where the estimator did not
converge, resulting in missing values, from the plot (default \code{TRUE}).}
}
\value{
\code{\link[=positivity_sens_indtrunc]{positivity_sens_indtrunc()}} returns an object of class \code{coxph_pos_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 used in the score function.}
\item{level}{The user-specified confidence level for constructing sensitivity
intervals.}
\item{trunc_mass}{The truncated baseline masses supplied in \code{trunc_mass}
(sorted).
The baseline covariate values are provided in \code{col_centerings}.}
\item{coef}{A matrix of coefficient estimates with \code{j}th column corresponding
to \code{trunc_mass[j]}.
Missing values indicate non-convergence or collinearity.}
\item{se}{A matrix of standard errors with \code{j}th column corresponding to
\code{trunc_mass[j]}.}
\item{lower,upper}{Matrices containing the lower and upper sensitivity
interval endpoints, with \code{j}th column corresponding to \code{trunc_mass[j]}.}
\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{col_centerings}{A numerical vector with the values used to center the
columns of the design matrix if \code{center_covariates}=\code{TRUE}.
Otherwise, a vector of zeros.}
\item{strata_summary}{Some summary statistics for each stratum, computed prior
to applying \code{restr_times}.}
\item{call_}{The call to \code{\link[=positivity_sens_indtrunc]{positivity_sens_indtrunc()}}.}

The \code{print} method for \code{coxph_pos_indtrunc} objects displays a summary of the
sensitivity analysis results, while the \code{plot} method returns a visualization
of the estimators and their sensitivity intervals across different truncated
mass values, generated through \code{\link[ggplot2:ggplot]{ggplot2::ggplot()}}.
}
\description{
Computes inverse probability weighted sensitivity analysis estimators for the
Cox model using nonparametric weights (see \code{\link[=npmle]{npmle()}}).
Given a grid of values for the potential amount of baseline probability mass
lost due to zero sampling probability, shows how a positivity violation could
influence the results of a fitted Cox model.
}
\details{
Consider a sample of doubly truncated data with event times \eqn{T_i},
truncation times \eqn{L_i} and \eqn{R_i}, and covariates \eqn{X_i}.

A positivity violation occurs when the sampling probability
\eqn{P(L<T \leq R|T=t)} is zero for \eqn{t\leq a} and \eqn{t > b}, where the
observation bounds \eqn{a}
and \eqn{b} lie within the event time support.
The truncated baseline probability mass is defined as the amount of probability
mass right-truncated by the positivity violation at the baseline covariate
level, conditional on not being left-truncated by the positivity violation,
i.e. \eqn{P(T> b|X=0,T > a)}.
Note that the interpretation of this truncated mass depends on how the baseline
covariate value is defined, e.g. whether the covariates are centered.

At each specified truncated mass, \code{\link[=positivity_sens_indtrunc]{positivity_sens_indtrunc()}} fits a Cox model
that accounts for the positivity violation through an adjustment to the
at-risk process (see Vazquez and Xie, 2025).
This modified at-risk process is inserted into the weighted score function from
\code{\link[=coxph_indtrunc]{coxph_indtrunc()}}.

The end result of the sensitivity analysis is a series of adjusted coefficient
estimators at the grid of truncated masses, which show how sensitive the Cox
model estimates are to potential positivity violations, as well as sensitivity
intervals giving a range of plausible values for the coefficients at the
user-supplied confidence \code{level} for each truncated mass.

In general, the sensitivity analysis estimators may not converge at
some truncated mass values.
Usually this is due to large weights, near-zero risk scores
\eqn{\exp(X_i^T\beta)}, and/or truncated masses too close to one.
Some options to consider are:
\itemize{
\item Changing the baseline covariate value by shifting the covariates or reordering
factor levels.
\item Using time-varying weights (see \code{ipw_type}).
\item Restricting the time window in the score function through \code{restr_times}
(see below).
\item Altering the range and step size of \code{trunc_mass}.
}
}
\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{
sensfit <- positivity_sens_indtrunc(Survdt(incu, ltrunc, rtrunc) ~ age_gp,
                                    data = aids,
                                    trunc_mass = seq(0, 0.11, by = 0.02),
                                    ipw_type = "W-asurv")
sensfit
plot(sensfit)

}
\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[=coxph_indtrunc]{coxph_indtrunc()}}: fitting a Cox model under quasi-independent truncation.
\item \code{vignette("cox-regression-quasiindep", package = "survdt")}: an illustration
of this sensitivity analysis applied to the \link{aids} data, if vignettes were
built when installing \link{survdt}.
}
}
