RMSTpowerBoost Pipeline

## Power & sample size planning with Restricted Mean Survival Time (RMST)

This page is the “how-to” for the app. Follow the 3-step workflow below: choose data → map variables & pick a model → run analytical or repeated calculations → export reports.

Inputs
Pilot data (.csv) or simulated data
Models
IPCW · Stratified · GAM · Dependent censoring
Outputs
Power curves · KM plots · Summaries · Reports
1
Upload / Generate pilot data
Provide a dataset with `time`, `status`, `arm` (plus covariates).
2
Map columns & choose RMST model
Select the time/event/treatment columns, then pick the model family and τ.
3
Run analysis & export
Compute power or sample size (analytical or repeated), then download HTML/PDF.

### Quick start (the 90‑second path)

1. Step 1 (left panel): choose Upload and upload a `.csv` pilot dataset.
2. When the analysis panel appears, map Time-to-Event, Status (1=event), and Treatment Arm (1=treat).
3. Choose Target Quantity: Power (enter sample sizes) or Sample Size (enter target power).
4. Set RMST L (τ) and α. Pick Analytical (fast) or Repeated (simulation-based).
5. Click Run. Review plots and tables, then download the report.

### Data requirements

Your pilot dataset must contain at least three columns that you will map in Step 2: `time` (positive follow-up time), `status` (1 = event, 0 = censored), and `arm` (treatment indicator; 1 = treated). Additional covariates are optional but strongly recommended for adjusted/robust planning.

Recommended coding

- `time`: numeric, in days (or your study unit), strictly > 0.
- `status`: 0/1. If your file uses “Yes/No”, convert to 0/1 before upload.
- `arm`: 0/1 or a 2-level factor. The app treats 1 as the treatment arm.

Common gotchas

- Missing values in mapped columns will usually break model fitting.
- Non-binary `status` (e.g., 1/2) needs recoding.
- More than two treatment levels: collapse to two arms before upload.

Minimal example schema

Column | Type | Meaning
--- | --- | ---
`time` | numeric | follow-up time
`status` | 0/1 | 1 = event, 0 = censored
`arm` | 0/1 | 1 = treated, 0 = control
`x1, x2, …` | mixed | baseline covariates (optional)
`strata` | factor | needed only for stratified models

### Step 1. Data Upload or Generate

#### Upload pilot data

Use this when you have real study or pilot data and want the app to learn empirical survival/censoring patterns.

- Accepted: `.csv` (the uploader is configured for CSV).
- Keep the file “rectangular”: one row per subject, one column per variable.
- If you have dates, pre-compute durations before upload.

#### Generate pilot data (built-in simulator)

Use this when you are prototyping or running scenario planning without a pilot dataset.

- Build covariates (continuous/categorical), then set the event-time model (AFT/PH/PWExponential).
- Choose allocation ratio, treatment effect, target censoring, and seed (optional).
- Click Generate. Data, Summary, and KM Plot tabs refresh on each generate run.
- After confirming covariates, panel 1B opens and panel 1A folds (it stays available).

Simulator notes (what the controls mean)

- Allocation (a:b): randomized ratio, e.g. `1:1`, `2:1`.
- Treatment β (arm): effect of the treatment indicator in the chosen event-time model (sign interpretation depends on AFT vs PH).
- Target censoring: desired censoring proportion; used to calibrate censoring distribution.
- Transform (continuous only): applied after generation as `(x - a) / b`.

### Step 2: Map variables & pick the RMST model

Once data exist, the “Model & Analysis” panel becomes available. First map the required columns: Time-to-Event, Status, and Treatment Arm. Some models require additional inputs: stratified models need a Stratification Variable; dependent censoring needs covariates for the censoring Cox model.

Model guide (when to use what)

RMST model | Use when… | Extra mapping
--- | --- | ---
Linear IPCW Model | you want a straightforward adjusted RMST comparison with inverse-probability-of-censoring weights | none
Additive Stratified Model | effects differ by strata and you want additive structure across strata | `strata` required
Multiplicative Stratified Model | you prefer multiplicative structure across strata | `strata` required
Semiparametric (GAM) Model | nonlinear covariate effects are plausible and you want flexible adjustment | none
Dependent Censoring Model | censoring may depend on covariates and you want an explicit censoring model | choose censoring model covariates

Choosing τ (RMST L)

Pick τ within the reliable support of follow-up. Practically: choose τ near a clinically meaningful horizon (e.g., 6/12 months), but not so large that almost everyone is censored before τ. If in doubt, start with a percentile of observed follow-up (e.g., 70–80%).

### Step 3: Power vs Sample size, Analytical vs Repeated

#### Target quantity

- Power: provide a comma-separated list of candidate sample sizes (per arm / per stratum).
- Sample Size: provide a target power; the app searches for a suitable N.

#### Calculation method

- Analytical: fastest; best for iterative planning and sensitivity analysis.
- Repeated: simulation-based; set replications `R` (≥ 500 recommended) and an optional seed.

What “Repeated” does (high level)

For each candidate sample size, the app repeatedly simulates/bootstraps realizations under the pilot-data mechanism, recomputes the test statistic, and estimates power as the rejection proportion at level α.

- Higher `R` reduces Monte Carlo error (but increases runtime).
- Use a seed when you want reproducibility across runs or reports.

### Where to look for results

Tabs

- Data: current dataset and export tools
- Summary: data summary first, then histograms
- KM Plot: Kaplan–Meier curves
- Analysis: key results, power/sample-size tables, analysis summary, and power plot

Tables & logs

- Key results summary
- Analysis summary and data summary
- Console/run log (what happened, warnings, failures)

Reports

Download HTML (most robust) and PDF (requires LaTeX such as TinyTeX/MiKTeX) after a successful run.

### Step 4. Analysis

Run the analysis after mapping inputs. Results populate the plots, tables, and run log, and the report downloads become available.

### Troubleshooting (fast fixes)

“Please map Time/Status/Arm column”

Map the correct columns in Step 2. The app will default to the first columns if it can’t detect names like `time`, `status`, `arm`.

Status coding looks wrong (power is nonsense)

- Ensure `status = 1` indicates the event (not censoring).
- If your event indicator is reversed, fix it before upload (or create a new column and map that one).

Dependent censoring model fails

Pick covariates for the censoring Cox model. Avoid including treatment; the app excludes it by design.

PDF report fails to render

Use the HTML report first. If you need PDF, install TinyTeX/MiKTeX and re-run; LaTeX errors will appear in the log.