---
title: "Getting started with survSampleSize"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with survSampleSize}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
```

## Overview

`survSampleSize` provides an interactive Shiny application for sample size
and power calculation in clinical trials with a survival (time-to-event)
endpoint, under general design conditions.

Two complementary methods are available:

- The **Lu (2021)** weighted log-rank method (via the `lrstat` package),
  which supports non-proportional hazards, delayed treatment effects,
  unequal allocation, dropout, non-inferiority testing, and
  Fleming-Harrington weighted log-rank statistics.
- The classic **Freedman (1982)** method (via the `powerSurvEpi` package)
  for the proportional-hazards setting.

## Launching the application

The package exposes a single user-facing function, `run_app()`, which
launches the Shiny application in your default browser:

```{r}
library(survSampleSize)
run_app()
```

The interactive app relies on several packages declared in `Suggests`. If
any are missing, `run_app()` reports which ones to install. You can install
all of them up front with:

```{r}
install.packages(c(
  "lrstat", "powerSurvEpi", "DT", "ggplot2", "bslib", "plotly"
))
```

## Workflow

Inside the app, the typical workflow is:

1. **Choose method and direction.** Select either the Lu (2021) or
   Freedman (1982) method, and whether to solve for the sample size *N*
   given a target power, or to solve for the power given a fixed *N*.

2. **Statistical design parameters.** Set the significance level (alpha),
   target power, one- vs. two-sided test, allocation ratio, and -- for the
   Lu method -- an optional non-inferiority margin.

3. **Time parameters (months).** Set the accrual duration and the follow-up
   time after accrual ends. The Freedman method instead uses a single total
   study duration.

4. **Survival and effect parameters.** Set the control-arm median survival,
   the target hazard ratio, and -- for the Lu method -- the delayed-effect
   (DTE) time, the annual dropout rate, the accrual rate, and the
   Fleming-Harrington weighting.

5. **Calculate.** The results panel reports the total sample size, expected
   number of events, study duration, and/or estimated power. Additional tabs
   show the theoretical survival curves, a calendar-time event-prediction
   timeline, and a side-by-side comparison of the two methods.

## References

- Freedman, L. S. (1982). Tables of the number of patients required in
  clinical trials using the log-rank test. *Statistics in Medicine*,
  1(2), 121-129. \doi{10.1002/sim.4780010204}
- Lu, K. (2021). Sample size calculation for logrank test and prediction of
  number of events over time. *Pharmaceutical Statistics*, 20(2), 229-244.
  \doi{10.1002/pst.2069}