This vignette walks through the basic functions in npsurvSS. By the end, users should be able to:
Creating objects of class “arm”
The cornerstone of npsurvSS lies in objects of class “arm”. These objects are lists that capture for a treatment arm assumptions regarding its sample size, accrual, survival, censoring, and duration of follow-up. Once created, they serve as inputs for other functions, including functions for power/sample size calculation and trial simulation.
The following code creates two arms, an active arm and a control arm. Both arms will accrue 120 patients uniformly over 6 months and follow them for an additional 12 months. Patients will be subjected to loss of follow-up at an exponential rate of 0.00578. active and control patients will experience event at exponential rates of 0.0462 and 0.0578, respectively. The hazard ratio between the two arms is therefore approximately 0.8.
In practice, investigators seldom consider exponential distributions on the hazard rate scale. Instead, they consider the median survival or survival probability at some milestone t. We have defined additional functions to facilitate this practice. per2haz is a simple code that can convert an exponential survival percentile to the hazard rate and vice versa.
Alternatively, create_arm_lachin allows investigators to specify exponential survival and censoring distributions by providing median survivals or milestone survivals.
active <- create_arm_lachin(size=120,
accr_time=6,
surv_median=15,
loss_milestone=c(120, 0.5), # corresponds to 120 month median
follow_time=12)
control <- create_arm_lachin(size=120,
accr_time=6,
surv_milestone=c(12, 0.5), # corresponds to 12 month median
loss_median=120,
follow_time=12)
class(active)
#> [1] "list" "lachin" "arm"
Note that objects created by create_arm_lachin belong to class “lachin” and “arm”. “lachin” is a subclass of “arm”. It is named after the class of distributions considered by Lachin (1986), which covers uniform/truncated-exponential accrual, exponential survival, and exponential censoring. Check out the R Documentation ?create_arm for examples of “arm” objects with more sophisticated assumptions, such as piecewise-uniform accrual, piecewise-exponential/Weibull survival, and Weibull censoring. While objects created by create_arm_lachin are always of class “lachin” and “arm”, objects created by create_arm are always of class “arm”, but not necessarily of class “lachin”.
Visualizing distributional assumptions
Having created an “arm” object, visualizing its assumptions is easy. For example, the following code plots the accrual cumulative distribution function (CDF):
Likewise, the survival function:
Just as pbinom in the R package stats is accompanied by functions for the density, quantile, and random generation, paccr is similarly accompanied by daccr, qaccr, and raccr. Distribution functions psurv and ploss are further accompanied by hsurv and hloss for the hazard.
Calculating power and sample size
Given an active arm and a control arm, calculating power and sample size is also easy. The following code calculates power under the default setting of an unweighted log-rank test with one-sided alpha 0.025:
To calculate power for other tests:
# unweighted log-rank
power_two_arm(control, active, test=list(test="weighted logrank"))
#> [1] 0.2366524
# Gehan-Breslow weighted log-rank
power_two_arm(control, active, test=list(test="weighted logrank", weight="n"))
#> [1] 0.2210357
# difference in 12 month survival
power_two_arm(control, active, test=list(test="survival difference", milestone=12))
#> [1] 0.2050328
# ratio of 12 month RMST
power_two_arm(control, active, test=list(test="rmst ratio", milestone=12))
#> [1] 0.1823979
Power for multiple tests can be calculated simulateously:
To calculate sample size required to achieve 80% power:
Note that size_two_arm returns the required sample size n and expected number of events d (per arm and total). When calculating the required sample size per arm, it considers as input the specified ratio between the two arms (e.g. 120:120) while ignoring their individual values (e.g. 120 and 120). Thus, the following two “arm” objects result in the same sample size calculation for the unweighted log-rank test:
Sample size for a trial with 2:1 randomization in favor of the active arm can be calculated like so:
Event-driven trials
By containing the keys follow_time and total_time, “arm” objects intrinsically apply to time-driven trials that end when a fixed period of time has elapsed after the last patient in. However, they can also be used to approximate event-driven trials, trials in which the study ends when a desired number of events has been observed. Specifically, a trial requiring d events can be approximated by a trial of length t, where the expected number of events at t is equal to d. The functions exp_events and exp_duration can be useful for this purpose:
Therefore, under the given assumptions, a trial requiring 150 events can be approximated by a 23.75-month long trial. When updating the trial duration in an “arm” object, it is important to update both the follow_time and total_time to ensure their consistency: