Package 'NBDesign' reference manual

Title:	Design and Monitoring of Clinical Trials with Negative Binomial Endpoint
Description:	Calculate various functions needed for design and monitoring clinical trials with negative binomial endpoint with variable follow-up. This version has a few changes compared to the previous version 1.0.0, including (1) correct a typo in Type 1 censoring, mtbnull=bnull and (2) restructure the code to account for shape parameter equal to zero, i.e. Poisson scenario.
Authors:	Xiaodong Luo [aut, cre], Sanofi [cph]
Maintainer:	Xiaodong Luo <[email protected]>
License:	GPL (>= 2)
Version:	2.0.0
Built:	2026-06-07 09:44:40 UTC
Source:	https://github.com/cran/NBDesign

Design and Monitoring of Clinical Trials with Negative Binomial Endpoint

Description

Calculate various functions needed for design and monitoring clinical trials with negative binomial endpoint with variable follow-up. This version has a few changes compared to the previous version 1.0.0, including (1) correct a typo in Type 1 censoring, mtbnull=bnull and (2) restructure the code to account for shape parameter equal to zero, i.e. Poisson scenario.

Details

The DESCRIPTION file:

Package:	NBDesign
Type:	Package
Version:	2.0.0
Date:	2020-09-09
Title:	Design and Monitoring of Clinical Trials with Negative Binomial Endpoint
Description:	Calculate various functions needed for design and monitoring clinical trials with negative binomial endpoint with variable follow-up. This version has a few changes compared to the previous version 1.0.0, including (1) correct a typo in Type 1 censoring, mtbnull=bnull and (2) restructure the code to account for shape parameter equal to zero, i.e. Poisson scenario.
Authors@R:	c( person(given="Xiaodong", family="Luo", email = "[email protected]", role =c("aut", "cre")), person("Sanofi", role = "cph"))
Depends:	R (>= 3.1.2)
Imports:	stats,PWEALL,MASS
License:	GPL (>= 2)
RoxygenNote:	5.0.1
LazyData:	true
NeedsCompilation:	no
Packaged:	2020-09-09 12:59:08 UTC; marve
Author:	Xiaodong Luo [aut, cre], Sanofi [cph]
Maintainer:	Xiaodong Luo <[email protected]>
Repository:	https://marvels2031.r-universe.dev
Date/Publication:	2020-09-10 05:30:22 UTC
RemoteUrl:	https://github.com/cran/NBDesign
RemoteRef:	HEAD
RemoteSha:	bdb7d54b1639ee5618df7da65c4f36b60dd363e6

Index of help topics:

NBDesign-package        Design and Monitoring of Clinical Trials with
                        Negative Binomial Endpoint
negint2                 A utility functon to calculate the mean
                        exposure under different scenarios
ynegbinompower          Two-sample sample size calculation for negative
                        binomial distribution with variable follow-up
ynegbinompowersim       Two-sample sample size calculation for negative
                        binomial distribution with variable follow-up
ynegbinomsize           Two-sample sample size calculation for negative
                        binomial distribution with variable follow-up

Author(s)

Xiaodong Luo [aut, cre], Sanofi [cph]

Maintainer: Xiaodong Luo <[email protected]>

A utility functon to calculate the mean exposure under different scenarios

Description

This will calculate the mean exposure under different scenarios: 2: fixed follow-up with drop-out, 3: variable follow-up with a maximum (maxfu), 4: variable follow-up with a maximum and drop-out

Usage

negint2(ux=0.5,fixedfu=1,type=2,u=c(0.5,0.5,1),ut=c(0.5,1.0,1.5),
  tfix=ut[length(ut)]+0.5,maxfu=10.0,tchange=c(0,0.5,1),
  ratec=c(0.15,0.15,0.15),eps=1.0e-03)
negint2(ux=0.5,fixedfu=1,type=2,u=c(0.5,0.5,1),ut=c(0.5,1.0,1.5),
  tfix=ut[length(ut)]+0.5,maxfu=10.0,tchange=c(0,0.5,1),
  ratec=c(0.15,0.15,0.15),eps=1.0e-03)

Arguments

ux

the parameter a in (a*t)/(1+a*t)

fixedfu

the minimum follow-up time

type

follow-up type, type=2: fixed fu with fu time fixedfu but subject to censoring; type=3: depending on entry time, minimum fu is fixedfu and maximum fu is maxfu; type=4: same as 3 but subject to censoring

u

recruitment rate

ut

recruitment interval, must have the same length as u

tfix

fixed study duration, often equals to recruitment time plus minimum follow-up

maxfu

maximum follow-up time, should not be greater than tfix

tchange

a strictly increasing sequence of time points starting from zero at which the drop-out rate changes. The first element of tchange must be zero. The above rates and tchange must have the same length.

ratec

piecewise constant drop-out rate

eps

error tolerance for the numerical intergration

Details

Let $\tau_{min}$ and $\tau_{max}$ correspond to the minimum follow-up time taumin and the maximum follow-up time taumax. Let $T_f$ , $C$ , $E$ and $R$ be the follow-up time, the drop-out time, the study entry time and the total recruitment period( $R$ is the last element of ut). For type 2 follow-up $T_f=min(C,\tau_{min})$ . For type 3 follow-up, $T_f=min(R+\tau_{min}-E,\tau_{max})$ . For type 4 follow-up, $T_f=min(R+\tau_{min}-E,\tau_{max},C)$ . Let $f$ be the density of $T_f$ . We calculate

$\int_0^{\infty} t f(t)dt$

and

$\int_0^{\infty} \frac{a t}{1+a t} f(t)dt$

where $a$ is the ux.

Value

mt

mean of (a*t)/(1+a*t)

tt

mean of t

vt

variance of t

Author(s)

Xiaodong Luo

Examples

##calculating the exposure for type 4 follow-up
exp4=negint2(ux=0.5,fixedfu=1,type=2,u=c(0.5,0.5,1),ut=c(0.5,1.0,1.5),
  tfix=2.0,maxfu=1.0,tchange=c(0,0.5,1),
  ratec=c(0.15,0.15,0.15),eps=1.0e-03)
#mean exposure            
meanexp=exp4$tt
#var exposure
varexp=exp4$vt
c(meanexp,sqrt(varexp))
#mean of (ux*t)/(1+ux*t)
meanuxt=exp4$mt
##calculating the exposure for type 4 follow-up
exp4=negint2(ux=0.5,fixedfu=1,type=2,u=c(0.5,0.5,1),ut=c(0.5,1.0,1.5),
  tfix=2.0,maxfu=1.0,tchange=c(0,0.5,1),
  ratec=c(0.15,0.15,0.15),eps=1.0e-03)
#mean exposure            
meanexp=exp4$tt
#var exposure
varexp=exp4$vt
c(meanexp,sqrt(varexp))
#mean of (ux*t)/(1+ux*t)
meanuxt=exp4$mt

Two-sample sample size calculation for negative binomial distribution with variable follow-up

Description

This will calculate the power for the negative binomial distribution for the 2-sample case under different follow-up scenarios: 1: fixed follow-up, 2: fixed follow-up with drop-out, 3: variable follow-up with a minimum fu and a maximum fu, 4: variable follow-up with a minimum fu and a maximum fu and drop-out.

Usage

ynegbinompower(nsize=200,r0=1.0,r1=0.5,shape0=1,shape1=shape0,pi1=0.5,
     alpha=0.05,twosided=1,fixedfu=1,type=1,u=c(0.5,0.5,1),ut=c(0.5,1.0,1.5),
     tfix=ut[length(ut)]+0.5,maxfu=10.0,tchange=c(0,0.5,1),
     ratec1=c(0.15,0.15,0.15),ratec0=ratec1,eps=1.0e-03)
ynegbinompower(nsize=200,r0=1.0,r1=0.5,shape0=1,shape1=shape0,pi1=0.5,
     alpha=0.05,twosided=1,fixedfu=1,type=1,u=c(0.5,0.5,1),ut=c(0.5,1.0,1.5),
     tfix=ut[length(ut)]+0.5,maxfu=10.0,tchange=c(0,0.5,1),
     ratec1=c(0.15,0.15,0.15),ratec0=ratec1,eps=1.0e-03)

Arguments

nsize

total number of subjects in two groups

r0

event rate for the control

r1

event rate for the treatment

shape0

dispersion parameter for the control

shape1

dispersion parameter for the treatment

pi1

allocation prob for the treatment

alpha

type-1 error

twosided

1: two-side, others: one-sided

fixedfu

fixed follow-up time for each patient

type

follow-up time type, type=1: fixed fu with fu time fixedfu; type=2: same as 1 but subject to censoring; type=3: depending on entry time, minimum fu is fixedfu and maximum fu is maxfu; type=4: same as 3 but subject to censoring

u

recruitment rate

ut

recruitment interval, must have the same length as u

tfix

fixed study duration, often equals to recruitment time plus minimum follow-up

maxfu

maximum follow-up time, should not be greater than tfix

tchange

ratec1

piecewise constant drop-out rate for the treatment

ratec0

piecewise constant drop-out rate for the control

eps

error tolerance for the numerical intergration

Details

Let $\tau_{min}$ and $\tau_{max}$ correspond to the minimum follow-up time fixedfu and the maximum follow-up time maxfu. Let $T_f$ , $C$ , $E$ and $R$ be the follow-up time, the drop-out time, the study entry time and the total recruitment period( $R$ is the last element of ut). For type 1 follow-up, $T_f=\tau_{min}$ . For type 2 follow-up $T_f=min(C,\tau_{min})$ . For type 3 follow-up, $T_f=min(R+\tau_{min}-E,\tau_{max})$ . For type 4 follow-up, $T_f=min(R+\tau_{min}-E,\tau_{max},C)$ . Let $f$ be the density of $T_f$ . Suppose that $Y_i$ is the number of event obsevred in follow-up time $t_i$ for patient $i$ with treatment assignment $Z_i$ , $i=1,\ldots,n$ . Suppose that $Y_i$ follows a negative binomial distribution such that

$P(Y_i=y\mid Z_i=j)=\frac{\Gamma(y+1/k_j)}{\Gamma(y+1)\Gamma(1/k_j)}\Bigg(\frac{k_ju_i}{1+k_ju_i}\Bigg)^y\Bigg(\frac{1}{1+k_ju_i}\Bigg)^{1/k_j},$

where

$\log(u_i)=\log(t_i)+\beta_0+\beta_1 Z_i.$

Let $\hat{\beta}_0$ and $\hat{\beta}_1$ be the MLE of $\beta_0$ and $\beta_1$ . The varaince of $\hat{\beta}_1$ is

$\mbox{var}(\hat{\beta}_1)=1/\tilde{a}_0(r_0)+1/\tilde{a}_1(r_1)$

where

$\tilde{a}_j(r)=\sum_{i=1}^n I(Z_i=j)k_jrt_i/(1+k_jrt_i), \hspace{0.5cm}j=0,1,$

and $k_j, j=0,1$ are the dispersion parameters for control $j=0$ and treatment $j=1$ . Note that Zhu and Lakkis (2014) use

$a_j(r)=\sum_{i=1}^n I(Z_i=j)k_jrE(t_i)/\{1+k_jrE(t_i)\},$

to replace $\tilde{a}_j(r)$ , $j=0,1$ . Using Jensen's inequality, we can show $a_j(r)\ge \tilde{a}_j(r)$ , which means Zhu and Lakkis's method will underestimate variance of $\hat{\beta}_1$ , which leads to either smaller than required sample size or inflated power. For comparison, I provide sample sizes under both $\tilde{a}_j(r)$ and $a_j(r)$ .

Zhu and Lakkis (2014) discuss three types of the variance under the null. The first way is to set $\tilde{r}_0=\tilde{r}_1=r_0$ , using event rate from the control group. The second way is to set $\tilde{r}_0=r_0, \tilde{r}_1=r_1$ , using true event rates. The third way is to set $\tilde{r}_0=\tilde{r}_1=\tilde{r}$ , where $\tilde{r}=\pi_1 r_1+\pi_0 r_0$ , using maximum likelihood estimation.

Therefore, for each type of follow-up, there are 3 sample sizes calculated (because there are 3 varainces under the null) for with and without approximation of Zhu and Lakkis (2014).

Note that PASS14.0 provides 3 ways of null varaince with the default being the MLE. PASS does not allow different dispersion parameters between treatmetn and control. EAST only provides the second way of null varaince but allows for different dispersion parameters. Both of these softwares base on the approximatin method of Zhu and Lakkis (2014), which underestimate the required sample sizes.

Value

tildeXPWR

powers (in percentage) not based on current approach, i.e. not based on the Zhu and Lakkis's approximation

XPWR

powers (in percentage) based on on the Zhu and Lakkis's approximation

tildemineffsize

minimum detectable effect sizes not based on approximation

mineffsize

minimum detectable effect sizes based on approximation

Exposure

mean exposure under different follow-up types with element 1 for control, element 2 for treatment and element 3 for overall.

SDExp

Sd of the exposure under different follow-up types with element 1 for control, element 2 for treatment and column 3 for overall.

Author(s)

Xiaodong Luo

References

Zhu~H and Lakkis~H. Sample size calculation for comparing two negative binomial rates. Statistics in Medicine 2014, 33: 376-387.

Examples

##calculating the sample sizes
abc=ynegbinompower(nsize=200,r0=1.0,r1=0.5,shape0=1,
        pi1=0.5,alpha=0.05,twosided=1,fixedfu=1,
        type=4,u=c(0.5,0.5,1),ut=c(0.5,1.0,1.5),
        tchange=c(0,0.5,1),
        ratec1=c(0.15,0.15,0.15),eps=1.0e-03)
###Zhu and Lakkis's powers (i.e. with approximation) 
abc$XPWR
###Our powers (i.e. without approximation)
abc$tildeXPWR
##calculating the sample sizes
abc=ynegbinompower(nsize=200,r0=1.0,r1=0.5,shape0=1,
        pi1=0.5,alpha=0.05,twosided=1,fixedfu=1,
        type=4,u=c(0.5,0.5,1),ut=c(0.5,1.0,1.5),
        tchange=c(0,0.5,1),
        ratec1=c(0.15,0.15,0.15),eps=1.0e-03)
###Zhu and Lakkis's powers (i.e. with approximation) 
abc$XPWR
###Our powers (i.e. without approximation)
abc$tildeXPWR

Two-sample sample size calculation for negative binomial distribution with variable follow-up

Description

Usage

ynegbinompowersim(nsize=200,r0=1.0,r1=0.5,shape0=1,shape1=shape0,pi1=0.5,
   alpha=0.05,twosided=1,fixedfu=1,type=1,u=c(0.5,0.5,1),ut=c(0.5,1.0,1.5),
   tfix=ut[length(ut)]+0.5,maxfu=10.0,tchange=c(0,0.5,1),
   ratec1=c(0.15,0.15,0.15),ratec0=ratec1,rn=10000)
ynegbinompowersim(nsize=200,r0=1.0,r1=0.5,shape0=1,shape1=shape0,pi1=0.5,
   alpha=0.05,twosided=1,fixedfu=1,type=1,u=c(0.5,0.5,1),ut=c(0.5,1.0,1.5),
   tfix=ut[length(ut)]+0.5,maxfu=10.0,tchange=c(0,0.5,1),
   ratec1=c(0.15,0.15,0.15),ratec0=ratec1,rn=10000)

Arguments

nsize

total number of subjects in two groups

r0

event rate for the control

r1

event rate for the treatment

shape0

dispersion parameter for the control

shape1

dispersion parameter for the treatment

pi1

allocation prob for the treatment

alpha

type-1 error

twosided

1: two-side, others: one-sided

fixedfu

fixed follow-up time for each patient

type

u

recruitment rate

ut

recruitment interval, must have the same length as u

tfix

fixed study duration, often equals to recruitment time plus minimum follow-up

maxfu

maximum follow-up time, should not be greater than tfix

tchange

ratec1

piecewise constant drop-out rate for the treatment

ratec0

piecewise constant drop-out rate for the control

rn

Number of repetitions

Details

$P(Y_i=y\mid Z_i=j)=\frac{\Gamma(y+1/k_j)}{\Gamma(y+1)\Gamma(1/k_j)}\Bigg(\frac{k_ju_i}{1+k_ju_i}\Bigg)^y\Bigg(\frac{1}{1+k_ju_i}\Bigg)^{1/k_j},$

where $k_j, j=0,1$ are the dispersion parameters for control $j=0$ and treatment $j=1$ and

$\log(u_i)=\log(t_i)+\beta_0+\beta_1 Z_i.$

The data will be gnerated according to the above model. Note that the piecewise exponential distribution and the piecewise uniform distribution are genrated using R package PWEALL functions "rpwe" and "rpwu", respectively.

The parameters in the model are estimated by MLE using the R package MASS function "glm.nb".

Value

power

simulation power (in percentage)

Author(s)

Xiaodong Luo

Examples

##calculating the sample sizes
abc=ynegbinompowersim(nsize=200,r0=1.0,r1=0.5,shape0=1,
        pi1=0.5,alpha=0.05,twosided=1,fixedfu=1,
        type=4,u=c(0.5,0.5,1),ut=c(0.5,1.0,1.5),
        tchange=c(0,0.5,1),
        ratec1=c(0.15,0.15,0.15),rn=10)
###Power
abc$power
##calculating the sample sizes
abc=ynegbinompowersim(nsize=200,r0=1.0,r1=0.5,shape0=1,
        pi1=0.5,alpha=0.05,twosided=1,fixedfu=1,
        type=4,u=c(0.5,0.5,1),ut=c(0.5,1.0,1.5),
        tchange=c(0,0.5,1),
        ratec1=c(0.15,0.15,0.15),rn=10)
###Power
abc$power

Two-sample sample size calculation for negative binomial distribution with variable follow-up

Description

This will calculate the sample size for the negative binomial distribution for the 2-sample case under different follow-up scenarios: 1: fixed follow-up, 2: fixed follow-up with drop-out, 3: variable follow-up with a minimum fu and a maximum fu, 4: variable follow-up with a minimum fu and a maximum fu and drop-out.

Usage

ynegbinomsize(r0=1.0,r1=0.5,shape0=1,shape1=shape0,pi1=0.5,
      alpha=0.05,twosided=1,beta=0.2,fixedfu=1,
      type=1,u=c(0.5,0.5,1),ut=c(0.5,1.0,1.5),tfix=ut[length(ut)]+0.5,maxfu=10.0,
      tchange=c(0,0.5,1),ratec1=c(0.15,0.15,0.15),ratec0=ratec1,eps=1.0e-03)
ynegbinomsize(r0=1.0,r1=0.5,shape0=1,shape1=shape0,pi1=0.5,
      alpha=0.05,twosided=1,beta=0.2,fixedfu=1,
      type=1,u=c(0.5,0.5,1),ut=c(0.5,1.0,1.5),tfix=ut[length(ut)]+0.5,maxfu=10.0,
      tchange=c(0,0.5,1),ratec1=c(0.15,0.15,0.15),ratec0=ratec1,eps=1.0e-03)

Arguments

r0

event rate for the control

r1

event rate for the treatment

shape0

dispersion parameter for the control

shape1

dispersion parameter for the treatment

pi1

allocation prob for the treatment

alpha

type-1 error

twosided

1: two-side, others: one-sided

beta

tyep-2 error

fixedfu

fixed follow-up time for each patient

type

u

recruitment rate

ut

recruitment interval, must have the same length as u

tfix

fixed study duration, often equals to recruitment time plus minimum follow-up fixedfu

maxfu

maximum follow-up time, should not be greater than tfix

tchange

a strictly increasing sequence of time points starting from zero at which the drop-out rate changes. The first element of tchange must be zero.

ratec1

piecewise constant drop-out rate for the treatment. The rate and tchange must have the same length.

ratec0

piecewise constant drop-out rate for the control. The rate and tchange must have the same length.

eps

error tolerance for the numerical intergration

Details

$P(Y_i=y\mid Z_i=j)=\frac{\Gamma(y+1/k_j)}{\Gamma(y+1)\Gamma(1/k_j)}\Bigg(\frac{k_ju_i}{1+k_ju_i}\Bigg)^y\Bigg(\frac{1}{1+k_ju_i}\Bigg)^{1/k_j},$

where

$\log(u_i)=\log(t_i)+\beta_0+\beta_1 Z_i.$

Let $\hat{\beta}_0$ and $\hat{\beta}_1$ be the MLE of $\beta_0$ and $\beta_1$ . The varaince of $\hat{\beta}_1$ is

$\mbox{var}(\hat{\beta}_1)=1/\tilde{a}_0(r_0)+1/\tilde{a}_1(r_1)$

where

$\tilde{a}_j(r)=\sum_{i=1}^n I(Z_i=j)k_jrt_i/(1+k_jrt_i), \hspace{0.5cm}j=0,1,$

and $k_j, j=0,1$ are the dispersion parameters for control $j=0$ and treatment $j=1$ . Note that Zhu and Lakkis (2014) use

$a_j(r)=\sum_{i=1}^n I(Z_i=j)k_jrE(t_i)/\{1+k_jrE(t_i)\},$

Therefore, for each type of follow-up, there are 3 sample sizes calculated (because there are 3 varainces under the null) for with and without approximation of Zhu and Lakkis (2014).

Value

tildeXN

sample sizes based on current approach, i.e. not based on the Zhu and Lakkis's approximation

XN

sample sizes based on the Zhu and Lakkis's approximation

Exposure

mean exposure under different follow-up types with element 1 for control, element 2 for treatment and element 3 for overall.

SDExp

Sd of the exposure under different follow-up types with element 1 for control, element 2 for treatment and column 3 for overall.

Author(s)

Xiaodong Luo

References

Zhu~H and Lakkis~H. Sample size calculation for comparing two negative binomial rates. Statistics in Medicine 2014, 33: 376-387.

Examples

##calculating the sample sizes
abc=ynegbinomsize(r0=1.0,r1=0.5,shape0=1,pi1=0.5,alpha=0.05,twosided=1,
    beta=0.2,fixedfu=1,type=4,u=c(0.5,0.5,1),ut=c(0.5,1.0,1.5),
    tfix=1.5,maxfu=1,tchange=c(0,0.5,1),ratec1=c(0.15,0.15,0.15),
    eps=1.0e-03)
###Zhu and Lakkis's sample sizes (i.e. with approximation) 
abc$XN
###Our sample sizes (i.e. without approximation)
abc$tildeXN
##calculating the sample sizes
abc=ynegbinomsize(r0=1.0,r1=0.5,shape0=1,pi1=0.5,alpha=0.05,twosided=1,
    beta=0.2,fixedfu=1,type=4,u=c(0.5,0.5,1),ut=c(0.5,1.0,1.5),
    tfix=1.5,maxfu=1,tchange=c(0,0.5,1),ratec1=c(0.15,0.15,0.15),
    eps=1.0e-03)
###Zhu and Lakkis's sample sizes (i.e. with approximation) 
abc$XN
###Our sample sizes (i.e. without approximation)
abc$tildeXN

Package 'NBDesign'

Help Index

Design and Monitoring of Clinical Trials with Negative Binomial Endpoint

Description

Details

Author(s)

A utility functon to calculate the mean exposure under different scenarios

Description

Usage

Arguments

Details

Value

Author(s)

Examples

Two-sample sample size calculation for negative binomial distribution with variable follow-up

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Two-sample sample size calculation for negative binomial distribution with variable follow-up

Description

Usage

Arguments

Details

Value

Author(s)

Examples

Two-sample sample size calculation for negative binomial distribution with variable follow-up

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples