
# tvrmst

**Time-Varying Restricted Mean Survival Time from Survival Matrices**

`tvrmst` is a matrix-first framework for computing dynamic restricted
mean survival time (RMST) curves, treatment contrasts, and bootstrap
confidence intervals.

The package separates survival estimation from functional summarization
and operates directly on subject-level survival probability matrices.

## Motivation

Restricted mean survival time (RMST) is defined as

$$
\mathrm{RMST}(\tau) = \int_0^\tau S(u)\,du.
$$

RMST is often more interpretable and robust than hazard ratios,
especially under non-proportional hazards. Most implementations target a
single horizon $\tau$. `tvrmst` extends this to the full dynamic curve:

$$
\tau \mapsto \mathrm{RMST}(\tau).
$$

This enables:

- Continuous-time treatment contrasts

- Time-dependent benefit visualization

- Individual-level RMST trajectories

## Mathematical Framework

For subject $i$, with predicted survival $S_i(t)$:

$$
\mathrm{RMST}_i(\tau) = \int_0^\tau S_i(u)\,du.
$$

Population mean dynamic RMST:

$$
\mathrm{RMST}(\tau) = \frac{1}{n}\sum_{i=1}^{n}\mathrm{RMST}_i(\tau).
$$

Two-arm contrast (A vs B):

$$
\Delta(\tau) = \mathrm{RMST}_B(\tau) - \mathrm{RMST}_A(\tau).
$$

All integrals use deterministic trapezoidal integration on a common time
grid.

## Design Principles

1.  **Matrix-first abstraction**: rows are subjects, columns are time
    points.

2.  **Model-agnostic workflow**: works with any upstream survival
    estimator.

3.  **Unbalanced-arm support**: group sizes can differ.

> `tvrmst` does not fit survival models.

## Installation

``` r
# install.packages("remotes")
remotes::install_github("your-username/tvrmst")
```

## Core API

### Data structure

- `as_survmat()`
- `nobs_survmat()`
- `bind_survmat()`

### Estimands

- `rmst_dynamic()`
- `rmst_delta()`

### Bootstrap

- `bootstrap_curve()`
- `boot_rmst_delta()`

### Visualization

- `plot_rmst_individual_by_group()`
- `plot_rmst_two_arms()`
- `plot_delta_curve()`
- `plot_boot_curve()`

### Coercion helper

- `as_survprob_matrix()`

## Basic Workflow

### 1) Prepare two-arm survival matrices

``` r
library(tvrmst)
set.seed(1)

time <- seq(0, 5, by = 0.05)
nA <- 100
nB <- 80

lambdaA <- rexp(nA, rate = 0.2)
lambdaB <- rexp(nB, rate = 0.15)

S_A <- outer(lambdaA, time, function(l, t) exp(-l * t))
S_B <- outer(lambdaB, time, function(l, t) exp(-l * t))

xA <- as_survmat(S_A, time, group = rep("A", nA))
xB <- as_survmat(S_B, time, group = rep("B", nB))
x_all <- bind_survmat(xA, xB)
```

### 2) Dynamic RMST

``` r
res_all <- rmst_dynamic(x_all)
```

Key outputs:

- `res_all$individual`: subject-level dynamic RMST curves

- `res_all$mean`: population mean dynamic RMST curve

### 3) Two-arm contrast

``` r
d <- rmst_delta(xA, xB)
```

Returns full $\Delta(\tau)$ over the grid.

### 4) Bootstrap confidence intervals

``` r
boot <- boot_rmst_delta(xA, xB, R = 300, seed = 1)
```

Computes percentile confidence bands pointwise along the delta curve.

## Visualization

``` r
plot_rmst_individual_by_group(res_all, group = x_all$group)
```

![](README_files/figure-gfm/unnamed-chunk-6-1.png)<!-- -->

``` r
plot_rmst_two_arms(xA, xB)
```

![](README_files/figure-gfm/unnamed-chunk-6-2.png)<!-- -->

``` r
plot_delta_curve(d$time, d$delta)
```

![](README_files/figure-gfm/unnamed-chunk-6-3.png)<!-- -->

``` r
plot_boot_curve(boot)
```

![](README_files/figure-gfm/unnamed-chunk-6-4.png)<!-- -->

## Relation to Existing RMST Workflows

Compared with fixed-horizon RMST tools, `tvrmst` provides:

- Continuous dynamic RMST curves
- Individual RMST trajectories
- Direct compatibility with ML survival predictions
- A clean separation between model fitting and functional summarization

This supports modern benchmarking and production survival pipelines.

## Citation

``` r
citation("tvrmst")
```

## License

MIT
