Package 'PDXpower' reference manual

Title:	Time to Event Outcome in Experimental Designs of Pre-Clinical Studies
Description:	Conduct simulation-based customized power calculation for clustered time to event data in a mixed crossed/nested design, where a number of cell lines and a number of mice within each cell line are considered to achieve a desired statistical power, motivated by Eckel-Passow and colleagues (2021) <doi:10.1093/neuonc/noab137> and Li and colleagues (2024) <doi:10.48550/arXiv.2404.08927>. This package provides two commonly used models for powering a design, linear mixed effects and Cox frailty model. Both models account for within-subject (cell line) correlation while holding different distributional assumptions about the outcome. Alternatively, the counterparts of fixed effects model are also available, which produces similar estimates of statistical power.
Authors:	Shanpeng Li [aut, cre], Gang Li [ctb]
Maintainer:	Shanpeng Li <[email protected]>
License:	GPL (>= 2)
Version:	1.0.3
Built:	2024-10-29 03:01:25 UTC
Source:	https://github.com/shanpengli/pdxpower

Simulated preliminary animals uncensored data

Description

The animals1 data frame has 18 rows and 3 columns, with all uncensored observations.

Usage

data(animals1)
data(animals1)

Format

This data frame contains the following columns:

ID: PDX line identifier.
Y: time-to-event variable.
Tx: treatment indicator. 0 denotes the placebo group and 1 the treatment group.

Simulated preliminary animals censored data

Description

The animals2 data frame has 18 rows and 4 columns, with some censored observations.

Usage

data(animals2)
data(animals2)

Format

This data frame contains the following columns:

ID: PDX line identifier.
Y: time-to-event variable.
Tx: treatment indicator. 0 denotes the placebo group and 1 the treatment group.
status: event status. 0 denotes right-censoring and 1 the event occurs.

A function to generate a four-panel power curve under specified number of PDX lines and number of individuals per PDX lines per treatment

Description

A function to generate a four-panel power curve under specified number of PDX lines and number of individuals per PDX lines per treatment

Usage

plotpower(
  object,
  ylim = c(0, 0.1),
  x.axis.n.breaks = 10,
  y.axis.n.breaks = 10,
  cut.off = 0.8,
  legend.position = "right"
)
plotpower(
  object,
  ylim = c(0, 0.1),
  x.axis.n.breaks = 10,
  y.axis.n.breaks = 10,
  cut.off = 0.8,
  legend.position = "right"
)

Arguments

`object`	object of class 'PowerTable'.
`ylim`	limit of y axis.
`x.axis.n.breaks`	number of breaks of the x axis. Default is 10.
`y.axis.n.breaks`	number of breaks of the y axis. Default is 10.
`cut.off`	a number to indicate the cut-off for power analysis. Default is 0.8.
`legend.position`	the position of legends ("none", "left", "right", "bottom", "top", or two-element numeric vector).

Value

a figure generated by ggplot.

A function to obtain a power table with the combination of various number of PDX lines and number of individuals per PDX lines per treatment based on a prior knowledge of median survival

Description

A function to obtain a power table with the combination of various number of PDX lines and number of individuals per PDX lines per treatment based on a prior knowledge of median survival

Usage

PowANOVA(
  ctl.med.surv = 2.4,
  tx.med.surv = 4.8,
  tau2 = NULL,
  icc = 0.1,
  sigma2 = 1,
  n = NULL,
  m = NULL,
  sim = 100,
  two.sided = TRUE,
  alpha = 0.05,
  fixed.effect = FALSE,
  ncores = NULL
)
PowANOVA(
  ctl.med.surv = 2.4,
  tx.med.surv = 4.8,
  tau2 = NULL,
  icc = 0.1,
  sigma2 = 1,
  n = NULL,
  m = NULL,
  sim = 100,
  two.sided = TRUE,
  alpha = 0.05,
  fixed.effect = FALSE,
  ncores = NULL
)

Arguments

`ctl.med.surv`	a numeric value of the hypothesized medial survival in the control arm. Default is 2.4.
`tx.med.surv`	a numeric value of the hypothesized medial survival in the treatment arm. Default is 4.8.
`tau2`	variance of PDX line specific random effect. Default is NULL. tau2 should be specified only when `icc` is set as NULL.
`icc`	intraclass correlation coefficient. Default is 0.1. If `icc` is specified, then tau2 will be calculated automatically. Otherwise, `tau2` must be specified.
`sigma2`	variance of random error.
`n`	an integer number to specify the number of PDX lines.
`m`	an integer number to specify the number of individuals per PDX line per treatment.
`sim`	Number of Monte Carlo samples to be generated. Default is 100.
`two.sided`	A logical value to indicate if a two-sided hypothesis testing is conducted. Default is TRUE.
`alpha`	significance level. Default is 0.05.
`fixed.effect`	logical value to indicate if a fixed effects only model is fitted. Default is FALSE.
`ncores`	number of cores for parallel computation.

Value

Object of PowANOVA with elements

PowTab

the estimates of statistical power across n and m.

Examples


require(PDXpower)
PowTab <- PowANOVA(ctl.med.surv = 2.4, tx.med.surv = 4.8, sim = 5, icc = 0.4,
n = 3, m = 2, ncores = 1)
PowTab
plotpower(PowTab, ylim = c(0, 1))

require(PDXpower)
PowTab <- PowANOVA(ctl.med.surv = 2.4, tx.med.surv = 4.8, sim = 5, icc = 0.4,
n = 3, m = 2, ncores = 1)
PowTab
plotpower(PowTab, ylim = c(0, 1))

A function to obtain a power table with the combination of various number of PDX lines and number of individuals per PDX lines per treatment based on a preliminary dataset

Description

A function to obtain a power table with the combination of various number of PDX lines and number of individuals per PDX lines per treatment based on a preliminary dataset

Usage

PowANOVADat(
  data = NULL,
  formula = NULL,
  random = NULL,
  n = NULL,
  m = NULL,
  sim = 100,
  two.sided = TRUE,
  alpha = 0.05,
  fixed.effect = FALSE,
  digits = 4,
  ncores = NULL
)
PowANOVADat(
  data = NULL,
  formula = NULL,
  random = NULL,
  n = NULL,
  m = NULL,
  sim = 100,
  two.sided = TRUE,
  alpha = 0.05,
  fixed.effect = FALSE,
  digits = 4,
  ncores = NULL
)

Arguments

`data`	data.frame in which to interpret the variables named in the formula.
`formula`	a two-sided linear formula object describing the fixed-effects part of the model, with the response on the left of a ~ operator and the terms, separated by + operators, on the right.
`random`	an one-sided formula of the form `~ x1 + ... + xn \| ID`.
`n`	an integer number to specify the number of PDX lines.
`m`	an integer number to specify the number of individuals per PDX line per treatment.
`sim`	Number of Monte Carlo samples to be generated. Default is 1000.
`two.sided`	a logical value to indicate if a two-sided hypothesis testing is conducted. Default is TRUE.
`alpha`	significance level. Default is 0.05.
`fixed.effect`	logical value to indicate if a fixed effects only model is fitted. Default is FALSE.
`digits`	digits the number of significant digits to use when printing.
`ncores`	number of cores for parallel computation.

Value

Object of PowANOVADat with elements

`beta`	the estimated treatment effect from the pilot data.
`tau2`	the estimated inter-PDX variance from the pilot data.
`sigma2`	the estimated random error variance from the pilot data.
`PowTab`	the estimates of statistical power across `n` and `m`.

Examples


require(PDXpower)
data(animals1)
PowTab <- PowANOVADat(data = animals1, formula = log(Y) ~ Tx, random = ~ 1|ID,
n = 3, m = 2, ncores = 1)
PowTab
plotpower(PowTab[[4]], ylim = c(0, 1))

require(PDXpower)
data(animals1)
PowTab <- PowANOVADat(data = animals1, formula = log(Y) ~ Tx, random = ~ 1|ID,
n = 3, m = 2, ncores = 1)
PowTab
plotpower(PowTab[[4]], ylim = c(0, 1))

A function to obtain a power table with the combination of various number of PDX lines and number of individuals per PDX lines per treatment.

Description

A function to obtain a power table with the combination of various number of PDX lines and number of individuals per PDX lines per treatment.

Usage

PowerTable(
  n,
  m,
  beta,
  tau2 = 0.5,
  alpha = 0.05,
  lambda = 0.03,
  nu = 2,
  sigma2 = 1,
  two.sided = TRUE,
  distr = c("Weibull", "normal"),
  Ct = 5,
  censor = TRUE,
  sim = 1000,
  print = c("both", "ANOVA", "Cox-frailty"),
  fixed.effect = FALSE,
  ncores = NULL
)
PowerTable(
  n,
  m,
  beta,
  tau2 = 0.5,
  alpha = 0.05,
  lambda = 0.03,
  nu = 2,
  sigma2 = 1,
  two.sided = TRUE,
  distr = c("Weibull", "normal"),
  Ct = 5,
  censor = TRUE,
  sim = 1000,
  print = c("both", "ANOVA", "Cox-frailty"),
  fixed.effect = FALSE,
  ncores = NULL
)

Arguments

`n`	an integer number to specify the number of PDX lines.
`m`	an integer number to specify the number of individuals per PDX line per treatment.
`beta`	Treatment effect for the treated group.
`tau2`	variance of PDX line specific random effect.
`alpha`	significance level. Default is 0.05.
`lambda`	Scale parameter of Weibull distribution for the baseline hazard.
`nu`	Shape parameter of Weibull distribution for the baseline hazard.
`sigma2`	Error variance of log survival time for both treatment groups.
`two.sided`	A logical value to indicate if a two-sided hypothesis testing is conducted. Default is TRUE.
`distr`	Distributional assumption of the simulated event time.
`Ct`	a fixed time point when a study is designed to end for generating type 1 censoring data.
`censor`	logical value of whether a censoring distribution is considered in a data generation setting. Default is TRUE.
`sim`	Number of Monte Carlo samples to be generated. Default is 1000.
`print`	a string to indicate which model result to be printed. If `print = "both"`, then the power curves of both models will be printed. Otherwise, print a power curve from one of the two models by specifying either `print = "ANOVA"` or `print = "Cox-frailty"`.
`fixed.effect`	logical value to indicate if a fixed effects only model is fitted. Default is FALSE.
`ncores`	number of cores for parallel computation.

Value

Object of class PowerTable with elements

`NofLine`	the number of PDX line `n`.
`NofAnimals`	the number of animals per arm per PDX line `m`.
`ANOVArandom`	the proportion of rejecting null treatment effect by fitting a ANOVA mixed effects model.
`Coxrandom`	the proportion of rejecting null treatment effect by fitting a Cox frailty model.
`ANOVAfix`	the proportion of rejecting null treatment effect by fitting a ANOVA fixed effects model if `fixed.effects = TRUE`.
`Coxfix`	the proportion of rejecting null treatment effect by fitting a Cox fixed effects model if `fixed.effects = TRUE`.
`censoringrate`	the average censoring rate across all Monte Carlo replicates.
`beta`	the pre-determined treatment effect.
`lambda`	the pre-determined scale parameter of baseline hazard for the Cox frailty model.
`nu`	the pre-determined shape parameter of baseline hazard for the Cox frailty model.
`tau2`	the pre-determined inter-PDX variance.
`Ct`	the pre-determined fixed time point to indicate the end of a study for type I censoring.
`nsim`	total number of Monte Carlo replicates.
`sigma2`	the pre-determined error variance for the ANOVA mixed effects model.
`censor`	a logical value to indicate whether type I censoring mechanism is considered for simulation.
`print`	a string to indicate which model is considered for simulation.
`fixed.effect`	a logical value to indicate whether a fixed effects model is considered for simulation.
`call`	match call.

Examples

n <- 3
m <- 2
beta <- 0.8
lambda <- 0.3
nu <- 1
tau2 <- 0.1

fit <- PowerTable(n = n, m = m, beta = beta, lambda = lambda, nu = nu,
                  tau2 = tau2, distr = "Weibull", sim = 5,
                  censor = FALSE,
                  print = "both", ncores = 1)
plotpower(fit, ylim = c(0, 1))


n <- 3
m <- 2
beta <- 0.8
lambda <- 0.3
nu <- 1
tau2 <- 0.1

fit <- PowerTable(n = n, m = m, beta = beta, lambda = lambda, nu = nu,
                  tau2 = tau2, distr = "Weibull", sim = 5,
                  censor = FALSE,
                  print = "both", ncores = 1)
plotpower(fit, ylim = c(0, 1))

A function to obtain a power table with the combination of various number of PDX lines and number of individuals per PDX lines per treatment based on a prior knowledge of median survival

Description

A function to obtain a power table with the combination of various number of PDX lines and number of individuals per PDX lines per treatment based on a prior knowledge of median survival

Usage

PowFrailty(
  ctl.med.surv = 2.4,
  tx.med.surv = 4.8,
  nu = 1,
  tau2 = 0.1,
  n = NULL,
  m = NULL,
  sim = 1000,
  censor = FALSE,
  Ct = 5,
  two.sided = TRUE,
  alpha = 0.05,
  fixed.effect = FALSE,
  ncores = NULL
)
PowFrailty(
  ctl.med.surv = 2.4,
  tx.med.surv = 4.8,
  nu = 1,
  tau2 = 0.1,
  n = NULL,
  m = NULL,
  sim = 1000,
  censor = FALSE,
  Ct = 5,
  two.sided = TRUE,
  alpha = 0.05,
  fixed.effect = FALSE,
  ncores = NULL
)

Arguments

`ctl.med.surv`	a numeric value of the hypothesized medial survival in the control arm. Default is 2.4.
`tx.med.surv`	a numeric value of the hypothesized medial survival in the treatment arm. Default is 4.8.
`nu`	shape parameter of Weibull distribution for the baseline hazard. Default is 1, i.e., constant failure rate.
`tau2`	variance of PDX line specific random effect. Default is 0.1.
`n`	an integer number to specify the number of PDX lines.
`m`	an integer number to specify the number of individuals per PDX line per treatment.
`sim`	Number of Monte Carlo samples to be generated. Default is 1000.
`censor`	logical value of whether a censoring distribution is considered in a data generation setting. Default is FALSE.
`Ct`	a fixed time point when a study is designed to end for generating type 1 censoring data.
`two.sided`	A logical value to indicate if a two-sided hypothesis testing is conducted. Default is TRUE.
`alpha`	significance level. Default is 0.05.
`fixed.effect`	logical value to indicate if a fixed effects only model is fitted. Default is FALSE.
`ncores`	number of cores for parallel computation.

Value

Object of PowFrailty with elements

PowTab

the estimates of statistical power across n and m.

Examples


require(PDXpower)
PowTab <- PowFrailty(ctl.med.surv = 2.4, tx.med.surv = 4.8, sim = 100,
n = 3, m = 2, ncores = 1)
PowTab
plotpower(PowTab, ylim = c(0, 1))

require(PDXpower)
PowTab <- PowFrailty(ctl.med.surv = 2.4, tx.med.surv = 4.8, sim = 100,
n = 3, m = 2, ncores = 1)
PowTab
plotpower(PowTab, ylim = c(0, 1))

A function to obtain a power table with the combination of various number of PDX lines and number of individuals per PDX lines per treatment based on a preliminary dataset

Description

A function to obtain a power table with the combination of various number of PDX lines and number of individuals per PDX lines per treatment based on a preliminary dataset

Usage

PowFrailtyDat(
  data = NULL,
  formula = NULL,
  maxit = 50,
  hazard = "Weibull",
  n = NULL,
  m = NULL,
  sim = 1000,
  censor = FALSE,
  Ct = 5,
  two.sided = TRUE,
  alpha = 0.05,
  fixed.effect = FALSE,
  digits = 4,
  ncores = NULL
)
PowFrailtyDat(
  data = NULL,
  formula = NULL,
  maxit = 50,
  hazard = "Weibull",
  n = NULL,
  m = NULL,
  sim = 1000,
  censor = FALSE,
  Ct = 5,
  two.sided = TRUE,
  alpha = 0.05,
  fixed.effect = FALSE,
  digits = 4,
  ncores = NULL
)

Arguments

`data`	data.frame in which to interpret the variables named in the formula.
`formula`	a formula object, with the response on the left of a ~ operator, and the terms on the right. The response must be a survival object as returned by the Surv function.
`maxit`	maximum number of iterations needed for model fitting. Default is 50.
`hazard`	distributional assumption of the baseline hazard. Default is Weibull.
`n`	an integer number to specify the number of PDX lines.
`m`	an integer number to specify the number of individuals per PDX line per treatment.
`sim`	Number of Monte Carlo samples to be generated. Default is 1000.
`censor`	logical value of whether a censoring distribution is considered in a data generation setting. Default is FALSE.
`Ct`	a fixed time point when a study is designed to end for generating type 1 censoring data.
`two.sided`	A logical value to indicate if a two-sided hypothesis testing is conducted. Default is TRUE.
`alpha`	significance level. Default is 0.05.
`fixed.effect`	logical value to indicate if a fixed effects only model is fitted. Default is FALSE.
`digits`	digits the number of significant digits to use when printing.
`ncores`	number of cores for parallel computation.

Value

Object of PowFrailtyDat with elements

`lambda`	the estimated scale parameter of Weibull baseline hazard from the pilot data.
`nu`	the estimated shape parameter of Weibull baseline hazard from the pilot data.
`beta`	the estimated treatment effect from the pilot data.
`tau2`	the estimated inter-PDX variance from the pilot data.
`sigma2`	the estimated random error variance from the pilot data.
`PowTab`	the estimates of statistical power across `n` and `m`.

Examples


require(PDXpower)
data(animals2)
PowTab <- PowFrailtyDat(data = animals2, formula = Surv(Y,status) ~ Tx + cluster(ID),
n = 3, m = 2, ncores = 1)
PowTab
plotpower(PowTab[[5]], ylim = c(0, 1))


require(PDXpower)
data(animals2)
PowTab <- PowFrailtyDat(data = animals2, formula = Surv(Y,status) ~ Tx + cluster(ID),
n = 3, m = 2, ncores = 1)
PowTab
plotpower(PowTab[[5]], ylim = c(0, 1))

Print PowerTable

Description

Print PowerTable

Usage

## S3 method for class 'PowerTable'
print(x, digits = 2, ...)
## S3 method for class 'PowerTable'
print(x, digits = 2, ...)

Arguments

`x`	object of class 'PowerTable'.
`digits`	the number of significant digits to use when printing.
`...`	Further arguments passed to or from other methods.

Value

Object of print.PowerTable with elements

data

a data frame of estimated power across all combinations and n and m.

Author(s)

Shanpeng Li [email protected]

A function to calculate the power under pre-specified effect size, variance, and correlation using Monte Carlo sampling scheme by fitting ANOVA fixed effects model, ANOVA random effects model, Cox model, and frailty model.

Description

A function to calculate the power under pre-specified effect size, variance, and correlation using Monte Carlo sampling scheme

Usage

SimPDXdata(
  seed = 1000,
  n,
  m,
  beta,
  tau2,
  lambda = 0.03,
  nu = 2,
  sigma2 = 1,
  distr = c("Weibull", "normal"),
  two.sided = TRUE,
  Ct = 5,
  censor = TRUE
)
SimPDXdata(
  seed = 1000,
  n,
  m,
  beta,
  tau2,
  lambda = 0.03,
  nu = 2,
  sigma2 = 1,
  distr = c("Weibull", "normal"),
  two.sided = TRUE,
  Ct = 5,
  censor = TRUE
)

Arguments

`seed`	an integer random seed number.
`n`	an integer number to specify the number of PDX lines.
`m`	an integer number to specify the number of individuals per PDX line per treatment.
`beta`	Treatment effect for the treated group.
`tau2`	Error variance of random effect.
`lambda`	Scale parameter of Weibull distribution for the baseline hazard.
`nu`	Shape parameter of Weibull distribution for the baseline hazard.
`sigma2`	Error variance of log survival time for both treatment groups.
`distr`	distributional assumption of survival time.
`two.sided`	a logical value to indicate if a two-sided test is performed. Default is TRUE.
`Ct`	a fixed time point when a study is designed to end for generating type 1 censoring data.
`censor`	logical value of whether a censoring distribution is considered in a data generation setting. Default is TRUE.

Value

Object of SimPDXdata with elements

Data

a simulated data.

Examples

require(PDXpower)
data <- SimPDXdata(n = 5, m = 3, beta = 0.8, sigma2 = 1, tau2 = 0.1,
                   distr = "normal", censor = FALSE)
require(PDXpower)
data <- SimPDXdata(n = 5, m = 3, beta = 0.8, sigma2 = 1, tau2 = 0.1,
                   distr = "normal", censor = FALSE)

Package 'PDXpower'

Help Index

Simulated preliminary animals uncensored data

Description

Usage

Format

Simulated preliminary animals censored data

Description

Usage

Format

A function to generate a four-panel power curve under specified number of PDX lines and number of individuals per PDX lines per treatment

Description

Usage

Arguments

Value

A function to obtain a power table with the combination of various number of PDX lines and number of individuals per PDX lines per treatment based on a prior knowledge of median survival

Description

Usage

Arguments

Value

Examples

A function to obtain a power table with the combination of various number of PDX lines and number of individuals per PDX lines per treatment based on a preliminary dataset

Description

Usage

Arguments

Value

Examples

A function to obtain a power table with the combination of various number of PDX lines and number of individuals per PDX lines per treatment.

Description

Usage

Arguments

Value

See Also

Examples

A function to obtain a power table with the combination of various number of PDX lines and number of individuals per PDX lines per treatment based on a prior knowledge of median survival

Description

Usage

Arguments

Value

Examples

A function to obtain a power table with the combination of various number of PDX lines and number of individuals per PDX lines per treatment based on a preliminary dataset

Description

Usage

Arguments

Value

Examples

Print PowerTable

Description

Usage

Arguments

Value

Author(s)

See Also

A function to calculate the power under pre-specified effect size, variance, and correlation using Monte Carlo sampling scheme by fitting ANOVA fixed effects model, ANOVA random effects model, Cox model, and frailty model.

Description

Usage

Arguments

Value

Examples