gsDesign

https://keaven.github.io/gsDesign/
Admin
A statistical software project providing tools and methods for designing and analyzing group...
Tokens:190,694
Snippets:1,489
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Step Spending Function Example

Source: https://keaven.github.io/gsDesign/reference/sfLinear.html

Illustrates the use of `sfStep()` to define a step function for spending. This is useful when the exact timing of analyses is uncertain. The example plots the spending function.

```R
library(ggplot2)
# Example for sfStep()
# alpha is the total error to spend, t is the proportion of information, param specifies the timing and spending levels
# Here, we spend 0.025 Type I error. The first analysis is at 0.2 information, with 0.005 alpha spent.
# The second analysis is at 0.5 information, with 0.01 alpha spent.
# The third analysis is at 0.8 information, with 0.02 alpha spent.
# The final spending is at 1.0 with 0.025 total spending.
alpha <- 0.025
t <- seq(0, 1, by = 0.01)
param <- c(0.2, 0.5, 0.8, 0.005, 0.01, 0.02)

# Calculate spending
spend <- sfStep(alpha = alpha, t = t, param = param)

# Plot spending
ggplot(data = data.frame(t = t, spend = spend$spend), aes(x = t, y = spend))
  + geom_line()
  + labs(title = "sfStep spending function", x = "Proportion of Information", y = "Cumulative Alpha Spent")

```

--------------------------------

### Summarize different boundary functions

Source: https://keaven.github.io/gsDesign/reference/spendingFunction.html

This example illustrates how to use summary() to inspect different types of boundary functions, specifically O'Brien-Fleming ('OF') and Wang-Tsiatis ('WT') with a specified parameter.

```R
# What happens to summary if we used a boundary function design
x <- gsDesign(test.type = 2, sfu = "OF")
y <- gsDesign(test.type = 1, sfu = "WT", sfupar = .25)
summary(x$upper)
summary(y$upper)
```

--------------------------------

### Install gsDesign Package

Source: https://keaven.github.io/gsDesign/index.html

Install the gsDesign package from CRAN for the easiest setup. Alternatively, install the development version directly from GitHub using the 'remotes' package.

```r
install.packages("gsDesign")
```

```r
# Alternatively, install development version from GitHub:
# install.packages("remotes")
remotes::install_github("keaven/gsDesign")
```

--------------------------------

### Linear Spending Function Example

Source: https://keaven.github.io/gsDesign/reference/sfLinear.html

Demonstrates the usage of `sfLinear()` to create a piecewise linear spending function. This function is then used to plot the spending over time.

```R
library(ggplot2)
# Example for sfLinear()
# alpha is the total error to spend, t is the proportion of information, param is the timing and spending levels
# Here, we spend 0.025 Type I error over 100% of information, with spending points at 0.2, 0.4, 0.6, 0.8 of information
# and corresponding spending proportions of 0.005, 0.01, 0.015, 0.02 at those information points.
# The final spending is at 1.0 with 0.025 total spending.
alpha <- 0.025
t <- seq(0, 1, by = 0.01)
param <- c(0.2, 0.4, 0.6, 0.8, 0.005, 0.01, 0.015, 0.02)

# Calculate spending
spend <- sfLinear(alpha = alpha, t = t, param = param)

# Plot spending
ggplot(data = data.frame(t = t, spend = spend$spend), aes(x = t, y = spend))
  + geom_line()
  + labs(title = "sfLinear spending function", x = "Proportion of Information", y = "Cumulative Alpha Spent")

```

--------------------------------

### gsBoundSummary Showing All Boundary Descriptions

Source: https://keaven.github.io/gsDesign/reference/gsBoundSummary.html

This example shows how to use gsBoundSummary to display all available boundary descriptions by setting 'exclude = NULL'. This includes additional metrics like Spending, B-value, CP, CP H1, and PP.

```R
gsBoundSummary(xinfo, Nname = "Information", exclude = NULL)
```

--------------------------------

### Design a 4-analysis trial with HSD spending function

Source: https://keaven.github.io/gsDesign/reference/spendingFunction.html

This example demonstrates how to design a 4-analysis trial using the Hwang-Shih-DeCani (HSD) spending function for both lower and upper bounds. It shows how to create the design object and print its summary.

```R
# Example 1: simple example showing what most users need to know

# Design a 4-analysis trial using a Hwang-Shih-DeCani spending function
# for both lower and upper bounds
x <- gsDesign(k = 4, sfu = sfHSD, sfupar = -2, sfl = sfHSD, sflpar = 1)

# Print the design
x
```

--------------------------------

### Summarize Binomial Group Sequential Design with Odds Ratio

Source: https://keaven.github.io/gsDesign/reference/gsBoundSummary.html

This example shows how to set up and summarize a group sequential design for a Binomial endpoint using the Odds Ratio (OR) scale. The delta1 is specified on the log scale.

```R
n.fix <- nBinomial(p1 = .3, p2 = .15, scale = "OR")
xOR <- gsDesign(k = 2, n.fix = n.fix, delta1 = log(.15 / .3 / .85 * .7), endpoint = "Binomial")
gsBoundSummary(xOR, deltaname = "OR", logdelta = TRUE)
```

--------------------------------

### Calculate expected events with specified study duration and minimum follow-up

Source: https://keaven.github.io/gsDesign/reference/eEvents.html

This example calculates expected events for a study with a specific total duration (Tfinal) and a minimum follow-up time (minfup) after the last enrollment. Enrollment durations are specified.

```r
lambda <- c(0.5, 0.6)
eta <- c(0.1, 0.15)
gamma <- c(10, 12)
R <- c(1, 1) # Recruitment durations
S <- c(1) # Duration of piecewise constant event rates
T <- 2 # Time of analysis
Tfinal <- 3 # Study duration
minfup <- 1 # Minimum follow-up after enrollment
eEvents(lambda = lambda, eta = eta, gamma = gamma, R = R, S = S, T = T, Tfinal = Tfinal, minfup = minfup)

```

--------------------------------

### eEvents for Control Group Example (Bernstein and Lagakos, 1978)

Source: https://keaven.github.io/gsDesign/reference/eEvents.html

Sets up a control group scenario for the eEvents function, referencing an example from Bernstein and Lagakos (1978). It defines control lambda rates and uses a matrix for lambda and gamma to accommodate multiple strata and enrollment periods, with eta set to 0.

```R
lamC <- c(1, .8, .5)
n <- eEvents(
  lambda = matrix(c(lamC, lamC * 2 / 3), ncol = 6), eta = 0,
  gamma = matrix(.5, ncol = 6), R = 2, T = 4
)
```

--------------------------------

### Design a 4-analysis trial using sfPower

Source: https://keaven.github.io/gsDesign/reference/sfPower.html

This example demonstrates how to design a 4-analysis trial using the sfPower spending function for both lower (Type II error) and upper (Type I error) bounds with specified rho parameters.

```R
library(ggplot2)
# design a 4-analysis trial using a Kim-DeMets spending function
# for both lower and upper bounds
x <- gsDesign(k = 4, sfu = sfPower, sfupar = 3, sfl = sfPower, sflpar = 1.5)

# print the design
x
```

--------------------------------

### Implement a 2-parameter beta distribution spending function

Source: https://keaven.github.io/gsDesign/reference/spendingFunction.html

This is a placeholder for an advanced example demonstrating the implementation of a custom spending function, specifically a 2-parameter version of the beta distribution spending function. This is intended for users who need to define novel spending functions.

```R
# Example 2: advanced example: writing a new spending function
# Most users may ignore this!

# Implementation of 2-parameter version of
# beta distribution spending function

```

--------------------------------

### Displaying Design Bounds (Z-scale)

Source: https://keaven.github.io/gsDesign/articles/gsSurvPower.html

Prints the efficacy and futility bounds from the input design object. This is a setup step for demonstrating bound stability.

```R
design_events <- design$n.I
cat("Design bounds (Z-scale):\n")
```

```R
cat("  Efficacy:", round(design$upper$bound, 4), "\n")
```

```R
cat("  Futility:", round(design$lower$bound, 4), "\n\n")
```

--------------------------------

### Design a 4-analysis trial with sfHSD

Source: https://keaven.github.io/gsDesign/reference/sfHSD.html

This example demonstrates how to design a 4-analysis trial using the sfHSD spending function for both lower and upper bounds with specified gamma parameters. It also shows the default usage where sfHSD is implicitly used.

```R
library(ggplot2)
# design a 4-analysis trial using a Hwang-Shih-DeCani spending function
# for both lower and upper bounds
x <- gsDesign(k = 4, sfu = sfHSD, sfupar = -2, sfl = sfHSD, sflpar = 1)

# print the design
x
```

```R
# since sfHSD is the default for both sfu and sfl,
# this could have been written as
x <- gsDesign(k = 4, sfupar = -2, sflpar = 1)
```

--------------------------------

### Set Up Design Assumptions for Scenario 1

Source: https://keaven.github.io/gsDesign/articles/PoissonMixtureModel.html

Configures key design parameters for Scenario 1, including hazard rates, error rates (alpha, beta), test type, spending functions, and randomization ratio. This setup is crucial for deriving sample size and event targets.

```R
# Get hazard rate info for Scenario 1 control group
control <- hazard |> filter(Scenario == 1, Treatment == "Control")
# Failure rates
lambdaC <- control$hazard_rate
# Interval durations
S <- (control$Time - control$time_lagged)[1:(bins - 1)]
# 1-sided Type I error
alpha <- 0.025
# Type II error (1 - power)
beta <- .1
# Test type 6: asymmetric 2-sided design, non-binding futility bound
test.type <- 6
# 1-sided Type I error used for safety (for asymmetric 2-sided design)
astar <- .2
# Spending functions (sfu, sfl) and parameters (sfupar, sflpar)
sfu <- sfHSD 
sfupar <- -3 
sfl <- sfLDPocock # Near-equal Z-values for each analysis
sflpar <- NULL # Not needed for Pocock spending
# Dropout rate (exponential parameter per unit of time)
dropout_rate <- 0.002
# Experimental / control randomization ratio
ratio <- 1
```

--------------------------------

### Specify Spending on a Pointwise Basis

Source: https://keaven.github.io/gsDesign/reference/sfPoints.html

This example demonstrates how to use sfPoints to define a group sequential design with specified spending at six analysis points. It then extracts and plots the cumulative spending proportions at each analysis, comparing them to the input values.

```R
library(ggplot2)
# example to specify spending on a pointwise basis
x <- gsDesign(
  k = 6, sfu = sfPoints, sfupar = c(.01, .05, .1, .25, .5, 1),
  test.type = 2
)
x
#> Symmetric two-sided group sequential design with
#> 90 % power and 2.5 % Type I Error.
#> Spending computations assume trial stops
#> if a bound is crossed.
#> 
#>            Sample
#>             Size 
#>   Analysis Ratio*  Z   Nominal p  Spend
#>          1  0.171 3.48    0.0002 0.0003
#>          2  0.342 3.07    0.0011 0.0010
#>          3  0.512 2.94    0.0017 0.0013
#>          4  0.683 2.58    0.0050 0.0037
#>          5  0.854 2.33    0.0099 0.0063
#>          6  1.025 2.03    0.0211 0.0125
#>      Total                       0.0250 
#> 
#> ++ alpha spending:
#>  User-specified spending function with Points = 0.01, Points = 0.05, Points = 0.1, Points = 0.25, Points = 0.5, Points = 1.
#> * Sample size ratio compared to fixed design with no interim
#> 
#> Boundary crossing probabilities and expected sample size
#> assume any cross stops the trial
#> 
#> Upper boundary (power or Type I Error)
#>           Analysis
#>    Theta      1      2      3      4      5      6 Total   E{N}
#>   0.0000 0.0002 0.0010 0.0013 0.0038 0.0063 0.0125 0.025 1.0171
#>   3.2415 0.0161 0.1072 0.1626 0.2666 0.2066 0.1409 0.900 0.7282
#> 
#> Lower boundary (futility or Type II Error)
#>           Analysis
#>    Theta     1     2      3      4      5      6 Total
#>   0.0000 2e-04 0.001 0.0013 0.0038 0.0063 0.0125 0.025
#>   3.2415 0e+00 0.000 0.0000 0.0000 0.0000 0.0000 0.000

# get proportion of upper spending under null hypothesis
# at each analysis
y <- x$upper$prob[, 1] / .025

# change to cumulative proportion of spending
for (i in 2:length(y))
  y[i] <- y[i - 1] + y[i]

# this should correspond to input sfupar
round(y, 6)
#> [1] 0.01 0.05 0.10 0.25 0.50 1.00

# plot these cumulative spending points
plot(1:6 / 6, y,
  main = "Pointwise spending function example",
  xlab = "Proportion of final sample size",
  ylab = "Cumulative proportion of spending",
  type = "p"
)

# approximate this with a t-distribution spending function
# by fitting 3 points
tx <- 0:100 / 100
lines(tx, sfTDist(1, tx, c(c(1, 3, 5) / 6, .01, .1, .5))$spend)
text(x = .6, y = .9, labels = "Pointwise Spending Approximated by")
text(x = .6, y = .83, "t-Distribution Spending with 3-point interpolation")

```

--------------------------------

### Using sfTrimmed with gsDesign

Source: https://keaven.github.io/gsDesign/reference/sfSpecial.html

Demonstrates how to incorporate the sfTrimmed spending function into a group sequential design using the gsDesign function. This example shows how to eliminate early efficacy analyses by setting a specific range for spending.

```R
x <- gsDesign(
  k = 4, n.fix = 100, sfu = sfTrimmed,
  sfupar = list(sf = sfHSD, param = 1, trange = c(.3, .9))
)
```

--------------------------------

### Run Lightweight Seasonal Simulation

Source: https://keaven.github.io/gsDesign/articles/MultiSeasonRareEvents.html

Sets up and runs a lightweight simulation for seasonal binomial designs. Use this to quickly assess performance under different scenarios, including fixed and adaptive approaches. Ensure `gsDesign` package is installed and relevant design objects are defined.

```r
ve_scenarios <- c(`H0 (VE=30%)` = ve0, `H1 (VE=80%)` = ve1)
planned_control_event_rates <- rep(seasonal_event_rate_control, length(ve_scenarios))

sim_light <- simBinomialSeasonalExact(
  gsD = design_calendar,
  ve = ve_scenarios,
  nsim = rep(150, length(ve_scenarios)),
  control_event_rate = planned_control_event_rates,
  season_length = season_length_years,
  dropout_rate = dropout_6mo,
  planned_counts = planned_counts,
  enroll_control_per_look = planned_enrollment_control,
  enroll_experimental_per_look = planned_enrollment_experimental,
  adaptive = c(FALSE, TRUE),
  max_multiplier = 2,
  final_full_spending = TRUE,
  seed = 101
)
```

--------------------------------

### Plotting Logistic Spending Function Examples

Source: https://keaven.github.io/gsDesign/reference/sfDistribution.html

Demonstrates how to plot various logistic spending functions using the sfLogistic function. It shows how to fit the function to specific points and illustrates different parameterizations, including a=0 and b=1.

```R
# start by showing how to fit two points with sfLogistic
# plot the spending function using many points to obtain a smooth curve
# note that curve fits the points x=.1,  y=.01 and x=.4,  y=.1
# specified in the 3rd parameter of sfLogistic
t <- 0:100 / 100
plot(t, sfLogistic(1, t, c(.1, .4, .01, .1))$spend,
  xlab = "Proportion of final sample size",
  ylab = "Cumulative Type I error spending",
  main = "Logistic Spending Function Examples",
  type = "l", cex.main = .9
)
lines(t, sfLogistic(1, t, c(.01, .1, .1, .4))$spend, lty = 2)

# now just give a=0 and b=1 as 3rd parameters for sfLogistic
lines(t, sfLogistic(1, t, c(0, 1))$spend, lty = 3)

# try a couple with unconventional shapes again using
# the xy form in the 3rd parameter
lines(t, sfLogistic(1, t, c(.4, .6, .1, .7))$spend, lty = 4)
lines(t, sfLogistic(1, t, c(.1, .7, .4, .6))$spend, lty = 5)
legend(
  x = c(.0, .475), y = c(.76, 1.03),
  lty = 1:5,
  legend = c(
    "Fit (.1, 01) and (.4, .1)", "Fit (.01, .1) and (.1, .4)",
    "a=0,  b=1", "Fit (.4, .1) and (.6, .7)",
    "Fit (.1, .4) and (.7, .6)"
  )
)

```

--------------------------------

### Calculate sequential p-value using exact binomial probabilities

Source: https://keaven.github.io/gsDesign/reference/sequentialPValueBinomialExact.html

This example shows how to compute the sequential p-value using the `sequentialPValueBinomialExact` function. It requires a `gsSurv` object, the planned event counts at each analysis, and the observed event counts in the experimental arm.

```R
counts <- toBinomialExact(x)$n.I
sequentialPValueBinomialExact(gsD = x, n.I = counts, x = c(12, 23, 38))
```

--------------------------------

### Seasonal design with integer conversion

Source: https://keaven.github.io/gsDesign/articles/toInteger.html

This example shows the application of `toInteger()` to a seasonal group sequential design. It compares continuous event targets, sample sizes, and analysis times with their integer counterparts after conversion, highlighting the impact of `roundUpFinal = TRUE` on the final event count and sample size.

```R
seasonal_event_rate_control <- 0.003
season_length <- 0.5
dropout_6mo <- 0.10

season_rate <- -log(1 - seasonal_event_rate_control) / season_length
dropout_rate <- -log(1 - dropout_6mo) / season_length

seasonal_design <- gsSurv(
  k = 3,
  test.type = 4,
  alpha = 0.025,
  beta = 0.1,
  timing = c(1 / 3, 2 / 3),
  sfu = sfHSD,
  sfupar = 1,
  sfl = sfHSD,
  sflpar = -2,
  lambdaC = c(season_rate, 0, season_rate, 0, season_rate, 0),
  S = c(6, 6, 6, 6, 6),
  hr = 0.2,
  hr0 = 0.7,
  eta = dropout_rate,
  gamma = c(1, 0, 1, 0, 1, 0),
  R = c(2, 10, 2, 10, 2, 10),
  T = 42,
  minfup = 6,
  ratio = 3,
  testLower = c(TRUE, FALSE, FALSE)
)

# Continuous event targets and expected enrollment before integer conversion
seasonal_design$n.I
rowSums(seasonal_design$eNC + seasonal_design$eNE)
seasonal_design$T

seasonal_integer <- toInteger(seasonal_design)

data.frame(
  analysis = seq_len(seasonal_design$k),
  continuous_events = round(seasonal_design$n.I, 3),
  integer_events = seasonal_integer$n.I,
  continuous_time = round(seasonal_design$T, 3),
  integer_time = round(seasonal_integer$T, 3),
  integer_enrollment = round(rowSums(seasonal_integer$eNC + seasonal_integer$eNE), 3)
)
```

--------------------------------

### Plot Beta Distribution Spending Functions

Source: https://keaven.github.io/gsDesign/reference/spendingFunction.html

Plots example beta distribution spending functions with varying parameters. This helps visualize how different parameter choices affect the spending of alpha over time. Ensure the 'sfbdist' function is defined before running this code.

```R
t <- 0:100 / 100
plot(
  t, sfbdist(1, t, c(2, 1))$spend,
  type = "l",
  xlab = "Proportion of information",
  ylab = "Cumulative proportion of total spending",
  main = "Beta distribution Spending Function Example"
)
lines(t, sfbdist(1, t, c(6, 4))$spend, lty = 2)
lines(t, sfbdist(1, t, c(.5, .5))$spend, lty = 3)
lines(t, sfbdist(1, t, c(.6, 2))$spend, lty = 4)
legend(
  x = c(.65, 1), y = 1 * c(0, .25), lty = 1:4,
  legend = c("a=2, b=1", "a=6, b=4", "a=0.5, b=0.5", "a=0.6, b=2")
)
```

--------------------------------

### Calculate Expected Sample Size using gsDesign

Source: https://keaven.github.io/gsDesign/reference/normalGrid.html

Demonstrates how to find the expected sample size for a default group sequential design using the gsDesign function. This example shows the output of the gsDesign function, including boundary crossing probabilities and expected sample size.

```R
# find expected sample size for default design with
# n.fix=1000
x <- gsDesign(n.fix = 1000)
x
#> Asymmetric two-sided group sequential design with
#> 90 % power and 2.5 % Type I Error.
#> Upper bound spending computations assume
#> trial continues if lower bound is crossed.
#> 
#>                   ----Lower bounds----  ----Upper bounds-----
#>   Analysis   N    Z   Nominal p Spend+  Z   Nominal p Spend++
#>          1  357 -0.24    0.4057 0.0148 3.01    0.0013  0.0013
#>          2  714  0.94    0.8267 0.0289 2.55    0.0054  0.0049
#>          3 1070  2.00    0.9772 0.0563 2.00    0.0228  0.0188
#>      Total                      0.1000                 0.0250 
#> + lower bound beta spending (under H1):
#>  Hwang-Shih-DeCani spending function with gamma = -2.
#> ++ alpha spending:
#>  Hwang-Shih-DeCani spending function with gamma = -4.
#> 
#> Boundary crossing probabilities and expected sample size
#> assume any cross stops the trial
#> 
#> Upper boundary (power or Type I Error)
#>           Analysis
#>    Theta      1      2      3  Total  E{N}
#>   0.0000 0.0013 0.0049 0.0171 0.0233 624.9
#>   0.1025 0.1412 0.4403 0.3185 0.9000 791.3
#> 
#> Lower boundary (futility or Type II Error)
#>           Analysis
#>    Theta      1      2      3  Total
#>   0.0000 0.4057 0.4290 0.1420 0.9767
#>   0.1025 0.0148 0.0289 0.0563 0.1000
```

--------------------------------

### Calculate Group Sequential Design with gsSurv

Source: https://keaven.github.io/gsDesign/reference/nSurv.html

Calculates parameters for a group sequential survival design using the gsSurv function. This example uses the same assumptions as the nSurv example but incorporates group sequential boundaries.

```R
x_gs <- gsSurv(
  k = 4, sfl = gsDesign::sfPower, sflpar = .5, lambdaC = log(2) / 6, hr = .5,
  eta = .001, gamma = 1, T = 36, minfup = 12, method = "LachinFoulkes"
)
print(x_gs)
```

--------------------------------

### Setting Randomization Ratio

Source: https://keaven.github.io/gsDesign/articles/SurvivalOverview.html

Sets the randomization ratio to 1 for subsequent examples.

```r
r <- 1
```

--------------------------------

### eEvents with Multiple Enrollment Periods and Piecewise Exponential Failure Rates

Source: https://keaven.github.io/gsDesign/reference/eEvents.html

Demonstrates setting up the eEvents function with three distinct enrollment periods, each having a different exponential failure rate (lambda), and specified eta, gamma, R, and S parameters. The output shows the structure of the returned list, including dimension names for lambda and eta corresponding to enrollment periods.

```R
str(eEvents(
  lambda = c(.05, .02, .01), eta = .01, gamma = c(5, 10, 20),
  R = c(2, 1, 2), S = c(1, 1), T = 20
))
```

--------------------------------

### Basic Group Sequential Design

Source: https://keaven.github.io/gsDesign/articles/gsDesignPackageOverview.html

Creates a basic group sequential design with default parameters. Use this for a quick setup of a standard design.

```R
library(gsDesign)

x <- gsDesign(n.fix = 200)
plot(x)
```

--------------------------------

### Set up a group sequential design

Source: https://keaven.github.io/gsDesign/reference/gsBoundCP.html

This snippet demonstrates how to initialize a group sequential design object using the gsDesign function with specified parameters.

```R
x <- gsDesign(k = 5)
x
```

--------------------------------

### Derive Minimum Follow-up with Fixed Enrollment

Source: https://keaven.github.io/gsDesign/reference/nSurv.html

If minimum follow-up (`minfup`) is `NULL`, `nSurv` calculates `minfup` and `T` based on fixed enrollment duration(s) (`R`) and specified enrollment rates (`gamma`) to achieve desired power. This method may fail if parameters lead to over- or under-powering.

```R
nSurv(R = fixed_R, minfup = NULL, gamma = rates)
```

--------------------------------

### Derive Group Sequential Design

Source: https://keaven.github.io/gsDesign/reference/sequentiaPValue.html

This example first derives a group sequential design using `gsSurv` and then uses this design to compute sequential p-values.

```R
# Derive Group Sequential Design 
x <- gsSurv(k = 4, alpha = 0.025, beta = 0.1, timing = c(.5,.65,.8), sfu = sfLDOF,
            sfl = sfHSD, sflpar = 2, lambdaC = log(2)/6, hr = 0.6,
            eta = 0.01 , gamma = c(2.5,5,7.5,10), R = c( 2,2,2,6 ),
            T = 30 , minfup = 18)
x$n.I
#
# Analysis at IA2
sequentialPValue(gsD=x,n.I=c(100,160),Z=c(1.5,2))
#
# Use planned spending instead of information fraction; do final analysis
seqp <- sequentialPValue(gsD=x,n.I=c(100,160,190,230),Z=c(1.5,2,2.5,3),usTime=x$timing)
seqp
```

--------------------------------

### Define Calendar Times for Analysis

Source: https://keaven.github.io/gsDesign/articles/PoissonMixtureModel.html

Specifies the calendar times from the start of randomization until each analysis time. This is used in conjunction with the gsSurvCalendar() function for study design.

```R
calendarTime <- c(14, 24, 36, 48)
```

--------------------------------

### Retrieve Initial Approximate Bounds

Source: https://keaven.github.io/gsDesign/articles/VaccineEfficacy.html

Extracts the initial approximate lower and upper bounds for a binomial exact design. These values are often used as a starting point for further adjustments.

```r
xb$init_approx$a
```

```r
xb$init_approx$b
```

--------------------------------

### sfLDOF(), sfLDPocock(), sfHSD(), sfPower(), sfExponential(), sfLogistic(), sfBetaDist(), sfCauchy(), sfExtremeValue(), sfExtremeValue2(), sfNormal(), sfTDist(), sfLinear(), sfStep(), sfPoints(), sfTruncated(), sfTrimmed(), sfGapped(), sfXG1(), sfXG2(), sfXG3()

Source: https://keaven.github.io/gsDesign/reference/index.html

Specific implementations of various spending functions for group sequential designs.

```APIDOC
## Specific Spending Function Implementations

### Description
These functions provide specific implementations of various spending functions, including Lan-DeMets (LDOF, LDPocock), Hwang-Shih-DeCani (HSD), Kim-DeMets (power), exponential, logistic, beta distribution, Cauchy, extreme value, t-distribution, piecewise linear, step, pointwise, truncated, trimmed, gapped, and Xi and Gallo conditional error functions. They allow for flexible control over Type I error allocation across analyses.

### Method
Function Call

### Endpoint
N/A (R function)

### Parameters
(Parameters are specific to each function, often including `alpha`, `beta`, `timing`, and shape parameters.)

### Request Example
```R
# Example for sfHSD
sfHSD(alpha = 0.05, t = c(0.25, 0.5, 0.75, 1))

# Example for sfPower
sfPower(alpha = 0.05, t = c(0.25, 0.5, 0.75, 1), gamma = 2)
```

### Response
Returns the calculated spending function values at specified analysis timings.
```

--------------------------------

### Biomarker Subgroup Design for Overall Stratified Population

Source: https://keaven.github.io/gsDesign/articles/gsSurvPower.html

Design a trial for a biomarker subgroup and assess power for the overall stratified population. This example uses gsSurvCalendar to design for the biomarker-positive subgroup first.

```R
prevalence <- 0.6
median_bm_pos <- 12    # control median in biomarker+ (months)
median_bm_neg <- 10    # control median in biomarker- (shorter prognosis)

bm_design <- gsSurvCalendar(
  test.type = 4, alpha = 0.0125, beta = 0.1,
  sfu = sfHSD, sfupar = -4, sfl = sfHSD, sflpar = -2,
  calendarTime = c(12, 24, 36),
  lambdaC = log(2) / median_bm_pos, hr = 0.65, eta = 0.01,
  gamma = 10, R = 18, minfup = 18, ratio = 1
)

summary(bm_design)
```

```R
gsBoundSummary(bm_design)
```

--------------------------------

### SAS ceiling-time design data

Source: https://keaven.github.io/gsDesign/articles/SeqDesignSurvival.html

Defines R data frames to store the ceiling-time analysis results from a SAS PROC SEQDESIGN survival example. These values are used for comparison with gsDesign outputs.

```R
sas_ceiling_time <- data.frame(
  Analysis = 1:4,
  Events = c(25.11225, 48.22068, 69.38712, 92.92776),
  Calendar_time = c(12, 17, 21, 26),
  N = c(180, 255, 270, 270),
  Upper_Z = c(4.15591, 2.90189, 2.36973, 2.01362)
)
```

--------------------------------

### Step Function Spending in Group Sequential Design

Source: https://keaven.github.io/gsDesign/reference/sfLinear.html

Demonstrates how to use the sfStep spending function with specific parameters to create a group sequential design. This can lead to a large jump in alpha spending at the first analysis.

```r
x <- gsDesign(k = 2, delta = .05, sfu = sfStep, sfupar = c(.02, .001), timing = .02, test.type = 1)
# spending jumps from miniscule to full alpha at first analysis after interim 1
plot(x, pl = "sf")
```

--------------------------------

### Design Trial with Kim-DeMets Spending Function

Source: https://keaven.github.io/gsDesign/reference/sfDistribution.html

Illustrates how to design a 4-analysis trial using the Kim-DeMets spending function (sfPower) for both lower and upper bounds with specified parameters.

```R
library(ggplot2)
# design a 4-analysis trial using a Kim-DeMets spending function
# for both lower and upper bounds
x <- gsDesign(k = 4, sfu = sfPower, sfupar = 3, sfl = sfPower, sflpar = 1.5)
```

--------------------------------

### SAS fractional-time design data

Source: https://keaven.github.io/gsDesign/articles/SeqDesignSurvival.html

Defines R data frames to store the fractional-time analysis results from a SAS PROC SEQDESIGN survival example. These values are used for comparison with gsDesign outputs.

```R
sas_fractional <- data.frame(
  Analysis = 1:4,
  Events = c(22.26962, 44.53924, 66.80886, 89.07847),
  Calendar_time = c(11.2631, 16.2875, 20.4926, 25.13323),
  N = c(168.95, 244.31, 270.00, 270.00),
  Upper_Z = c(4.33263, 2.96333, 2.35902, 2.01409)
)
```

--------------------------------

### Failing gsDesign: testUpper must be TRUE at final analysis

Source: https://keaven.github.io/gsDesign/articles/SelectiveBoundTesting.html

This example demonstrates a validation error when `testUpper` is FALSE at the final analysis, violating rule 1. The `try()` function is used to catch the expected error.

```R
try(gsDesign(k = 3, test.type = 3, testUpper = c(TRUE, TRUE, FALSE)))
#> Error in gsTestBoundsCheck(x$k, x$test.type, testUpper, testLower, testHarm) : 
#>   testUpper must be TRUE at the final analysis
```

--------------------------------

### as_table(), as_gt(), as_rtf()

Source: https://keaven.github.io/gsDesign/reference/index.html

Functions for creating and exporting summary tables from gsDesign objects.

```APIDOC
## Summary Table Functions

### Description
These functions allow users to create summary tables from gsDesign objects (`as_table`), convert these tables to `gt` objects for enhanced formatting (`as_gt`), and save them as RTF files (`as_rtf`). This facilitates reporting and presentation of design characteristics.

### Method
Function Call

### Endpoint
N/A (R function)

### Parameters
(Parameters typically include the design object or summary table object.)

### Request Example
```R
# Assuming 'design' is a gsDesign object
summary_table <- as_table(design)

# Convert to gt object for display or further manipulation
# gt_table <- as_gt(summary_table)

# Save as RTF
# as_rtf(summary_table, "design_summary.rtf")
```

### Response
Returns a summary table object, a `gt` object, or saves a file.
```

--------------------------------

### GNU GPL Startup Notice for Interactive Programs

Source: https://keaven.github.io/gsDesign/LICENSE.html

Display this notice when an interactive program starts to inform users about its free software status and warranty limitations. It directs users to commands for more details on terms and conditions.

```text
<program>  Copyright (C) <year>  <name of author>
This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type 'show c' for details.
```

--------------------------------

### Print Methods for gsSurv and nSurv Objects

Source: https://keaven.github.io/gsDesign/reference/nSurv.html

Provides `print()`, `xtable()`, and `summary()` methods for operating on `gsSurv` and `nSurv` objects. These methods help in displaying and summarizing the results of survival analysis calculations.

```R
print()
xtable()
summary()
```

--------------------------------

### Generate LaTeX table from gsSurv object using xtable

Source: https://keaven.github.io/gsDesign/reference/nSurv.html

Use the xtable method to convert a gsSurv object into a LaTeX table format. This is useful for reporting trial results in publications. Ensure the xtable package is installed.

```R
print(xtable::xtable(x_gs,
  footnote = "This is a footnote; note that it can be wide.",
  caption = "Caption example for xtable output."
))
```

--------------------------------

### Summarize gsBinomialExact object

Source: https://keaven.github.io/gsDesign/reference/as_table.html

This snippet demonstrates how to create a summary table from a gsBinomialExact object using the as_table function and then format it for display with as_gt.

```R
b <- binomialSPRT(p0 = .1, p1 = .35, alpha = .08, beta = .2, minn = 10, maxn = 25)
b_power <- gsBinomialExact(
  k = length(b$n.I), theta = seq(.1, .45, .05), n.I = b$n.I,
  a = b$lower$bound, b = b$upper$bound
)
b_power |
  as_table() |
  as_gt()
```

--------------------------------

### Summarize Power Bounds for Slower Enrollment Scenario

Source: https://keaven.github.io/gsDesign/articles/gsSurvPower.html

Provides a detailed summary of the efficacy and futility bounds, sample size, event counts, and timing for each analysis stage under a slower enrollment scenario.

```R
pwr_slow_simple |> gsBoundSummary()
```

--------------------------------

### Usage of Two-Parameter Spending Functions

Source: https://keaven.github.io/gsDesign/reference/sfDistribution.html

Demonstrates the calling sequence for various two-parameter spending functions. These functions are primarily used within `gsDesign()` to specify spending function families for trial bounds.

```R
sfLogistic(alpha, t, param)

sfBetaDist(alpha, t, param)

sfCauchy(alpha, t, param)

sfExtremeValue(alpha, t, param)

sfExtremeValue2(alpha, t, param)

sfNormal(alpha, t, param)
```

--------------------------------

### Failing gsDesign: No bound active at analysis 1

Source: https://keaven.github.io/gsDesign/articles/SelectiveBoundTesting.html

This example shows a validation error where no bound (efficacy or futility) is active at the first analysis (IA1), violating rule 2. The `try()` function is used to catch the expected error.

```R
try(gsDesign(k = 3, test.type = 4,
  testUpper = c(FALSE, TRUE, TRUE),
  testLower = c(FALSE, TRUE, TRUE)
))
#> Error in gsTestBoundsCheck(x$k, x$test.type, testUpper, testLower, testHarm) : 
#>   At analysis 1 at least one of testUpper, testLower, or testHarm must be TRUE
```

--------------------------------

### Limits of sfTDist: sfNormal and sfCauchy

Source: https://keaven.github.io/gsDesign/reference/sfTDist.html

Shows how sfNormal (infinite df) and sfCauchy (1 df) represent the limits of what sfTDist can fit, illustrating the range of possible spending for the third point.

```R
# sfCauchy (sfTDist with 1 df) and sfNormal (sfTDist with infinite df)
# show the limits of what sfTdist can fit
# for the third point are u3 from 0.344 to 0.6 when t3=0.75
sfNormal(1, 1:3 / 4, c(.25, .5, .1, .2))$spend[3]
#> [1] 0.3439558
sfCauchy(1, 1:3 / 4, c(.25, .5, .1, .2))$spend[3]
#> [1] 0.6
```

--------------------------------

### Step Spending Function for Alpha

Source: https://keaven.github.io/gsDesign/reference/sfLinear.html

Applies a step spending function for alpha, where spending occurs at specific thresholds, combined with a fixed sample size. This example also shows how to adjust interim analysis timing while keeping spending the same.

```r
sfupar <- c(.2, .4, .9, ((1:3) / 3)^3)
x <- gsDesign(k = 3, n.fix = 100, sfu = sfStep, sfupar = sfupar, test.type = 1)
plot(x, pl = "sf")

# original planned sample sizes
ceiling(x$n.I)

# cumulative spending planned at original interims
cumsum(x$upper$spend)

# change timing of analyses;
# note that cumulative spending "P(Cross) if delta=0" does not change from cumsum(x$upper$spend)
# while full alpha is spent, power is reduced by reduced sample size
y <- gsDesign(
  k = 3, sfu = sfStep, sfupar = sfupar, test.type = 1,
  maxn.IPlan = x$n.I[x$k], n.I = c(30, 70, 95),
  n.fix = x$n.fix
)
```

--------------------------------

### Handle Insufficient Sample Sizes

Source: https://keaven.github.io/gsDesign/reference/gsBinomialExact.html

Illustrates a scenario where the provided range of sample sizes might be insufficient to achieve the desired power. This code block is commented out and intended for demonstration purposes, highlighting the need to ensure an adequate sample size range.

```R
if (FALSE) { # \dontrun{ 
  nBinomial1Sample(p0 = 0.05, p1 = 0.2, alpha = 0.025, beta = .2, n = 25:30)
} # }
```

--------------------------------

### summary() and print() for gsDesign and gsBoundSummary

Source: https://keaven.github.io/gsDesign/reference/index.html

Provides summary and detailed print methods for group sequential designs and boundary summaries.

```APIDOC
## summary(gsDesign) / print(gsDesign) / gsBoundSummary() / xprint() / print(gsBoundSummary())

### Description
Provides summary and detailed print methods for group sequential designs and boundary summaries. Used to inspect the characteristics of a derived design.

### Method
Function Call

### Endpoint
N/A (R function)

### Parameters
(Specific parameters typically include the design object.)

### Request Example
```R
# Assuming 'design' is a gsDesign object
summary(design)
print(design)

# Assuming 'bound_summary' is a gsBoundSummary object
print(bound_summary)
```

### Response
Prints a summary or detailed information about the design or boundary summary.
```

--------------------------------

### Calculate repeated p-values for a gsSurv object

Source: https://keaven.github.io/gsDesign/reference/repeatedPValueBinomialExact.html

This example demonstrates how to use repeatedPValueBinomialExact to compute repeated p-values. It first creates a gsSurv object, then extracts the planned event counts, and finally calls the function with observed event counts.

```R
x <- gsSurv(
  k = 3, test.type = 4, alpha = 0.025, beta = 0.1, timing = c(0.45, 0.7),
  sfu = sfHSD, sfupar = -4, sfl = sfLDOF, sflpar = 0,
  lambdaC = 0.001, hr = 0.3, hr0 = 0.7, eta = 5e-04,
  gamma = 10, R = 16, T = 24, minfup = 8, ratio = 3
)
counts <- toBinomialExact(x)$n.I
repeatedPValueBinomialExact(gsD = x, n.I = counts, x = c(12, 23, 38))
```

--------------------------------

### tEventsIA(), nEventsIA(), nSurv(), gsSurv(), print.nSurv(), xtable.gsSurv(), print.gsSurv()

Source: https://keaven.github.io/gsDesign/reference/index.html

Advanced functions for time-to-event sample size calculation and group sequential survival designs.

```APIDOC
## tEventsIA(), nEventsIA(), nSurv(), gsSurv(), print.nSurv(), xtable.gsSurv(), print.gsSurv()

### Description
These functions provide advanced capabilities for time-to-event endpoints, including calculating the number of events and sample size for interim analyses, and designing group sequential survival studies. Includes methods for printing and creating tables of these designs.

### Method
Function Call

### Endpoint
N/A (R function)

### Parameters
(Parameters vary by function but typically involve hazard rates, accrual times, follow-up times, alpha, beta.)

### Request Example
```R
# Example for nSurv
nSurv(lambda1 = 0.5, lambda2 = 0.2, T = 2, alpha = 0.05, beta = 0.1)

# Example for gsSurv
gsSurv(lambda1 = 0.5, lambda2 = 0.2, T = 2, k = 3, alpha = 0.05, beta = 0.1)
```

### Response
Returns calculated sample sizes, event counts, or design objects.
```
Tokens:
Raw