% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/coxiv_tsrif.R
\name{coxiv_tsrif}
\alias{coxiv_tsrif}
\title{Two-stage residual inclusion-frailty (TSRI-F) instrumental variable analysis of Cox model}
\usage{
coxiv_tsrif(surv, cens, trt, iv, covs, data, tchange = NULL,
            tvareff = FALSE, fdist = "gamma", bootvar = FALSE, B = 50)
}
\arguments{
\item{surv}{a string indicating variable name of survival time \eqn{T}.}

\item{cens}{a string indicating variable name of event indicator \eqn{D}: 1 for terminal event occurrence and 0 for right censor.}

\item{trt}{a string indicating the treatment variable name \eqn{A}. Binary or continuous treatment supported.}

\item{iv}{a string or vector of strings indicating instrumental variable(s) \eqn{Z}. Binary or continuous IV supported.}

\item{covs}{a string or vector of strings indicating set of measured covariates \eqn{X}.}

\item{data}{a \link[base]{data.frame} containing all variables needed.}

\item{tchange}{a positive numeric value specifying the time point at which the treatment effect changes value.}

\item{tvareff}{logical; by default \code{FALSE} and estimate a time-constant treatment effect model. If \code{TRUE}, a time-varying treatment effect model is applied.}

\item{fdist}{the frailty distribution, default is \code{gamma}. Other options include \code{gaussian} or \code{t} distribution. Read more about frailty distribution specification at \link[survival]{frailty}.}

\item{bootvar}{logical; if \code{TRUE}, bootstrap variance estimation is performed. Otherwise, analytical variance is provided from frailty Cox model.}

\item{B}{number of bootstrap iterations if \code{bootvar} is \code{TRUE}.}
}
\value{
A \code{coxivtsrif} object with following components:
\itemize{
\item \code{input} : collected input and derived model formulas used for the TSRI-F fit.
\item \code{trt_coef} : a \code{data.frame} of treatment-effect estimates with columns \code{logHR}, \code{se}, \code{Z}, and \code{p.val}. If \code{tvareff = TRUE}, it contains one row for each treatment-effect period.
\item \code{conf_int} : a \code{data.frame} for 95\% confidence interval(s) for estimated treatment effect (s) from the choice of standard error estimator.
\item \code{ctrl_func} : the estimated control function \eqn{\widehat{R}}, or \code{data.frame} of \eqn{\widehat{R}^1} and \eqn{\widehat{R}^2} if \code{tvareff = TRUE}.
\item \code{trt_model} : a \link[stats]{lm} object fit of the first-stage treatment model.
\item \code{out_model} : a \link[survival]{coxph} object fit of the second-stage outcome Cox model. If \code{tvareff = TRUE}, Cox models for first period \code{out_model1} and second period \code{out_model2} are both returned.
\item \code{est_boot} :  a vector of length \code{B} of bootstrap estimates from each iteration. If \code{bootvar = FALSE}, returns \code{NULL}.
\item \code{data_long} :  a \code{data.frame} of data for model fit transformed into start-stop form for two-period Cox estimation, if \code{tvareff = TRUE}.
\item \code{surv_curve}: a \link[survival]{survfit} object for fitted survival curve using complete data.
\item \code{iv_diag} : a list of IV diagnostics for weak-IV assessment, including the nested ANOVA comparison and F-statistic.
}
}
\description{
Flexible instrumental analysis of Cox model in a novel \strong{T}wo-\strong{S}tage \strong{R}esidual \strong{I}nclusion with \strong{F}railty (TSRI-F) framework when treatment \eqn{A} and mortality \eqn{D} are subject to unmeasured confounding.
Allow estimation of time constant treatment effect (Martinez-Camblor et al. (2019)) and time-varying treatment effect (Martinez-Camblor et al. (2019))
in terms of log hazard ratio (log-HR). A set of instrumental variables \eqn{Z} and covariates for adjustment \eqn{X} (i.e., measured confounders) are required to estimate treatment effects \eqn{\beta^{(1)}_a} and \eqn{\beta^{(2)}_a} before and after the pre-specified time \code{tchange}.
}
\details{
This function performs two-stage residual inclusion IV analysis of the Cox model with individual frailty
when the treatment effect \eqn{\beta_a} is constant over time (\code{tvareff = FALSE}) or \eqn{\beta_a (t)} changes value at some time \emph{t} (\code{tvareff = TRUE}).
The IV assumptions are that 1) relevance \eqn{Z \not\amalg A | U,X}, 2) exclusion restriction \eqn{Z\amalg (T,D)|A, U,X}, and 3) randomization \eqn{Z\amalg U|X} with \eqn{U} the unmeasured confounder.
TSRI-F posits a first-stage linear model that generates the treatment: \deqn{A = \gamma_0+ \gamma_1Z+\gamma_2U+\gamma'X+\epsilon}
and a second-stage outcome model follows Cox proportional hazards form: \deqn{\lambda(t|X,U)=\lambda_0(t)\exp\{\beta_aA+\beta_uU+\beta'X\}}
where \eqn{\lambda_0} is the baseline hazard function. The first stage of TSRIF procedure for constant treatment effect estimates \emph{control function} \eqn{\widehat{R}} from residual of treatment model:
\eqn{\widehat{R} = A - \hat{\gamma}_0 -\hat{\gamma}_1Z-\hat{\gamma}'X}, and fit a second-stage Cox model with user-specified individual frailty \eqn{\phi} while adjusting for \eqn{\widehat{R}}.

For more intricate case of time-varying effect, the first stage proceeds identically to compute \eqn{\widehat{R}^{(1)} = A - \hat{\gamma}_0 -\hat{\gamma}_1Z-\hat{\gamma}'X}.
Second stage involves fitting two Cox models to estimate \eqn{\beta_a^{(1)} = \beta_a(t), t<} \code{tchange} and \eqn{\beta_a^{(2)} = \beta_a(t), t\ge} \code{tchange}.
The first-period Cox model is fitted with frailty term \eqn{\hat{\phi_1}} and including \eqn{\widehat{R}^{(1)}} as a covariate.
Then, update the control function \eqn{\widehat{R}^{(2)} = \widehat{R}^{(1)} + \hat{\beta}^{(1), -1}_r \hat{\phi_1}} for the second period, which are then included as a covariate in the second-period Cox model
with a new frailty term.

This approach estimates conditional treatment effect of \code{trt}. Coefficient estimates of covariates other than \code{trt} are also estimated and readily available, but these estimates are
suggestive of their associational relations with survival outcome, and causal conclusions regarding these covariates with outcome should be cautious.
}
\examples{
data("VitD", package = "surviv")

fit_tsrif1 <- coxiv_tsrif(surv = "time", cens = "death", covs = c("age"),
                          trt = "vitd", iv = "filaggrin", tchange = NULL,
                          data = VitD, fdist = "gaussian", bootvar = FALSE,
                          B = 20, tvareff = FALSE)
fit_tsrif1$trt_coef

fit_tsrif2 <- coxiv_tsrif(surv = "time", cens = "death", covs = c("age"),
                          trt = "vitd", iv = "filaggrin", tchange = 5,
                          data = VitD, fdist = "gaussian", bootvar = FALSE,
                          B = 20, tvareff = TRUE)
fit_tsrif2$trt_coef

}
\references{
\enumerate{
\item Pablo Martinez-Camblor, Todd Mackenzie, Douglas O Staiger, Philip P Goodney, A James O'Malley, Adjusting for bias introduced by instrumental variable estimation in the Cox proportional hazards model, \emph{Biostatistics}, Volume 20, Issue 1, January 2019, Pages 80-96,
\item Pablo Martinez-Camblor, Todd A. MacKenzie, Douglas O. Staiger, Phillip P. Goodney, A. James O'Malley, An Instrumental Variable Procedure for Estimating Cox Models with Non-Proportional Hazards in the Presence Of Unmeasured Confounding, \emph{Journal of the Royal Statistical Society Series C: Applied Statistics}, Volume 68, Issue 4, August 2019, Pages 985-1005
}
}
