% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/coxiv_seq.R
\name{coxiv_seq}
\alias{coxiv_seq}
\title{Sequential 2SRI Cox analysis via sequential trials emulation}
\usage{
coxiv_seq(formula, trtformula, data, id, tvtrt, iv, stratify = FALSE,
  se_type = c("robust", "jackknife", "bootstrap", "none"), B = 50,
  seed = NULL, ipacw_den_covs = NULL, ipacw_num_covs = NULL,
  by_trial = TRUE, ...)
}
\arguments{
\item{formula}{a \code{formula} for the composite second-stage Cox model,
typically of the form
\code{Surv(start.new, stop.new, event) ~ tvtrt.base + x1.base + x2.base}.
The right-hand side must include \code{paste0(tvtrt, ".base")}. The control
function term \code{R.base} is added automatically if absent.}

\item{trtformula}{a \code{formula} for the trial-specific first-stage treatment
model. Its left-hand side must equal \code{paste0(tvtrt, ".base")}, and its
right-hand side must include \code{paste0(iv, ".base")}.}

\item{data}{a \code{seqem} object returned by \code{\link[=seqem]{seqem()}}.}

\item{id}{a string name for the subject identifier variable.}

\item{tvtrt}{a string name for the original time-varying treatment
variable.}

\item{iv}{a string name for the original baseline instrumental
variable.}

\item{stratify}{logical; if \code{TRUE}, the composite Cox model is stratified by
emulated trial so that each trial has its own baseline hazard.}

\item{se_type}{standard error estimator: one of \code{"robust"}, \code{"jackknife"},
\code{"bootstrap"}, or \code{"none"}.}

\item{B}{the number of bootstrap replicates when \code{se_type = "bootstrap"}.}

\item{seed}{optional random seed for bootstrap resampling.}

\item{ipacw_den_covs}{optional string vector of underlying covariate names
to use in the denominator IPACW model through their lead versions (for
example \code{c("endoleak")} uses \code{endoleak.lead1}). If \code{NULL}, the underlying
variables corresponding to non-treatment \code{.base} terms in \code{formula} and
\code{trtformula} are used whenever the original variables are available in the
stacked data.}

\item{ipacw_num_covs}{optional string vector of baseline \code{.base}
covariates to use in the numerator stabiliser model. If \code{NULL}, an
intercept-only numerator model is used.}

\item{by_trial}{logical; if \code{TRUE}, fit and return separate second-stage Cox
models within each emulated trial.}

\item{...}{additional arguments passed to \code{\link[survival:coxph]{survival::coxph()}}.}
}
\value{
A \code{coxivseq} object with components including:
\itemize{
\item \code{call} : the matched call.
\item \code{formula} : the composite second-stage Cox formula actually fitted.
\item \code{trtformula} : the sequential first-stage treatment models formula.
\item \code{fit} : the fitted composite \code{\link[survival:coxph]{survival::coxph()}} model.
\item \code{coef} : a \code{data.frame} with columns \code{logHR}, \code{HR}, \code{se}, \code{Z}, \code{p.val}.
\item \code{conf_int} : a \code{data.frame} of 95\% confidence limits with columns
\verb{2.5\%} and \verb{97.5\%} for estimated log hazard ratios.
\item \code{vcov_mat} : variance-covariance matrix corresponding to the
selected \code{se_type}.
\item \code{trtfit_by_trial} : list of first-stage treatment models.
\item \code{fit_by_trial} : list of second-stage trial-specific Cox fits when
\code{by_trial = TRUE}.
\item \code{data_ste} : final stacked, artificially censored analysis dataset,
including \code{R.base} and the computed IPACW column.
\item \code{jackknife}, \code{bootstrap}: a \code{matrix} of jackknife or bootstrap resampled
estimates if \code{se_type} set to \code{jackknife} or \code{boostrap}.
\item \code{tvtrt}, \code{iv}, \code{n}, \code{n_ids}, \code{n_trials}, \code{n_event}, \code{stratify},
\code{se_type}, \code{B}, \code{by_trial}: miscellaneous string tags for model print
summary.
}
}
\description{
Fits a sequential two-stage residual inclusion (2SRI) Cox
model for a time-varying treatment with a baseline instrumental variable,
using a stacked sequential trial emulation created by \code{\link[=seqem]{seqem()}}.
}
\details{
The analysis proceeds trial by trial. Within each emulated trial, a
first-stage logistic regression is fit for the trial-baseline treatment
\verb{\{tvtrt\}.base} on the baseline IV and baseline covariates from
\code{trtformula}. A trial-specific control-function residual \code{R.base} is then
constructed and carried across all rows within that subject-trial trajectory.

The stacked data are then artificially censored when observed treatment
deviates from the trial-baseline treatment status, and stabilised inverse
probability of artificial censoring weights (IPACW) are estimated. These
weights address the informative censoring induced by the sequential trial
emulation itself. This function does not estimate additional weights for
naturally occurring right censoring.

Finally, a weighted composite Cox model is fit on the artificially censored,
weighted stacked data. The returned coefficient summary is organised in the
same style as \code{\link[=seqcox]{seqcox()}}, \code{\link[=coxiv_omom]{coxiv_omom()}}, and \code{\link[=coxiv_tsrif]{coxiv_tsrif()}}.
}
\examples{
data("vascular", package = "surviv")

vasc_seqem <- seqem(
  data = vascular,
  start = "time.start",
  stop = "time.stop",
  event = "event",
  id = "id",
  tvtrt = "reint",
  covs = c("iv", "diameter", "endoleak"),
  coarsen = "ceiling",
  cbin_width = 2
)

fit_seqcox <- coxiv_seq(
  formula = survival::Surv(start.new, stop.new, event) ~
    reint.base + diameter.base + endoleak.base,
  trtformula = reint.base ~ iv.base + diameter.base + endoleak.base,
  data = vasc_seqem,
  id = "id",
  tvtrt = "reint",
  iv = "iv",
  se_type = "robust",
  by_trial = TRUE
)

print(fit_seqcox)

}
\references{
Gran JM, Roysland K, Wolbers M, Didelez V, Sterne JA, Ledergerber B,
Furrer H, von Wyl V, Aalen OO. A sequential Cox approach for estimating the
causal effect of treatment in the presence of time-dependent confounding
applied to data from the Swiss HIV Cohort Study. \emph{Statistics in
Medicine}. 2010;29(26):2757-2768.

Keogh RH, Gran JM, Seaman SR, Davies G, Vansteelandt S. Causal inference in
survival analysis using longitudinal observational data: Sequential trials
and marginal structural models. \emph{Statistics in Medicine}.
2023;42(13):2191-2225.
}
