Package 'earlygating'

Title: Properties of Bayesian Early Gating Designs
Description: Computes the most important properties of four 'Bayesian' early gating designs (two single arm and two randomized controlled designs), such as minimum required number of successes in the experimental group to make a GO decision, operating characteristics and average operating characteristics with respect to the sample size. These might aid in deciding what design to use for the early phase trial.
Authors: Elias Laurin Meyer [aut, cre]
Maintainer: Elias Laurin Meyer <[email protected]>
License: GPL-3
Version: 1.1
Built: 2025-02-12 04:25:34 UTC
Source: https://github.com/el-meyer/earlygating

Help Index


Single Arm Average Operating Characteristics

Description

Function for calculating the average operating characteristics of two single arm bayesian designs for early gating with respect to the sample size in the experimental group and possible historical data.

Usage

avg_oc_wr_ne(
  N_e,
  true_RR_c = NULL,
  delta,
  delta_power,
  confidence,
  e_a = 0.5,
  e_b = 0.5,
  h_a = 0.5,
  h_b = 0.5,
  RR_h = NULL,
  N_h = NULL,
  hist_RR_c = NULL,
  alpha_c,
  beta_c,
  trues = seq(0, 1, 0.001),
  adapt = 1,
  plot = T,
  coresnum = NULL,
  legend = T,
  legend.pos = "topleft"
)

Arguments

N_e

Sample Size in the experimental group. Can be either a single value or a vector.

true_RR_c

Default value is NULL. If specified, will be used in the generated plots, indicating the true achieved decision power and decision type 1 error. If not specified, will be set to either RR_h or hist_RR_c, depending on which was specified by the user.

delta

Required superiority to make a "GO" decision. Corresponds to δ\delta.

delta_power

Superiority, at which decision power will be evaluated. Corresponds to δˉ\bar{\delta}.

confidence

Required confidence to make "GO" decision. Corresponds to γ\gamma.

e_a

Alpha parameter of Beta Prior Distribution for the experimental response rate. Corresponds to αe\alpha_e. Default is 12\frac{1}{2}.

e_b

Beta parameter of Beta Prior Distribution for the experimental response rate. Corresponds to βe\beta_e. Default is 12\frac{1}{2}.

h_a

Alpha parameter of Beta Prior Distribution for the historical control response rate. Corresponds to αh\alpha_h. Only needs to be specified, if RR_h and N_h are also specified. Default is 12\frac{1}{2}.

h_b

Beta parameter of Beta Prior Distribution for the historical control response rate. Corresponds to βh\beta_h. Only needs to be specified, if RR_h and N_h are also specified. Default is 12\frac{1}{2}.

RR_h

Historical control response rate. Corresponds to php_h. If specified together with N_h, function will use setting 2 from pdf.

N_h

Historical control sample size. Corresponds to nhn_h. If specified together with RR_h, function will use setting 2 from pdf.

hist_RR_c

Point estimate of historical control repsonse rate. Corresponds to ph^\hat{p_h}. If specified, while RR_h and N_h are not specified, function will use setting 1 from pdf.

alpha_c

Alpha parameter of Beta Distribution for the control response rate used to calculate average operating characteristics. Corresponds to αc\alpha_c.

beta_c

Beta parameter of Beta Distribution for the control response rate used to calculate average operating characteristics. Corresponds to βc\beta_c.

trues

Sequence of true control response rates and experimental response rates, at which the Probability to Go will be computed. Default is seq(0,1,0.01) to ensure continuous plots and accurate results.

adapt

Level of adapting of experimental control rate to account for patient selection bias from phase II to phase III. Corresponds to ξ\xi. Default is 1, so no adapting.

plot

Plots yes or no. Default is TRUE.

coresnum

Number of cores used for parallel computing, in case N_e is a vector. Default is the number of total cores - 1.

legend

Logical; whether or not to include legend in plot. Default is TRUE.

legend.pos

Position of legend. Default is "topleft".

Value

Either a vector containing the average decision power and average alpha (if N_e has length 1), or a matrix containing the average decision power and average decision alpha (if N_e has length > 1), where every row corresponds to one value of N_e.

Examples

# Setting 1
avg_oc_wr_ne(
  N_e = 50, delta = 0.08, delta_power = 0.13,
  confidence = 0.6, hist_RR_c = 0.5,
  alpha_c = 15, beta_c = 13
)

# Setting 2
avg_oc_wr_ne(
  N_e = 50, delta = 0.08, delta_power = 0.13,
  confidence = 0.6, RR_h = 0.5, N_h = 50,
  alpha_c = 15, beta_c = 13
)

RCT Average Operating Characteristics

Description

Function for calculating the average operating characteristics of two RCT bayesian designs for early gating with respect to the sample size in the experimental group, the sample size in the control group and possible historical data.

Usage

avg_oc_wr_ne_rct(
  N_c,
  N_e,
  delta,
  delta_power,
  confidence,
  e_a = 0.5,
  e_b = 0.5,
  c_a = 0.5,
  c_b = 0.5,
  h_a = 0.5,
  h_b = 0.5,
  N_h = NULL,
  RR_h = NULL,
  w = NULL,
  alpha_c,
  beta_c,
  trues = seq(0, 1, 0.01),
  plot = T,
  coresnum = NULL,
  legend = T,
  legend.pos = "topleft"
)

Arguments

N_c

Sample Size in the control group. Can be either a single value or a vector, but needs to be the same length as N_e.

N_e

Sample Size in the experimental group. Can be either a single value or a vector, but needs to be the same length as N_c.

delta

Required superiority to make a "GO" decision. Corresponds to δ\delta.

delta_power

Superiority, at which decision power will be evaluated. Corresponds to δˉ\bar{\delta}.

confidence

Required confidence to make "GO" decision. Corresponds to γ\gamma.

e_a

Alpha parameter of Beta Prior Distribution for the experimental response rate. Corresponds to αe\alpha_e. Default is 12\frac{1}{2}.

e_b

Beta parameter of Beta Prior Distribution for the experimental response rate. Corresponds to βe\beta_e. Default is 12\frac{1}{2}.

c_a

Alpha parameter of Beta Prior Distribution for the control response rate. Corresponds to αc\alpha_c. Default is 12\frac{1}{2}.

c_b

Beta parameter of Beta Prior Distribution for the control response rate. Corresponds to βc\beta_c. Default is 12\frac{1}{2}.

h_a

Alpha parameter of Beta Prior Distribution for the historical control response rate. Corresponds to αh\alpha_h. Only needs to be specified, if RR_h, N_h and w are also specified. Default is 12\frac{1}{2}.

h_b

Beta parameter of Beta Prior Distribution for the historical control response rate. Corresponds to βh\beta_h. Only needs to be specified, if RR_h, N_h and w are also specified. Default is 12\frac{1}{2}.

N_h

Historical control sample size. Corresponds to nhn_h. If specified together with RR_h and w, function will use setting 4 from pdf.

RR_h

Historical control response rate. Corresponds to php_h. If specified together with N_h and w, function will use setting 4 from pdf.

w

Level of dynmaic borrowing. Corresponds to ww.

alpha_c

Alpha parameter of Beta Distribution for the control response rate used to calculate average operating characteristics. Corresponds to αc\alpha_c.

beta_c

Beta parameter of Beta Distribution for the control response rate used to calculate average operating characteristics. Corresponds to βc\beta_c.

trues

Sequence of true control response rates and experimental response rates, at which the Probability to Go will be computed. Default is seq(0,1,0.01) to ensure continuous plots and accurate results.

plot

Plots yes or no. Default is TRUE.

coresnum

Number of cores used for parallel computing, in case N_e is a vector. Default is the number of total cores - 1.

legend

Logical; whether or not to include legend in plot. Default is TRUE.

legend.pos

Position of legend. Default is "topleft".

Value

Either a vector containing the average decision power and average alpha (if N_e has length 1) or a matrix containing the average decision power and average decision alpha (if N_e has length > 1), where every row corresponds to one value of N_e.

Examples

# Setting 3
avg_oc_wr_ne_rct(
N_c = 25, N_e = 25, delta = 0.08,
delta_power = 0.13, confidence = 0.6,
alpha_c = 15, beta_c = 13
)



# Setting 4
avg_oc_wr_ne_rct(
N_c = 25, N_e = 25, delta = 0.08,
delta_power = 0.13, confidence = 0.6,
alpha_c = 15, beta_c = 13,
RR_h = 0.5, N_h = 100, w = 0.3
)

Average operating characteristics with respect to historic target

Description

Function for calculating the average operating characteristics of a single arm Bayesian designs for early gating with respect to the historic target.

Usage

avg_oc_wr_ph(
  N_e,
  delta,
  delta_power,
  confidence,
  e_a = 0.5,
  e_b = 0.5,
  alpha_c,
  beta_c,
  trues = seq(0, 1, 0.01),
  adapt = 1,
  plot = T,
  legend = T,
  legend.pos = "topleft"
)

Arguments

N_e

Sample Size in the experimental group. Can be either a single value or a vector.

delta

Required superiority to make a "GO" decision. Corresponds to δ\delta.

delta_power

Superiority, at which decision power will be evaluated. Corresponds to δˉ\bar{\delta}.

confidence

Required confidence to make "GO" decision. Corresponds to γ\gamma.

e_a

Alpha parameter of Beta Prior Distribution for the experimental response rate. Corresponds to αe\alpha_e. Default is 12\frac{1}{2}.

e_b

Beta parameter of Beta Prior Distribution for the experimental response rate. Corresponds to βe\beta_e. Default is 12\frac{1}{2}.

alpha_c

Alpha parameter of Beta Distribution for the control response rate used to calculate average operating characteristics. Corresponds to αc\alpha_c.

beta_c

Beta parameter of Beta Distribution for the control response rate used to calculate average operating characteristics. Corresponds to βc\beta_c.

trues

Sequence of true control response rates and experimental response rates, at which the Probability to Go will be computed. Default is seq(0,1,0.01) to ensure continuous plots and accurate results.

adapt

Level of adapting of experimental control rate to account for patient selection bias from phase II to phase III. Corresponds to ξ\xi. Default is 1, so no adapting.

plot

Plots yes or no. Default is TRUE.

legend

Logical; whether or not to include legend in plot. Default is TRUE.

legend.pos

Position of legend. Default is "topleft".

Value

A matrix containing information about the decision power and the decision alpha with respect to p_h.

Examples

avg_oc_wr_ph(
  N_e = 50, delta = 0.08, delta_power = 0.13,
  confidence = 0.6, alpha_c = 15, beta_c = 13
)

Parameters of Beta distribution given Historical Data

Description

Function for calculating the parameters of the beta distribution used to average the operating characteristics, given historical data.

Usage

beta_par(
  mu_cov,
  phi_cov = NULL,
  orr,
  data,
  newdata,
  link = NULL,
  weights = NULL,
  plot = T
)

Arguments

mu_cov

A character vector containing the names of covariates in data that should be used to model the parameter μ\mu in the pdf.

phi_cov

A character vector containing the names of covariates in data that should be used to model the parameter ϕ\phi in the pdf. Default is NULL, so ϕ\phi will not be modelled with respect to the covariates.

orr

Character containing the name of the variable in data that represents the objective response rate.

data

Data frame containing all the covariates and the ORR.

newdata

Data frame containing a single value for each of the specified covariates that will be used to estimate the parameters of the Beta distribution.

link

Link function for μ\mu. Corresponds to gg. Default is NULL, which means the link function will be automatically chosen as the one yielding the highest log-likelihood for the given data and covariates.

weights

Weights that should be used for regression. Default is NULL, so no weights.

plot

Plots yes or no. Default is TRUE.

Examples

mu_cov <- c("date", "Phase")
orr <- "ORR"
newdata <- data.frame(
  "date" = 2017,
  "Phase" = factor(3)
  )
studs <- data.frame(
  "ORR"= c(0.693, 0.580, 0.693, 0.477, 0.609,
           0.727, 0.727, 0.591, 0.362, 0.593,
           0.792, 0.620, 0.550, 0.690, 0.776),
  "date" = c(2011, 2008.5, 2009, 1996, 2001,
             2003.5, 2002.5, 2008, 2000,
             2006, 2005, 2007.5, 2009.5,
             2010.5, 2010),
   "Phase" = factor(c(3, 2, 3, 3, 2, 2, 3, 3,
                      3, 3, 2, 3, 3, 3, 2)),
   "N" = c(293, 69, 336, 235, 92, 110, 131,
           208, 94, 123, 53, 182, 267, 239, 237)
 )

beta_par(
  mu_cov = mu_cov,
  orr = orr,
  data = studs,
  newdata = newdata,
  weights = studs$N/mean(studs$N)
)

Single Arm Operating Characteristics

Description

Function for calculating the operating characteristics of the single arm Bayesian designs in setting 1 and 2 for early gating.

Usage

oc(
  N_e,
  delta,
  delta_power,
  confidence,
  e_a = 0.5,
  e_b = 0.5,
  h_a = 0.5,
  h_b = 0.5,
  RR_h = NULL,
  N_h = NULL,
  hist_RR_c = NULL,
  trues = seq(0, 1, 0.01),
  adapt = 1,
  plot = T,
  legend = T,
  legend.pos = "topleft"
)

Arguments

N_e

Sample Size in the experimental group. Can be either a single value or a vector.

delta

Required superiority to make a "GO" decision. Corresponds to δ\delta.

delta_power

Superiority, at which decision power will be evaluated. Corresponds to δˉ\bar{\delta}.

confidence

Required confidence to make "GO" decision. Corresponds to γ\gamma.

e_a

Alpha parameter of Beta Prior Distribution for the experimental response rate. Corresponds to αe\alpha_e. Default is 12\frac{1}{2}.

e_b

Beta parameter of Beta Prior Distribution for the experimental response rate. Corresponds to βe\beta_e. Default is 12\frac{1}{2}.

h_a

Alpha parameter of Beta Prior Distribution for the historical control response rate. Corresponds to αh\alpha_h. Only needs to be specified, if RR_h and N_h are also specified. Default is 12\frac{1}{2}.

h_b

Beta parameter of Beta Prior Distribution for the historical control response rate. Corresponds to βh\beta_h. Only needs to be specified, if RR_h and N_h are also specified. Default is 12\frac{1}{2}.

RR_h

Historical control response rate. Corresponds to php_h. If specified together with N_h, function will use setting 2 from pdf.

N_h

Historical control sample size. Corresponds to nhn_h. If specified together with RR_h, function will use setting 2 from pdf.

hist_RR_c

Point estimate of historical control repsonse rate. Corresponds to ph^\hat{p_h}. If specified, while RR_h and N_h are not specified, function will use setting 1 from pdf.

trues

Sequence of true control response rates and experimental response rates, at which the Probability to Go will be computed. Default is seq(0,1,0.01) to ensure continuous plots and accurate results.

adapt

Level of adapting of experimental control rate to account for patient selection bias from phase II to phase III. Corresponds to ξ\xi. Default is 1, so no adapting.

plot

Plots yes or no. Default is TRUE.

legend

Logical; whether or not to include legend in plot. Default is TRUE.

legend.pos

Position of legend. Default is "topleft".

Value

A matrix containing the decision power and decision alpha with respect to the true control response rate.

Examples

# Setting 1
oc(
  N_e = 50, delta = 0.08, delta_power = 0.13,
  confidence = 0.6, hist_RR_c = 0.5
)

# Setting 2
oc(
  N_e = 50, delta = 0.08, delta_power = 0.13,
  confidence = 0.6, RR_h = 0.5, N_h = 50
)

RCT Operating Characteristics

Description

Function for calculating the operating characteristics of the RCT Bayesian designs in setting 3 and 4 for early gating.

Usage

oc_rct(
  N_c,
  N_e,
  delta,
  delta_power,
  confidence,
  e_a = 0.5,
  e_b = 0.5,
  c_a = 0.5,
  c_b = 0.5,
  h_a = 0.5,
  h_b = 0.5,
  RR_h = NULL,
  N_h = NULL,
  w = NULL,
  trues = seq(0, 1, 0.01),
  plot = T,
  legend = T,
  legend.pos = "topleft"
)

Arguments

N_c

Sample Size in the control group. Can be either a single value or a vector, but needs to be the same length as N_e.

N_e

Sample Size in the experimental group. Can be either a single value or a vector, but needs to be the same length as N_c.

delta

Required superiority to make a "GO" decision. Corresponds to δ\delta.

delta_power

Superiority, at which decision power will be evaluated. Corresponds to δˉ\bar{\delta}.

confidence

Required confidence to make "GO" decision. Corresponds to γ\gamma.

e_a

Alpha parameter of Beta Prior Distribution for the experimental response rate. Corresponds to αe\alpha_e. Default is 12\frac{1}{2}.

e_b

Beta parameter of Beta Prior Distribution for the experimental response rate. Corresponds to βe\beta_e. Default is 12\frac{1}{2}.

c_a

Alpha parameter of Beta Prior Distribution for the control response rate. Corresponds to αc\alpha_c. Default is 12\frac{1}{2}.

c_b

Beta parameter of Beta Prior Distribution for the control response rate. Corresponds to βc\beta_c. Default is 12\frac{1}{2}.

h_a

Alpha parameter of Beta Prior Distribution for the historical control response rate. Corresponds to αh\alpha_h. Only needs to be specified, if RR_h, N_h and w are also specified. Default is 12\frac{1}{2}.

h_b

Beta parameter of Beta Prior Distribution for the historical control response rate. Corresponds to βh\beta_h. Only needs to be specified, if RR_h, N_h and w are also specified. Default is 12\frac{1}{2}.

RR_h

Historical control response rate. Corresponds to php_h. If specified together with N_h and w, function will use setting 4 from pdf.

N_h

Historical control sample size. Corresponds to nhn_h. If specified together with RR_h and w, function will use setting 4 from pdf.

w

Level of dynmaic borrowing. Corresponds to ww.

trues

Sequence of true control response rates and experimental response rates, at which the Probability to Go will be computed. Default is seq(0,1,0.01) to ensure continuous plots and accurate results.

plot

Plots yes or no. Default is TRUE.

legend

Logical; whether or not to include legend in plot. Default is TRUE.

legend.pos

Position of legend. Default is "topleft".

Value

A matrix containing the decision power and decision alpha with respect to the true control response rate.

Examples

# Setting 3
oc_rct(
  N_c = 25, N_e = 25, delta = 0.08,
  delta_power = 0.13, confidence = 0.6
)

# Setting 4
oc_rct(
  N_c = 25, N_e = 25, delta = 0.08,
  delta_power = 0.13, confidence = 0.6,
  RR_h = 0.5, N_h = 50, w = 0.3
)

Required Responders for GO decision Single Arm

Description

Function for calculating the minimum required number of responders in the experimental group to make a GO decision in Settings 1 and 2.

Usage

req_resp(
  N_e,
  delta,
  confidence,
  e_a = 0.5,
  e_b = 0.5,
  h_a = 0.5,
  h_b = 0.5,
  RR_h = NULL,
  N_h = NULL,
  hist_RR_c = NULL,
  adapt = 1
)

Arguments

N_e

Sample Size in the experimental group.

delta

Required superiority to make a "GO" decision. Corresponds to δ\delta.

confidence

Required confidence to make "GO" decision. Corresponds to γ\gamma.

e_a

Alpha parameter of Beta Prior Distribution for the experimental response rate. Corresponds to αe\alpha_e. Default is 12\frac{1}{2}.

e_b

Beta parameter of Beta Prior Distribution for the experimental response rate. Corresponds to βe\beta_e. Default is 12\frac{1}{2}.

h_a

Alpha parameter of Beta Prior Distribution for the historical control response rate. Corresponds to αh\alpha_h. Only needs to be specified, if RR_h and N_h are also specified. Default is 12\frac{1}{2}.

h_b

Beta parameter of Beta Prior Distribution for the historical control response rate. Corresponds to βh\beta_h. Only needs to be specified, if RR_h and N_h are also specified. Default is 12\frac{1}{2}.

RR_h

Historical control response rate. Corresponds to php_h. If specified together with N_h, function will use setting 2 from pdf.

N_h

Historical control sample size. Corresponds to nhn_h. If specified together with RR_h, function will use setting 2 from pdf.

hist_RR_c

Point estimate of historical control repsonse rate. Corresponds to ph^\hat{p_h}. If specified, while RR_h and N_h are not specified, function will use setting 1 from pdf.

adapt

Level of adapting of experimental control rate to account for patient selection bias from phase II to phase III. Corresponds to ξ\xi. Default is 1, so no adapting.

Value

Integer.

Examples

# Setting 1
req_resp(
  N_e = 50, delta = 0.08,
  confidence = 0.6, hist_RR_c = 0.5
)

# Setting 2
req_resp(
  N_e = 50, delta = 0.08,
  confidence = 0.6, RR_h = 0.5, N_h = 50
)

Required Responders for GO decision RCT

Description

Function for calculating the minimum required number of responders in the experimental group to make a GO decision in Settings 3 and 4.

Usage

req_resp_rct(
  N_c,
  N_e,
  delta,
  confidence,
  e_a = 0.5,
  e_b = 0.5,
  c_a = 0.5,
  c_b = 0.5,
  h_a = 0.5,
  h_b = 0.5,
  RR_h = NULL,
  N_h = NULL,
  w = NULL,
  plot = T
)

Arguments

N_c

Sample Size in the control group.

N_e

Sample Size in the experimental group.

delta

Required superiority to make a "GO" decision. Corresponds to δ\delta.

confidence

Required confidence to make "GO" decision. Corresponds to γ\gamma.

e_a

Alpha parameter of Beta Prior Distribution for the experimental response rate. Corresponds to αe\alpha_e. Default is 12\frac{1}{2}.

e_b

Beta parameter of Beta Prior Distribution for the experimental response rate. Corresponds to βe\beta_e. Default is 12\frac{1}{2}.

c_a

Alpha parameter of Beta Prior Distribution for the control response rate. Corresponds to αc\alpha_c. Default is 12\frac{1}{2}.

c_b

Beta parameter of Beta Prior Distribution for the control response rate. Corresponds to βc\beta_c. Default is 12\frac{1}{2}.

h_a

Alpha parameter of Beta Prior Distribution for the historical control response rate. Corresponds to αh\alpha_h. Only needs to be specified, if RR_h, N_h and w are also specified. Default is 12\frac{1}{2}.

h_b

Beta parameter of Beta Prior Distribution for the historical control response rate. Corresponds to βh\beta_h. Only needs to be specified, if RR_h, N_h and w are also specified. Default is 12\frac{1}{2}.

RR_h

Historical control response rate. Corresponds to php_h. If specified together with N_h and w, function will use setting 4 from pdf.

N_h

Historical control sample size. Corresponds to nhn_h. If specified together with RR_h and w, function will use setting 4 from pdf.

w

Level of dynmaic borrowing. Corresponds to ww.

plot

Plots yes or no. Default is TRUE.

Value

Matrix containing pairs of successes in control group and respective required successes in experimental group.

Examples

# Setting 3
req_resp_rct(
  N_c = 25, N_e = 25,
  delta = 0.08, confidence = 0.6
)

# Setting 4
req_resp_rct(
  N_c = 25, N_e = 25,
  delta = 0.08, confidence = 0.6,
  RR_h = 0.5, N_h = 50, w = 0.3
)