Help for package PDXpower

Type:

Package

Title:

Time to Event Outcome in Experimental Designs of Pre-Clinical Studies

Version:

1.0.4

Date:

2025-01-24

Maintainer:

Shanpeng Li <lishanpeng0913@ucla.edu>

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.

License:

GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]

Encoding:

UTF-8

Depends:

R (≥ 3.5.0),survival,stats,parallel

Imports:

nlme,ggplot2,ggpubr,frailtypack

RoxygenNote:

7.2.3

Suggests:

testthat (≥ 3.0.0), spelling

Language:

en-US

LazyData:

true

NeedsCompilation:

Packaged:

2025-01-24 19:25:23 UTC; shanpengli

Author:

Shanpeng Li [aut, cre], Gang Li [ctb]

Repository:

CRAN

Date/Publication:

2025-01-24 19:40:02 UTC

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
)

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))

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
)

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))

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
)

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))

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
)

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))

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
)

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))

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
)

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)

Simulated preliminary animals uncensored data

Description

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

Usage

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)

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"
)

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.

Print PowerTable

Description

Print PowerTable

Usage

## 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 lishanpeng0913@ucla.edu

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 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 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

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

Print PowerTable

Description

Usage

Arguments

Value

Author(s)

See Also