% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/coxiv_omom.R
\name{coxiv_omom}
\alias{coxiv_omom}
\title{Orthogonality method-of-moment IV estimation of Cox model}
\usage{
coxiv_omom(formula, trt, iv, data)
}
\arguments{
\item{formula}{a regression \link[stats]{formula} object with \link[survival]{Surv} object as outcome including survival time and censoring indicator.}

\item{trt}{a string indicates the name of the treatment variable of interest. Only time-invariant \strong{binary} or \strong{continuous} treatment is supported. It is strongly recommended that binary treatment is converted to numeric type (0,1) instead of using factor type. Treatment cannot be multi-categorical.}

\item{iv}{a string indicates the name of the instrumental variable. Only one time-variant \strong{binary} or \strong{continuous} instrumental variable is supported. IV cannot be multi-categorical.}

\item{data}{a \link[base]{data.frame} object of input data containing all variables specified in \code{formula}, including observed confounders.}
}
\value{
A \code{coxivomom} object for OMOM IV estimation of a Cox model with the following components:
\itemize{
\item \code{call}: the match call of the OMOM IV model.
\item \code{coef} : a \code{data.frame} of estimated log-hazard ratios and inference for all predictors in the outcome Cox model, with columns \code{logHR}, \code{se}, \code{Z}, and \code{p.val}.
\item \code{conf_int} : a \code{data.frame} of 95\% confidence interval(s) for the estimated log hazard ratios.
\item \code{input}: the collected input of the OMOM IV model.
\item \code{formula}: the outcome regression formula for Cox model
\item \code{n}: the effective sample size used for model estimation after missingness removal.
\item \code{events}: the effective number of events of survival outcome after missingness removal.
\item \code{vcov_mat} : estimated covariance matrix of log hazard ratios.
\item \code{iv_diag}: a list of IV diagnosis for weak IV. Include F-statistics and \code{anova} fit of nested treatment models comparison.
\item \code{surv_curve}: a \link[survival]{survfit} object for fitted survival curve using complete data.
}
}
\description{
Estimate marginal causal treatment effect (in terms of log-hazard ratio) in Cox model setting subject to unmeasured confounding \eqn{U} using instrumental variable based on the IV \strong{O}rthogonality \strong{M}ethod-\strong{o}f-\strong{M}oment estimator in MacKenzie et al. (2014).
}
\details{
A causal Cox counterfactual survival model for survival time \eqn{T} with additive unmeasured confounding is assumed for treatment \eqn{A}, observed confounder \eqn{X}, and unmeasured confounder \eqn{U}.
\deqn{P(T(a)=t|T(a)\ge t, U=u) = \lambda_0(t)\exp(\beta_a a + \beta'x) + h(u,t)}
OMOM IV estimator assumes the following conditions: 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}.
The estimates are obtained as the numerical solution to zero-crossing of estimating equation:
\deqn{\psi(\beta) \approx \sum^n_{i=1}\int^\tau_0 \left\{ Z_i-\frac{\sum^n_{j=1} Z_j D_j(s)\exp\{\beta_a A_j+\beta'X\}}{\sum^n_{j=1}D_j(s)\exp\{\beta_a A_j+\beta'X\}}dN_i(s) \right\} = 0 }
which is identical to the partial Cox score function for instrument \eqn{Z}. \eqn{D(t)} is the event indicator at time t and \eqn{N(t)} is a counting process for survival.
Huber-White sandwich estimator is used to obtain variance for \eqn{\hat{\beta}}.
Suggestive diagnostic test for weak IV was provided by fitting a pseudo-first stage treatment linear model (since OMOM IV is an estimating equation based IV approach, not two-stage based)
regressing treatment \code{trt} on IV \code{iv} and confounders extracted from all predictors from \code{formula} input except for \code{trt}.
A nested \link[stats]{anova} F-test was performed to compare fitted treatment models with and without \code{iv} as predictor.
A popular rule of thumb of indication for weak IV in econometric literature is when F-statistics is less than 10 from comparing IV-exclusion model.
}
\examples{
data("VitD", package = "surviv")
fit_omom <- coxiv_omom(survival::Surv(time, death) ~ vitd + age,
                        trt = "vitd", iv = "filaggrin", data = VitD)
fit_omom$coef
fit_omom$conf_int

}
\references{
MacKenzie, T.A., Tosteson, T.D., Morden, N.E. et al. Using instrumental variables to estimate a Cox proportional hazards regression subject to additive confounding. \emph{Health Serv Outcomes Res Method} 14, 54-68 (2014).
}
