---
title: "Survival Outcomes"
author: "Sean T. Bresnahan and Charis Xiong"
date: "`r Sys.Date()`"
output:
  BiocStyle::html_document:
    toc: true
    toc_depth: 3
    toc_float: true
vignette: >
  %\VignetteIndexEntry{Survival Outcomes}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  echo = TRUE, message = FALSE, warning = FALSE,
  fig.width = 7, fig.height = 4.5, comment = "#>"
)
set.seed(1)
library(iconic)
```

# Introduction

This vignette covers time-to-event outcomes. `iconic` supports Cox proportional-hazards and restricted-mean-survival-time (RMST) effect scales for all instrument- and negative-control-based estimators.

# Installation

`iconic` is being submitted to Bioconductor. Once accepted, install the
release version with:

```{r install-bioc, eval=FALSE}
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("iconic")
```

The development version is available from GitHub:

```{r install-github, eval=FALSE}
BiocManager::install("sbresnahan/iconic")
```


# Time-to-event outcomes in ICONIC

ICONIC extends all estimators except `COCA` to time-to-event outcomes via
two-stage predictor substitution (2SPS). The key insight is that the
first-stage regressions — instrumenting $X$ on $G_1 + W + C$, instrumenting
$M$ on $\hat{X} + G_m + W + C$, and constructing the bridge proxies
$\hat{W}$ — involve only continuous variables ($X$, $M$, $W$) as responses,
so they remain ordinary least squares regardless of the outcome type. Only
the final outcome stage changes. (For the instrument-variable estimators
`IV2SLS` / `IV2SLS2`, the negative controls are an optional path-specific
augmentation — `W1` for the exposure first stage, `W2` for the mediator and
outcome stages: when no negative controls are supplied, the first stages
instrument on the genetic instrument(s) and covariates alone.)

# Two effect scales

ICONIC provides two effect scales for survival outcomes:

1. **Cox log-hazard-ratio (log-HR)**: fits
   `coxph(Surv(time, event) ~ X_hat + M_hat + W_hat + C)` and reports the
   coefficients as log-HRs. The log-HR is **non-collapsible**: the
   conditional log-HR given covariates differs from the marginal log-HR
   even under no confounding, so the product decomposition
   $\text{NIE} = \hat{\alpha}_M \cdot \hat{\beta}_M$ is approximate on this
   scale. The log-HR scale is the **recommended primary scale**.

2. **RMST (restricted mean survival time)**: computes pseudo-observations
   via the leave-one-out jackknife of the Kaplan-Meier RMST estimate, then
   fits OLS on the pseudo-observations. RMST is **collapsible**, so the
   NDE/NIE decomposition is exact on this scale. However, the
   pseudo-observations introduce additional variance, producing wider
   confidence intervals and higher RMSE than the Cox partial-likelihood
   estimator.

# COCA incompatibility

`COCA` regresses the negative control on the outcome ($W \sim Y + X$) and
recovers $\hat{\tau} = -\hat{\beta}_Z / \hat{\beta}_Y$. This requires $Y$
as a continuous response variable. With a censored time-to-event outcome,
$Y$ is not available as a continuous variable — the outcome is represented
as a `Surv(time, event)` object — so `COCA` is structurally incompatible
with survival outcomes. ICONIC returns `NA` for COCA on survival data and
excludes it from the eligibility report.

# A minimal example

We simulate a small survival panel and estimate on both scales.

```{r surv-data}
sdat <- generate_toy_data(
  n = 100, n_features = 3, seed = 1,
  outcome_type = "survival",
  phi = 0.8, omega_1 = 0.7, omega_2 = 0.7
)

# For survival, pass surv_time + surv_event instead of Y.
sdata <- iconic_data(
  X = sdat$X,
  surv_time = sdat$surv_time, surv_event = sdat$surv_event,
  M = sdat$M,
  G = sdat$G, Gm = sdat$Gm,
  W1 = sdat$W1, W2 = sdat$W2,
  outcome_type = "survival",
  covariates = sdat$synthetic_data
)
```

## Cox log-HR scale

```{r surv-loghr}
est_loghr <- iconic_estimate(sdata, effect_scale = "loghr")
head(est_loghr)
```

## RMST scale

```{r surv-rmst}
est_rmst <- iconic_estimate(sdata, effect_scale = "rmst")
head(est_rmst)
```

On the log-HR scale, the true total effect is $\beta_X$ and the NDE/NIE
decomposition is approximate. On the RMST scale, the truth is computed
empirically at zero confounding (because RMST depends on the baseline
hazard and truncation time), and the decomposition is exact.

# Diagnosis and eligibility

```{r surv-diagnose}
diag <- iconic_diagnose(sdata)
diag$eligibility
```

Note that `COCA` is marked ineligible for survival outcomes. All other
estimators are assessed on the same instrument-strength and NC-validity
criteria as for continuous outcomes.

# Further reading

- **Walkthrough vignette**: `vignette("iconic-walkthrough")` — the full
  model-selection workflow, including a survival example.
- **Function reference**: `?iconic_estimate` for the `effect_scale`
  argument and `?generate_toy_data` for the survival DGP parameters
  (`surv_h0`, `surv_event_frac`, `surv_censor_rate`).

# Session information

```{r sessionInfo}
sessionInfo()
```