% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/seqcox.R
\name{seqcox}
\alias{seqcox}
\title{Sequential Cox analysis via sequential trials emulation}
\usage{
seqcox(formula, data, id, trial_id = "trial", stratify = FALSE,
  se_type = c("robust", "jackknife", "bootstrap", "none"), B = 50,
  seed = NULL, ipacw_trunc = 0.95, ipacw_den_covs = NULL,
  ipacw_num_covs = NULL, by_trial = TRUE, ...)
}
\arguments{
\item{formula}{a survival formula for the composite Cox model, typically of
the form \code{Surv(start.new, stop.new, event) ~ trt.base + L.base + ...}.
The \emph{first} \code{.base} term is treated as the trial-baseline treatment variable.}

\item{data}{a \code{seqem} object returned by \code{\link[=seqem]{seqem()}}. A raw data frame is not
accepted.}

\item{id}{a string name of the subject identifier column in the sequential trials data.}

\item{trial_id}{a string name of the trial index column. Defaults to \code{"trial"}.}

\item{stratify}{logical; if \code{TRUE}, the composite Cox model is stratified by
\code{trial_id} so each emulated 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}{number of bootstrap replicates when \code{se_type = "bootstrap"}.}

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

\item{ipacw_trunc}{optional truncation quantile for cumulative stabilized
IPACW. Defaults to \code{0.95}. Set to \code{NULL} to disable truncation.}

\item{ipacw_den_covs}{optional character 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} are
used.}

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

\item{by_trial}{logical; if \code{TRUE} (default), fit trial-specific Cox models
and return them in \verb{$fit_by_trial}.}

\item{...}{additional arguments passed to \code{\link[survival:coxph]{survival::coxph()}}.}
}
\value{
A \code{seqcox} object with components including:
\itemize{
\item \code{call} : the matched call.
\item \code{formula} : the composite Cox formula actually fitted.
\item \code{fit} : a composite \code{\link[survival:coxph]{survival::coxph()}} fit.
\item \code{coef} : a \code{data.frame} of estimated coefficient summaries with columns
\code{logHR}, \code{HR}, \code{se}, \code{Z}, and \code{p.val}.
\item \code{conf_int} : a \code{data.frame} of 95\% confidence limits with columns
\verb{2.5\%} and \verb{97.5\%}.
\item \code{n_ids}, \code{n_trials}, \code{n_event}: the analysis size summaries
for sample size, number of emulated trials aggregated, and number
of events.
\item \code{fit_by_trial} : a list of trial-specific Cox fits when
\code{by_trial = TRUE}.
\item \code{data_ste} : a \code{data.frame} of stacked analysis dataset actually used in
the composite fit, including the computed IPACW column.
\item \code{jackknife}, \code{bootstrap}: a vector of jackknife or bootstrap resampled
estimates if \code{se_type} set to \code{jackknife} or \code{boostrap}.
}
}
\description{
Fit a composite Cox model to a stacked sequential trial emulation object
produced by \code{\link[=seqem]{seqem()}}. The analysis follows the sequential Cox approach of
Gran et al. by using stabilized inverse probability of artificial censoring
weights (IPACW) to adjust for the informative artificial censoring induced by
restricting each emulated trial to individuals who continue to follow their
treatment assignment at the trial start.
}
\examples{
  data("vascular", package = "surviv")
  vasc_seqem = seqem(data = vascular, start = "time.start",
                     stop = "time.stop", event = "event", id = "id",
                     tvtrt = "reint", covs = c("diameter", "endoleak"),
                     coarsen = "ceiling", cbin_width = 2)
  fit_seqcox <- seqcox(
    formula = survival::Surv(start.new, stop.new, event) ~
      reint.base + diameter.base + endoleak.base,
    data = vasc_seqem,
    id = "id",
    se_type = "robust"
  )
  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.
}
