Help for package PDXpower

Type:

Package

Title:

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

Version:

1.0.5

Date:

2025-12-15

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 (2025) <doi:10.51387/25-NEJSDS76>. 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)

Imports:

nlme,ggplot2,ggpubr,frailtypack,stats, survival, parallel, ggplot2

RoxygenNote:

7.3.2

Suggests:

testthat (≥ 3.0.0), spelling

Language:

en-US

LazyData:

true

NeedsCompilation:

Packaged:

2025-12-15 00:47:05 UTC; shanpengli

Author:

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

Repository:

CRAN

Date/Publication:

2025-12-15 01:00: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,
  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.

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

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

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 = 7.2, nu = 1, tau2 = 0.1, sim = 20,
censor = TRUE, Ct = 12, n = 3, m = 4, ncores = 1)
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,
  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.

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)
require(frailtypack)
data(animals2)
PowTab <- PowFrailtyDat(data = animals2,
                        formula = survival::Surv(Y,status) ~ Tx + cluster(ID),
                        n = 3, m = 4,
                        Ct = 12, censor = TRUE,
                        sim = 20, ncores = 1)
plotpower(PowTab[[5]], 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