carat-package: Covariate-Adaptive Randomization for Clinical Trials

Description

Provides functions and a command-line user interface to generate allocation sequences for clinical trials with covariate-adaptive randomization methods. It currently supports six different covariate-adaptive randomization procedures, including stratified randomization, minimization, and a general family of designs proposed by Hu and Hu (2012) <doi:10.1214/12-AOS983>. Three hypothesis testing methods, all valid and robust under covariate-adaptive randomization are also included in the package to facilitate the inference for treatment effects under the included randomization procedures. Additionally, the package provides comprehensive and efficient tools for the performance evaluation and comparison of randomization procedures and tests based on various criteria.

Acknowledgement

This work was supported by the Fundamental Research Funds for the Central Universities, and the Research Funds of Renmin University of China [grant number 20XNA023].

Author(s)

Fuyi Tu fuyi.tu@ruc.edu.cn;Xiaoqing Ye ye_xiaoq@163.com; Wei Ma mawei@ruc.edu.cn; Feifang Hu feifang@gwu.edu.

References

Atkinson A C. Optimum biased coin designs for sequential clinical trials with prognostic factors[J]. Biometrika, 1982, 69(1): 61-67. <doi:10.2307/2335853>

Baldi Antognini A, Zagoraiou M. The covariate-adaptive biased coin design for balancing clinical trials in the presence of prognostic factors[J]. Biometrika, 2011, 98(3): 519-535. <doi:10.1093/biomet/asr021>

Hu Y, Hu F. Asymptotic properties of covariate-adaptive randomization[J]. The Annals of Statistics, 2012, 40(3): 1794-1815. <doi:10.1214/12-AOS983>

Ma W, Hu F, Zhang L. Testing hypotheses of covariate-adaptive randomized clinical trials[J]. Journal of the American Statistical Association, 2015, 110(510): 669-680. <doi:10.1080/01621459.2014.922469>

Ma W, Qin Y, Li Y, et al. Statistical Inference for Covariate-Adaptive Randomization Procedures[J]. Journal of the American Statistical Association, 2020, 115(531): 1488-1597. <doi:10.1080/01621459.2019.1635483>

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47. <doi: 10.18637/jss.v107.i02>

Pocock S J, Simon R. Sequential treatment assignment with balancing for prognostic factors in the controlled clinical trial[J]. Biometrics, 1975: 103-115. <doi:10.2307/2529712>

Rosenberger W F, Lachin J M. Randomization in clinical trials: theory and practice[M]. John Wiley & Sons, 2015. <doi:10.1002/9781118742112>

Shao J., Yu, X. Validity of tests under covariate-adaptive biased coin randomization and generalized linear models[J]. Biometrics, 2013, 69(4), 960-969. <doi:10.1111/biom.12062>

Shao J., Yu X, Zhong B. A theory for testing hypotheses under covariate-adaptive randomization[J]. Biometrika, 2010, 97(2): 347-360. <doi:10.1093/biomet/asq014>

Zelen M. The randomization and stratification of patients to clinical trials[J]. Journal of chronic diseases, 1974, 27(7): 365-375. <doi:10.1016/0021-9681(74)90015-0>

Covariate-adjusted Biased Coin Design

Description

Allocates patients to one of two treatments based on covariate-adjusted biased coin design as proposed by Baldi Antognini A, Zagoraiou M (2011) <doi:10.1093/biomet/asr021>.

Usage

AdjBCD(data, a = 3)

Arguments

Details

Consider I covaraites and m_i levels for the ith covariate, i=1,\ldots,I. T_j is the assignment of the jth patient and Z_j = (k_1,\dots,k_I) indicates the covariate profile of the jth patient, j=1,\ldots,n. For convenience, (k_1,\dots,k_I) and (i;k_i) denote stratum and margin, respectively. D_j(.) is the difference between numbers of patients assigned to treatment 1 and treatment 2 at the corresponding level after j patients have been assigned.

Let F^a be a decreasing and symmetric function of D_j(.), which depends on a design parameter a\ge 0. Then, the probability of allocating the (j+1)th patient to treatment 1 is F^a(D_j(.)), where

F^a(x)=\frac{1}{x^a + 1},

for x\ge 1,

F^a(x)=1 / 2,

for x = 0, and

F^a(x)=\frac{|x|^a}{|x|^a + 1},

for x\le -1. As a goes to \infty, the design becomes more deteministic.

Details of the procedure can be found in Baldi Antognini and M. Zagoraiou (2011).

Value

It returns an object of class "carandom".

An object of class "carandom" is a list containing the following components:

References

Baldi Antognini A, Zagoraiou M. The covariate-adaptive biased coin design for balancing clinical trials in the presence of prognostic factors[J]. Biometrika, 2011, 98(3): 519-535.

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

See Also

See AdjBCD.sim for allocating patients with covariate data generating mechanism; See AdjBCD.ui for the command-line user interface.

Examples

# a simple use
## Real Data
## create a dataframe
df <- data.frame("gender" = sample(c("female", "male"), 1000, TRUE, c(1 / 3, 2 / 3)), 
                 "age" = sample(c("0-30", "30-50", ">50"), 1000, TRUE), 
                 "jobs" = sample(c("stu.", "teac.", "others"), 1000, TRUE), 
                 stringsAsFactors = TRUE)
Res <- AdjBCD(df, a = 2)
## view the output
Res

  ## view all patients' profile and assignments
  Res$Cov_Assig
  

## Simulated Data
n <- 1000
cov_num <- 3
level_num <- c(2, 3, 5) 
# Set pr to follow two tips:
#(1) length of pr should be sum(level_num);
#(2) sum of probabilities for each margin should be 1.
pr <- c(0.4, 0.6, 0.3, 0.4, 0.3, rep(0.2, times = 5))
# set the design parameter
a <- 1.8
# obtain result
Res.sim <- AdjBCD.sim(n, cov_num, level_num, pr, a)

  # view the assignments of patients
  Res.sim$Cov_Assig[cov_num + 1, ]
  # view the differences between treatment 1 and treatment 2 at all levels
  Res.sim$Diff
  

Covariate-adjusted Biased Coin Design with Covariate Data Generating Mechanism

Description

Allocates patients to one of two treatments based on the covariate-adjusted biased coin design as proposed by Baldi Antognini A, Zagoraiou M (2011) <doi:10.1093/biomet/asr021>, by simulating the covariates-profile under the assumption of independence between covariates and levels within each covariate.

Usage

AdjBCD.sim(n = 1000, cov_num = 2, level_num = c(2, 2), 
           pr = rep(0.5, 4), a = 3)

Arguments

Details

See AdjBCD.

Value

See AdjBCD.

References

Baldi Antognini A, Zagoraiou M. The covariate-adaptive biased coin design for balancing clinical trials in the presence of prognostic factors[J]. Biometrika, 2011, 98(3): 519-535.

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

See Also

See AdjBCD for allocating patients with complete covariate data; See AdjBCD.ui for the command-line user interface.

Command-line User Interface Using Covariate-adjusted Biased Coin Design

Description

A call to the user-interface function for allocation of patients to one of two treatments, using covariate-adjusted biased coin design, as proposed by Baldi Antognini A, Zagoraiou M (2011) <doi:10.1093/biomet/asr021>.

Usage

AdjBCD.ui(path, folder = "AdjBCD")

Arguments

Details

See AdjBCD.

Value

It returns an object of class "carseq".

The function print is used to obtain results. The generic accessor functions assignment, covariate, cov_num, cov_profile and others extract various useful features of the value returned by AdjBCD.ui.

Note

This function provides a command-line user interface, and users should follow the prompts to enter data including covariates as well as levels for each covariate, design parameter a and the covariate profile of the new patient.

References

Baldi Antognini A, Zagoraiou M. The covariate-adaptive biased coin design for balancing clinical trials in the presence of prognostic factors[J]. Biometrika, 2011, 98(3): 519-535.

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

See Also

See AdjBCD for allocating patients with complete covariate data; See AdjBCD.sim for allocating patients with covariate data generating mechanism.

Atkinson's D_A-optimal Biased Coin Design

Description

Allocates patients to one of two treatments based on the D_A-optimal biased coin design in the presence of the prognostic factors proposed by Atkinson A C (1982) <doi:10.2307/2335853>.

Usage

DoptBCD(data)

Arguments

Details

Consider an experiment involving n patients. Assuming a linear model between response and covariates, Atkinson's D_A-optimal biased coin design sequentially assigns patients to minimize the variance of estimated treatment effects. Supposing j patients have been assigned, the probability of assigning the (j+1)th patient to treatment 1 is

\frac{[1 - (1; \bold{x}^t_{j+1})(\bold{F}^t_j\bold{F}_j)^{-1}\bold{b}_j]^2}{[1-(1; \bold{x}^t_{j+1})(\bold{F}_j^t\bold{F}_j)^{-1}\bold{b}_j]^2+[1 + (1; \bold{x}_{j+1}^t)(\bold{F}_j^t\bold{F}_j)^{-1}\bold{b}_j]^2},

where \bold{X} = (\bold{x_i}, i = 1, \dots, j) and \bold{x}_i = (x_{i1}, \dots, x_{ij}) denote the covariate profile of the ith patient; and \bold{F}_j = [\bold{1}_j; \bold{X}] is the information matrix; and \bold{b}_j^T=(2\bold{T}_j-\bold{1}_j)^T\bold{F}_j, \bold{T}_j = (T_1, \dots, T_j) is a sequence containing the first j patients' allocations.

Details of the procedure can be found in A.C.Atkinson (1982).

Value

It returns an object of class "carandom".

An object of class "carandom" is a list containing the following components:

References

Atkinson A C. Optimum biased coin designs for sequential clinical trials with prognostic factors[J]. Biometrika, 1982, 69(1): 61-67.

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

See Also

See DoptBCD.sim for allocating patients with covariate data generating mechanism. See DoptBCD.ui for the command-line user interface.

Examples

# a simple use
## Real Data
df <- data.frame("gender" = sample(c("female", "male"), 100, TRUE, c(1 / 3, 2 / 3)), 
                 "age" = sample(c("0-30", "30-50", ">50"), 100, TRUE), 
                 "jobs" = sample(c("stu.", "teac.", "others"), 100, TRUE), 
                 stringsAsFactors = TRUE)
Res <- DoptBCD(df)
## view the output
Res

## view all patients' profile and assignments
## Res$Cov_Assig

## Simulated Data
n <- 1000
cov_num <- 2 

level_num <- c(2, 5)
# Set pr to follow two tips:
#(1) length of pr should be sum(level_num);
#(2)sum of probabilities for each margin should be 1.
pr <- c(0.4, 0.6, rep(0.2, times = 5))
Res.sim <- DoptBCD.sim(n, cov_num, level_num, pr)
## view the output
Res.sim

## view the difference between treatment 1 and treatment 2 
##             at overall, within-strt. and overall levels
Res.sim$Diff


N <- 5
n <- 100
cov_num <- 2
level_num <- c(3, 5) # << adjust to your CPU and the length should correspond to cov_num
## Set pr to follow two tips:
## (1) length of pr should be sum(level_num);
## (2)sum of probabilities for each margin should be 1
pr <- c(0.3, 0.4, 0.3, rep(0.2, times = 5))
omega <- c(0.2, 0.2, rep(0.6 / cov_num, times = cov_num))

## generate a container to contain Diff
DH <- matrix(NA, ncol = N, nrow = 1 + prod(level_num) + sum(level_num))
DA <- matrix(NA, ncol = N, nrow = 1 + prod(level_num) + sum(level_num))
for(i in 1 : N){
  result <- HuHuCAR.sim(n, cov_num, level_num, pr, omega)
  resultA <- StrBCD.sim(n, cov_num, level_num, pr)
  DH[ , i] <- result$Diff; DA[ , i] <- resultA$Diff
}
## do some analysis
require(dplyr)

## analyze the overall imbalance
Ana_O <- matrix(NA, nrow = 2, ncol = 3)
rownames(Ana_O) <- c("HuHuCAR", "DoptBCD")
colnames(Ana_O) <- c("mean", "median", "95%quantile")
temp <- DH[1, ] %>% abs
tempA <- DA[1, ] %>% abs
Ana_O[1, ] <- c((temp %>% mean), (temp %>% median),
                (temp %>% quantile(0.95)))
Ana_O[2, ] <- c((tempA %>% mean), (tempA %>% median),
                (tempA %>% quantile(0.95)))

## analyze the within-stratum imbalances
tempW <- DH[2 : (1 + prod(level_num)), ] %>% abs
tempWA <- DA[2 : 1 + prod(level_num), ] %>% abs
Ana_W <- matrix(NA, nrow = 2, ncol = 3)
rownames(Ana_W) <- c("HuHuCAR", "DoptBCD")
colnames(Ana_W) <- c("mean", "median", "95%quantile")
Ana_W[1, ] = c((tempW %>% apply(1, mean) %>% mean),
               (tempW %>% apply(1, median) %>% mean),
               (tempW %>% apply(1, mean) %>% quantile(0.95)))
Ana_W[2, ] = c((tempWA %>% apply(1, mean) %>% mean),
               (tempWA %>% apply(1, median) %>% mean),
               (tempWA %>% apply(1, mean) %>% quantile(0.95)))

## analyze the marginal imbalance
tempM <- DH[(1 + prod(level_num) + 1) :
              (1 + prod(level_num) + sum(level_num)), ] %>% abs
tempMA <- DA[(1 + prod(level_num) + 1) :
               (1 + prod(level_num) + sum(level_num)), ] %>% abs
Ana_M <- matrix(NA, nrow = 2, ncol = 3)
rownames(Ana_M) <- c("HuHuCAR", "DoptBCD")
colnames(Ana_M) <- c("mean", "median", "95%quantile")
Ana_M[1, ] = c((tempM %>% apply(1, mean) %>% mean),
               (tempM %>% apply(1, median) %>% mean),
               (tempM %>% apply(1, mean) %>% quantile(0.95)))
Ana_M[2, ] = c((tempMA %>% apply(1, mean) %>% mean),
               (tempMA %>% apply(1, median) %>% mean),
               (tempMA %>% apply(1, mean) %>% quantile(0.95)))

AnaHP <- list(Ana_O, Ana_M, Ana_W)
names(AnaHP) <- c("Overall", "Marginal", "Within-stratum")

AnaHP

Atkinson's D_A-optimal Biased Coin Design with Covariate Data Generating Mechanism

Description

Allocates patients generated by simulating covariates-profile under the assumption of independence between covariates and levels within each covariate, to one of two treatments based on the D_A-optimal biased coin design in the presence of prognostic factors, as proposed by Atkinson A C (1982) <doi:10.2307/2335853>.

Usage

DoptBCD.sim(n = 1000, cov_num = 2, level_num = c(2, 2), 
            pr = rep(0.5, 4))

Arguments

Details

See DoptBCD.

Value

See DoptBCD.

References

Atkinson A C. Optimum biased coin designs for sequential clinical trials with prognostic factors[J]. Biometrika, 1982, 69(1): 61-67.

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

See Also

See DoptBCD for allocating patients with complete covariate data; See DoptBCD.ui for the command-line user interface.

Command-line User Interface Using Atkinson's D_A-optimal Biased Coin Design

Description

A call to the user-interface function used to allocate patients to one of two treatments using Atkinson's D_A-optimal biased coin design proposed by Atkinson A C (1982) <doi:10.2307/2335853>.

Usage

DoptBCD.ui(path, folder = "DoptBCD")

Arguments

Details

See DoptBCD.

Value

It returns an object of class "carseq".

The function print is used to obtain results. The generic accessor functions assignment, covariate, cov_num, cov_profile and others extract various useful features of the value returned by that function.

Note

This function provides a command-line user interface and users should follow the prompts to enter data including covariates, as well as levels for each covariate and the covariate profile of the new patient.

References

Atkinson A C. Optimum biased coin designs for sequential clinical trials with prognostic factors[J]. Biometrika, 1982, 69(1): 61-67.

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

See Also

See DoptBCD for allocating patients with complete covariate data; See DoptBCD.sim for allocating patients with covariate data generating mechanism.

Hu and Hu's General Covariate-Adaptive Randomization

Description

Allocates patients to one of two treatments using Hu and Hu's general covariate-adaptive randomization proposed by Hu Y, Hu F (2012) <doi:10.1214/12-AOS983>.

Usage

HuHuCAR(data, omega = NULL, p = 0.85)

Arguments

Details

Consider I covariates and m_i levels for the ith covariate, i=1,\ldots,I. T_j is the assignment of the jth patient and Z_j = (k_1,\dots,k_I) indicates the covariate profile of this patient, j=1,\ldots,n. For convenience, (k_1,\dots,k_I) and (i;k_i) denote the stratum and margin, respectively. D_j(.) is the difference between the numbers of patients assigned to treatment 1 and treatment 2 at the corresponding levels after j patients have been assigned. The general covariate-adaptive randomization procedure is as follows:

(1) The first patient is assigned to treatment 1 with probability 1/2;

(2) Suppose that j-1 patients have been assigned (1<j\le n) and the jth patient falls within (k_1^*,\dots,k_I^*);

(3) If the jth patient were assigned to treatment 1, then the potential overall, within-covariate-margin, and within-stratum differences between the two treatments would be

D_j^{(1)}=D_{j-1}+1,

D_j^{(1)}(i;k_i^*)=D_{j-1}(i,k_i^*)+1,

D_j^{(1)}(k_1^*,\dots,k_I^*)=D_j(k_1^*,\dots,k_I^*)+1,

for margin (i;k_i^*) and stratum (k_1^*,\ldots,k_I^*). Similarly, the potential differences at the overall, within-covariate-margin, and within-stratum levels would be obtained if the jth patient were assigned to treatment 2;

(4) An imbalance measure is defined by

Imb_j^{(l)}=\omega_o[D_j^{(l)}]^2+\sum_{i=1}^{I}\omega_{m,i}[D_j^{(l)}(i;k_i^*)]^2+\omega_s[D_j^{(l)}(k_1^*,\dots,k_I^*)]^2,l=1,2;

(5) Conditional on the assignments of the first (j-1) patients as well as the covariate profiles of the first j patients, assign the jth patient to treatment 1 with probability

P(T_j=1|Z_j,T_1,\dots,T_{j-1})=q

for Imb_j^{(1)}>Imb_j^{(2)},

P(T_j=1|Z_j,T_1,\dots,T_{j-1})=p

for Imb_j^{(1)}<Imb_j^{(2)}, and

P(T_j=1|Z_j,T_1,\dots,T_{j-1})=0.5

for Imb_j^{(1)}=Imb_j^{(2)}.

Details of the procedure can be found in Hu and Hu (2012).

Value

It returns an object of class "carandom".

An object of class "carandom" is a list containing the following components:

References

Hu Y, Hu F. Asymptotic properties of covariate-adaptive randomization[J]. The Annals of Statistics, 2012, 40(3): 1794-1815.

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

See Also

See HuHuCAR.sim for allocating patients with covariate data generating mechanism. See HuHuCAR.ui for the command-line user interface.

Examples

# a simple use
## Real Data
## create a dataframe
df <- data.frame("gender" = sample(c("female", "male"), 1000, TRUE, c(1 / 3, 2 / 3)), 
                 "age" = sample(c("0-30", "30-50", ">50"), 1000, TRUE), 
                 "jobs" = sample(c("stu.", "teac.", "others"), 1000, TRUE), 
                 stringsAsFactors = TRUE)
omega <- c(1, 2, rep(1, 3))
Res <- HuHuCAR(data = df, omega)
## view the output
Res

## view all patients' profile and assignments
Res$Cov_Assig

## Simulated data
cov_num <- 3
level_num <- c(2, 3, 3)
pr <- c(0.4, 0.6, 0.3, 0.4, 0.3, 0.4, 0.3, 0.3)
omega <- rep(0.2, times = 5)
Res.sim <- HuHuCAR.sim(n = 100, cov_num, level_num, pr, omega)
## view the output
Res.sim

## view the detials of difference
Res.sim$Diff


N <- 100 # << adjust according to your CPU
n <- 1000
cov_num <- 3
level_num <- c(2, 3, 5) # << adjust to your CPU and the length should correspond to cov_num
# Set pr to follow two tips:
#(1) length of pr should be sum(level_num);
#(2)sum of probabilities for each margin should be 1.
pr <- c(0.4, 0.6, 0.3, 0.4, 0.3, rep(0.2, times = 5))
omega <- c(0.2, 0.2, rep(0.6 / cov_num, times = cov_num))
# Set omega0 = omegaS = 0
omegaP <- c(0, 0, rep(1 / cov_num, times = cov_num))

## generate a container to contain Diff
DH <- matrix(NA, ncol = N, nrow = 1 + prod(level_num) + sum(level_num))
DP <- matrix(NA, ncol = N, nrow = 1 + prod(level_num) + sum(level_num))
for(i in 1 : N){
  result <- HuHuCAR.sim(n, cov_num, level_num, pr, omega)
  resultP <- HuHuCAR.sim(n, cov_num, level_num, pr, omegaP)
  DH[ , i] <- result$Diff; DP[ , i] <- resultP$Diff
}

## do some analysis
require(dplyr)

## analyze the overall imbalance
Ana_O <- matrix(NA, nrow = 2, ncol = 3)
rownames(Ana_O) <- c("NEW", "PS")
colnames(Ana_O) <- c("mean", "median", "95%quantile")
temp <- DH[1, ] %>% abs
tempP <- DP[1, ] %>% abs
Ana_O[1, ] <- c((temp %>% mean), (temp %>% median),
                (temp %>% quantile(0.95)))
Ana_O[2, ] <- c((tempP %>% mean), (tempP %>% median),
                (tempP %>% quantile(0.95)))
## analyze the within-stratum imbalances
tempW <- DH[2 : (1 + prod(level_num)), ] %>% abs
tempWP <- DP[2 : 1 + prod(level_num), ] %>% abs
Ana_W <- matrix(NA, nrow = 2, ncol = 3)
rownames(Ana_W) <- c("NEW", "PS")
colnames(Ana_W) <- c("mean", "median", "95%quantile")
Ana_W[1, ] = c((tempW %>% apply(1, mean) %>% mean),
               (tempW %>% apply(1, median) %>% mean),
               (tempW %>% apply(1, mean) %>% quantile(0.95)))
Ana_W[2, ] = c((tempWP %>% apply(1, mean) %>% mean),
               (tempWP %>% apply(1, median) %>% mean),
               (tempWP %>% apply(1, mean) %>% quantile(0.95)))

## analyze the marginal imbalance
tempM <- DH[(1 + prod(level_num) + 1) : (1 + prod(level_num) + sum(level_num)), ] %>% abs
tempMP <- DP[(1 + prod(level_num) + 1) : (1 + prod(level_num) + sum(level_num)), ] %>% abs
Ana_M <- matrix(NA, nrow = 2, ncol = 3)
rownames(Ana_M) <- c("NEW", "PS"); colnames(Ana_M) <- c("mean", "median", "95%quantile")
Ana_M[1, ] = c((tempM %>% apply(1, mean) %>% mean),
               (tempM %>% apply(1, median) %>% mean),
               (tempM %>% apply(1, mean) %>% quantile(0.95)))
Ana_M[2, ] = c((tempMP %>% apply(1, mean) %>% mean),
               (tempMP %>% apply(1, median) %>% mean),
               (tempMP %>% apply(1, mean) %>% quantile(0.95)))

AnaHP <- list(Ana_O, Ana_M, Ana_W)
names(AnaHP) <- c("Overall", "Marginal", "Within-stratum")

AnaHP

Hu and Hu's General Covariate-Adaptive Randomization with Covariate Data Generating Mechanism

Description

Allocates patients to one of two treatments using general covariate-adaptive randomization proposed by Hu Y, Hu F (2012) <doi:10.1214/12-AOS983>, by simulating covariate profiles based on the assumption of independence between covariates and levels within each covariate.

Usage

HuHuCAR.sim(n = 1000, cov_num = 2, level_num = c(2, 2), 
            pr = rep(0.5, 4), omega = NULL, p = 0.85)

Arguments

Details

See HuHuCAR.

Value

See HuHuCAR.

References

Hu Y, Hu F. Asymptotic properties of covariate-adaptive randomization[J]. The Annals of Statistics, 2012, 40(3): 1794-1815.

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

See Also

See HuHuCAR for allocating patients with complete covariate data; See HuHuCAR.ui for the command-line user interface.

Command-line User Interface Using Hu and Hu's General Covariate-adaptive Randomization

Description

A call to the user-iterface function used to allocate patients to one of two treatments using Hu and Hu's general covariate-adaptive randomization method as proposed by Hu Y, Hu F (2012) <doi:10.1214/12-AOS983>.

Usage

HuHuCAR.ui(path, folder = "HuHuCAR")

Arguments

Details

See HuHuCAR

Value

It returns an object of class "carseq".

The function print is used to obtain results. The generic accessor functions assignment, covariate, cov_num, cov_profile and others extract various useful features of the value returned by HuHuCAR.ui.

Note

This function provides a command-line interface so that users should follow the prompts to enter data, including covariates as well as levels for each covariate, weights omega, biased probability p and the covariate profile of the new patient.

References

Hu Y, Hu F. Asymptotic properties of covariate-adaptive randomization[J]. The Annals of Statistics, 2012, 40(3): 1794-1815.

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

See Also

See HuHuCAR for allocating patients with complete covariate data; See HuHuCAR.sim for allocating patients with covariate data generating mechanism.

Pocock and Simon's Method in the Two-Arms Case

Description

Allocates patients to one of two treatments using Pocock and Simon's method proposed by Pocock S J, Simon R (1975) <doi:10.2307/2529712>.

Usage

PocSimMIN(data, weight = NULL, p = 0.85)

Arguments

Details

Consider I covariates and m_i levels for the ith covariate, i=1,\ldots,I. T_j is the assignment of the jth patient and Z_j = (k_1,\dots,k_I) indicates the covariate profile of this patient, j=1,\ldots,n. For convenience, (k_1,\dots,k_I) and (i;k_i) denote the stratum and margin, respectively. D_j(.) is the difference between the numbers of patients assigned to treatment 1 and treatment 2 at the corresponding levels after j patients have been assigned. The Pocock and Simon's minimization procedure is as follows:

(1) The first patient is assigned to treatment 1 with probability 1/2;

(2) Suppose that j-1 patients have been assigned (1<j\le n) and the jth patient falls within (k_1^*,\dots,k_I^*);

(3) If the jth patient were assigned to treatment 1, then the potential within-covariate-margin differences between the two treatments would be

D_j^{(1)}(i;k_i^*)=D_{j-1}(i,k_i^*)+1

for margin (i;k_i^*). Similarly, the potential differences would be obtained in the same way if the jth patient were assigned to treatment 2;

(4) An imbalance measure is defined by

Imb_j^{(l)}=\sum_{i=1}^{I}\omega_{m,i}[D_j^{(l)}(i;k_i^*)]^2,l=1,2;

(5) Conditional on the assignments of the first (j-1) patients as well as the covariate profiles of the first j patients, assign the jth patient to treatment 1 with the probability

P(T_j=1|Z_j,T_1,\dots,T_{j-1})=q

for Imb_j^{(1)}>Imb_j^{(2)},

P(T_j=1|Z_j,T_1,\dots,T_{j-1})=p

for Imb_j^{(1)}<Imb_j^{(2)}, and

P(T_j=1|Z_j,T_1,\dots,T_{j-1})=0.5

for Imb_j^{(1)}=Imb_j^{(2)}.

Details of the procedure can be found in Pocock S J, Simon R (1975).

Value

It returns an object of class "carandom".

An object of class "carandom" is a list containing the following components:

References

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

Pocock S J, Simon R. Sequential treatment assignment with balancing for prognostic factors in the controlled clinical trial[J]. Biometrics, 1975: 103-115.

See Also

See PocSimMIN.sim for allocating patients with covariate data generating mechanism. See PocSimMIN.ui for the command-line user interface.

Examples

# a simple use
## Real Data
## creat a dataframe
df <- data.frame("gender" = sample(c("female", "male"), 1000, TRUE, c(1 / 3, 2 / 3)), 
                 "age" = sample(c("0-30", "30-50", ">50"), 1000, TRUE), 
                 "jobs" = sample(c("stu.", "teac.", "others"), 1000, TRUE), 
                 stringsAsFactors = TRUE)
weight <- c(1, 2, 1)
Res <- PocSimMIN(data = df, weight)
## view the output
Res

## view all patients' profile and assignments
Res$Cov_Assig

## Simulated Data
cov_num = 3
level_num = c(2, 3, 3)
pr = c(0.4, 0.6, 0.3, 0.3, 0.4, 0.4, 0.3, 0.3)
Res.sim <- PocSimMIN.sim(n = 1000, cov_num, level_num, pr)
## view the output
Res.sim

## view the detials of difference
Res.sim$Diff


N <- 5
n <- 1000
cov_num <- 3
level_num <- c(2, 3, 5) 
# Set pr to follow two tips:
# (1) length of pr should be sum(level_num);
# (2)sum of probabilities for each margin should be 1.
pr <- c(0.4, 0.6, 0.3, 0.4, 0.3, rep(0.2, times = 5))
omega <- c(0.2, 0.2, rep(0.6 / cov_num, times = cov_num))
weight <- c(2, rep(1, times = cov_num - 1))

## generate a container to contain Diff
DH <- matrix(NA, ncol = N, nrow = 1 + prod(level_num) + sum(level_num))
DP <- matrix(NA, ncol = N, nrow = 1 + prod(level_num) + sum(level_num))
for(i in 1 : N){
  result <- HuHuCAR.sim(n, cov_num, level_num, pr, omega)
  resultP <- PocSimMIN.sim(n, cov_num, level_num, pr, weight)
  DH[ , i] <- result$Diff; DP[ , i] <- resultP$Diff
}

## do some analysis
require(dplyr)

## analyze the overall imbalance
Ana_O <- matrix(NA, nrow = 2, ncol = 3)
rownames(Ana_O) <- c("NEW", "PS")
colnames(Ana_O) <- c("mean", "median", "95%quantile")
temp <- DH[1, ] %>% abs
tempP <- DP[1, ] %>% abs
Ana_O[1, ] <- c((temp %>% mean), (temp %>% median),
                (temp %>% quantile(0.95)))
Ana_O[2, ] <- c((tempP %>% mean), (tempP %>% median),
                (tempP %>% quantile(0.95)))

## analyze the within-stratum imbalances
tempW <- DH[2 : (1 + prod(level_num)), ] %>% abs
tempWP <- DP[2 : 1 + prod(level_num), ] %>% abs
Ana_W <- matrix(NA, nrow = 2, ncol = 3)
rownames(Ana_W) <- c("NEW", "PS")
colnames(Ana_W) <- c("mean", "median", "95%quantile")
Ana_W[1, ] = c((tempW %>% apply(1, mean) %>% mean),
               (tempW %>% apply(1, median) %>% mean),
               (tempW %>% apply(1, mean) %>% quantile(0.95)))
Ana_W[2, ] = c((tempWP %>% apply(1, mean) %>% mean),
               (tempWP %>% apply(1, median) %>% mean),
               (tempWP %>% apply(1, mean) %>% quantile(0.95)))

## analyze the marginal imbalance
tempM <- DH[(1 + prod(level_num) + 1) :
              (1 + prod(level_num) + sum(level_num)), ] %>% abs
tempMP <- DP[(1 + prod(level_num) + 1) :
               (1 + prod(level_num) + sum(level_num)), ] %>% abs
Ana_M <- matrix(NA, nrow = 2, ncol = 3)
rownames(Ana_M) <- c("NEW", "PS")
colnames(Ana_M) <- c("mean", "median", "95%quantile")
Ana_M[1, ] = c((tempM %>% apply(1, mean) %>% mean),
               (tempM %>% apply(1, median) %>% mean),
               (tempM %>% apply(1, mean) %>% quantile(0.95)))
Ana_M[2, ] = c((tempMP %>% apply(1, mean) %>% mean),
               (tempMP %>% apply(1, median) %>% mean),
               (tempMP %>% apply(1, mean) %>% quantile(0.95)))

AnaHP <- list(Ana_O, Ana_M, Ana_W)
names(AnaHP) <- c("Overall", "Marginal", "Within-stratum")

AnaHP

Pocock and Simon's Method in the Two-Arms Case with Covariate Data Generating Mechanism

Description

Allocates patients to one of two treatments using Pocock and Simon's method proposed by Pocock S J, Simon R (1975) <doi:10.2307/2529712>, by simulating covariate profiles under the assumption of independence between covariates and levels within each covariate.

Usage

PocSimMIN.sim(n = 1000, cov_num = 2, level_num = c(2, 2), 
              pr = rep(0.5, 4), weight = NULL, p = 0.85)

Arguments

Details

See PocSimMIN.

Value

See PocSimMIN.

References

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

Pocock S J, Simon R. Sequential treatment assignment with balancing for prognostic factors in the controlled clinical trial[J]. Biometrics, 1975: 103-115.

See Also

See PocSimMIN for allocating patients with complete covariate data; See PocSimMIN.ui for the command-line user interface.

Command-line User Interface Using Pocock and Simon's Procedure with Two-Arms Case

Description

A call to the user-iterface function used to allocate patients to one of two treatments using Pocock and Simon's method proposed by Pocock S J, Simon R (1975) <doi:10.2307/2529712>.

Usage

PocSimMIN.ui(path, folder = "PocSimMIN")

Arguments

Details

See PocSimMIN.

Value

It returns an object of class "carseq".

The function print is used to obtain results. The generic accessor functions assignment, covariate, cov_num, cov_profile and others extract various useful features of the value returned by PocSimMIN.ui.

Note

This function provides a command-line interface and users should follow the prompts to enter data including covariates as well as levels for each covariate, weight, biased probability p and the covariate profile of the new patient.

References

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

Pocock S J, Simon R. Sequential treatment assignment with balancing for prognostic factors in the controlled clinical trial[J]. Biometrics, 1975: 103-115.

See Also

See PocSimMIN for allocating a given completely collected data; See PocSimMIN.sim for allocating patients with covariate data generating mechanism.

Shao's Method in the Two-Arms Case

Description

Allocates patients to one of the two treatments using Shao's method proposed by Shao J, Yu X, Zhong B (2010) <doi:10.1093/biomet/asq014>.

Usage

StrBCD(data, p = 0.85)

Arguments

Details

Consider I covariates and m_i levels for the ith covariate, i=1,\ldots,I. T_j is the assignment of the jth patient and Z_j = (k_1,\dots,k_I) indicates the covariate profile of this patient, j=1,\ldots,n. For convenience, (k_1,\dots,k_I) and (i;k_i) denote the stratum and margin, respectively. D_j(.) is the difference between the numbers of patients assigned to treatment 1 and treatment 2 at the corresponding levels after j patients have been assigned. The stratified biased coin design is as follows:

(1) The first patient is assigned to treatment 1 with probability 1/2;

(2) Suppose j-1 patients have been assigned (1<j\le n) and the jth patient falls within (k_1^*,\dots,k_I^*);

(3) If the jth patient were assigned to treatment 1, then the potential within-stratum difference between the two treatments would be

D_j^{(1)}(k_1^*,\dots,k_I^*)=D_j(k_1^*,\dots,k_I^*)+1

for stratum (k_1^*,\ldots,k_I^*). Similarly, the potential difference would be obtained in the same way if the jth patient were assigned to treatment 2;

(4) An imbalance measure is defined by

Imb_j^{(l)}=[D_j^{(l)}(k_1^*,\dots,k_I^*)]^2,l=1,2;

(5) Conditional on the assignments of the first (j-1) patients as well as the covariates'profiles of the first j patients, assign the jth patient to treatment 1 with probability

P(T_j=1|Z_j,T_1,\dots,T_{j-1})=q

for Imb_j^{(1)}>Imb_j^{(2)},

P(T_j=1|Z_j,T_1,\dots,T_{j-1})=p

for Imb_j^{(1)}<Imb_j^{(2)}, and

P(T_j=1|Z_j,T_1,\dots,T_{j-1})=0.5

for Imb_j^{(1)}=Imb_j^{(2)}.

Details of the procedure can be found in Shao J, Yu X, Zhong B (2010).

Value

It returns an object of class "carandom".

An object of class "carandom" is a list containing the following components:

References

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

Shao J, Yu X, Zhong B. A theory for testing hypotheses under covariate-adaptive randomization[J]. Biometrika, 2010, 97(2): 347-360.

See Also

See StrBCD.sim for allocating patients with covariate data generating mechanism. See StrBCD.ui for command-line user interface.

Examples

# a simple use
## Real Data
## creat a dataframe
df <- data.frame("gender" = sample(c("female", "male"), 1000, TRUE, c(1 / 3, 2 / 3)), 
                 "age" = sample(c("0-30", "30-50", ">50"), 1000, TRUE), 
                 "jobs" = sample(c("stu.", "teac.", "others"), 1000, TRUE), 
                 stringsAsFactors = TRUE)
Res <- StrBCD(data = df)
## view the output
Res

## view all patients' profile and assignments
Res$Cov_Assig

## Simulated Data
cov_num = 3
level_num = c(2, 3, 3)
pr = c(0.4, 0.6, 0.3, 0.4, 0.3, 0.4, 0.3, 0.3)
Res.sim <- StrBCD.sim(n = 1000, cov_num, level_num, pr)
## view the output
Res.sim

## view the detials of difference
Res.sim$Diff


N <- 5
n <- 1000
cov_num <- 3
level_num <- c(2, 3, 5) 
# Set pr to follow two tips:
# (1) length of pr should be sum(level_num);
# (2)sum of probabilities for each margin should be 1
pr <- c(0.4, 0.6, 0.3, 0.4, 0.3, rep(0.2, times = 5))
omega <- c(0.2, 0.2, rep(0.6 / cov_num, times = cov_num))

## generate a container to contain Diff
DH <- matrix(NA, ncol = N, nrow = 1 + prod(level_num) + sum(level_num))
DS <- matrix(NA, ncol = N, nrow = 1 + prod(level_num) + sum(level_num))
for(i in 1 : N){
  result <- HuHuCAR.sim(n, cov_num, level_num, pr, omega)
  resultS <- StrBCD.sim(n, cov_num, level_num, pr)
  DH[ , i] <- result$Diff; DS[ , i] <- resultS$Diff
}

## do some analysis
require(dplyr)

## analyze the overall imbalance
Ana_O <- matrix(NA, nrow = 2, ncol = 3)
rownames(Ana_O) <- c("NEW", "Shao")
colnames(Ana_O) <- c("mean", "median", "95%quantile")
temp <- DH[1, ] %>% abs
tempS <- DS[1, ] %>% abs
Ana_O[1, ] <- c((temp %>% mean), (temp %>% median),
                (temp %>% quantile(0.95)))
Ana_O[2, ] <- c((tempS %>% mean), (tempS %>% median),
                (tempS %>% quantile(0.95)))

## analyze the within-stratum imbalances
tempW <- DH[2 : (1 + prod(level_num)), ] %>% abs
tempWS <- DS[2 : 1 + prod(level_num), ] %>% abs
Ana_W <- matrix(NA, nrow = 2, ncol = 3)
rownames(Ana_W) <- c("NEW", "Shao")
colnames(Ana_W) <- c("mean", "median", "95%quantile")
Ana_W[1, ] = c((tempW %>% apply(1, mean) %>% mean),
               (tempW %>% apply(1, median) %>% mean),
               (tempW %>% apply(1, mean) %>% quantile(0.95)))
Ana_W[2, ] = c((tempWS %>% apply(1, mean) %>% mean),
               (tempWS %>% apply(1, median) %>% mean),
               (tempWS %>% apply(1, mean) %>% quantile(0.95)))

## analyze the marginal imbalance
tempM <- DH[(1 + prod(level_num) + 1) :
              (1 + prod(level_num) + sum(level_num)), ] %>% abs
tempMS <- DS[(1 + prod(level_num) + 1) :
               (1 + prod(level_num) + sum(level_num)), ] %>% abs
Ana_M <- matrix(NA, nrow = 2, ncol = 3)
rownames(Ana_M) <- c("NEW", "Shao")
colnames(Ana_M) <- c("mean", "median", "95%quantile")
Ana_M[1, ] = c((tempM %>% apply(1, mean) %>% mean),
               (tempM %>% apply(1, median) %>% mean),
               (tempM %>% apply(1, mean) %>% quantile(0.95)))
Ana_M[2, ] = c((tempMS %>% apply(1, mean) %>% mean),
               (tempMS %>% apply(1, median) %>% mean),
               (tempMS %>% apply(1, mean) %>% quantile(0.95)))

AnaHP <- list(Ana_O, Ana_M, Ana_W)
names(AnaHP) <- c("Overall", "Marginal", "Within-stratum")

AnaHP

Shao's Method in the Two-Arms Case with Covariate Data Generating Mechanism

Description

Allocates patients to one of two treatments using Shao's method proposed by Shao J, Yu X, Zhong B (2010) <doi:10.1093/biomet/asq014>, by simulating covariate profiles under the assumption of independence between covariates and levels within each covariate.

Usage

StrBCD.sim(n = 1000, cov_num = 2, level_num = c(2, 2), 
           pr = rep(0.5, 4), p = 0.85)

Arguments

Details

See StrBCD.

Value

See StrBCD.

References

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

Shao J, Yu X, Zhong B. A theory for testing hypotheses under covariate-adaptive randomization[J]. Biometrika, 2010, 97(2): 347-360.

See Also

See StrBCD for allocating patients with complete covariate data; See StrBCD.ui for the command-line user interface.

Command-line User Interface Using Shao's Method

Description

A call to the user-interface function used to allocate patients to one of two treatments using Shao's method proposed by Shao J, Yu X, Zhong B (2010) <doi:10.1093/biomet/asq014>.

Usage

StrBCD.ui(path, folder = "StrBCD")

Arguments

Details

See StrBCD.

Value

It returns an object of class "carseq".

The function print is used to obtain results. The generic accessor functions assignment, covariate, cov_num, cov_profile and others extract various useful features of the value returned by StrBCD.ui.

Note

This function provides a command-line interface and users should follow the prompts to enter data including covariates as well as levels for each covariate, biased probability p and the covariate profile of the new patient.

References

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

Shao J, Yu X, Zhong B. A theory for testing hypotheses under covariate-adaptive randomization[J]. Biometrika, 2010, 97(2): 347-360.

See Also

See StrBCD for allocating patients with complete covariate data; See StrBCD.sim for allocating patients with covariate data generating mechanism.

Stratified Permuted Block Randomization

Description

Allocates patients to one of two treatments using stratified permuted block randomization proposed by Zelen M (1974) <doi:10.1016/0021-9681(74)90015-0>.

Usage

StrPBR(data, bsize = 4)

Arguments

Details

Different covariate profiles are defined to be strata, and then permuted block randomization is applied to each stratum. It works efficiently when the number of strata is small. However, when the number of strata increases, the stratified permuted block randomization fails to obtain balance between two treatments.

Permuted block randomization, or blocking, is used to balance treatments within a block so that there are the same number of subjects in each treatment. A block contains the same number of each treatment and blocks of different sizes are combined to make up the randomization list.

Details of the procedure can be found in Zelen M (1974).

Value

It returns an object of class "carandom".

An object of class "carandom" is a list containing the following components:

References

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

Zelen M. The randomization and stratification of patients to clinical trials[J]. Journal of chronic diseases, 1974, 27(7): 365-375.

See Also

See StrPBR.sim for allocating patients with covariate data generating mechanism. See StrPBR.ui for the command-line user interface.

Examples

# a simple use
## Real Data
## creat a dataframe
df <- data.frame("gender" = sample(c("female", "male"), 100, TRUE, c(1 / 3, 2 / 3)), 
                 "age" = sample(c("0-30", "30-50", ">50"), 100, TRUE), 
                 "jobs" = sample(c("stu.", "teac.", "others"), 100, TRUE), 
                 stringsAsFactors = TRUE)
Res <- StrPBR(data = df, bsize = 4)
## view the output
Res

## view all patients' profile and assignments
Res$Cov_Assig

## Simulated data
cov_num <- 3
level_num <- c(2, 3, 3)
pr <- c(0.4, 0.6, 0.3, 0.4, 0.3, 0.4, 0.3, 0.3)
Res.sim <- StrPBR.sim(n = 100, cov_num, level_num, pr)
## view the output
Res.sim

## view the detials of difference
Res.sim$Diff


N <- 5
n <- 1000
cov_num <- 3
level_num <- c(2, 3, 5) 
# Set pr to follow two tips:
#(1) length of pr should be sum(level_num);
#(2)sum of probabilities for each margin should be 1.
pr <- c(0.4, 0.6, 0.3, 0.4, 0.3, rep(0.2, times = 5))
omega <- c(0.2, 0.2, rep(0.6 / cov_num, times = cov_num))
# Set block size for stratified randomization
bsize <- 4

## generate a container to contain Diff
DS <- matrix(NA, ncol = N, nrow = 1 + prod(level_num) + sum(level_num))
for(i in 1 : N){
  rtS <- StrPBR.sim(n, cov_num, level_num, pr, bsize)
  DS[ , i] <- rtS$Diff
}

## do some analysis
require(dplyr)

## analyze the overall imbalance
Ana_O <- matrix(NA, nrow = 1, ncol = 3)
rownames(Ana_O) <- c("Str.R")
colnames(Ana_O) <- c("mean", "median", "95%quantile")
tempS <- DS[1, ] %>% abs
Ana_O[1, ] <- c((tempS %>% mean), (tempS %>% median),
                (tempS %>% quantile(0.95)))
## analyze the within-stratum imbalances
tempWS <- DS[2 : 1 + prod(level_num), ] %>% abs
Ana_W <- matrix(NA, nrow = 1, ncol = 3)
rownames(Ana_W) <- c("Str.R")
colnames(Ana_W) <- c("mean", "median", "95%quantile")
Ana_W[1, ] = c((tempWS %>% apply(1, mean) %>% mean),
               (tempWS %>% apply(1, median) %>% mean),
               (tempWS %>% apply(1, mean) %>% quantile(0.95)))

## analyze the marginal imbalance
tempMS <- DS[(1 + prod(level_num) + 1) : (1 + prod(level_num) + sum(level_num)), ] %>% abs
Ana_M <- matrix(NA, nrow = 1, ncol = 3)
rownames(Ana_M) <- c("Str.R");
colnames(Ana_M) <- c("mean", "median", "95%quantile")
Ana_M[1, ] = c((tempMS %>% apply(1, mean) %>% mean),
               (tempMS %>% apply(1, median) %>% mean),
               (tempMS %>% apply(1, mean) %>% quantile(0.95)))

AnaHP <- list(Ana_O, Ana_M, Ana_W)
names(AnaHP) <- c("Overall", "Marginal", "Within-stratum")

AnaHP

Stratified Permuted Block Randomization with Covariate Data Generating Mechanism

Description

Allocates patients to one of two treatments using stratified randomization proposed by Zelen M (1974) <doi:10.1016/0021-9681(74)90015-0>, by simulating covariates-profile on assumption of independence between covariates and levels within each covariate.

Usage

StrPBR.sim(n = 1000, cov_num = 2, level_num = c(2, 2), 
           pr = rep(0.5, 4), bsize = 4)

Arguments

Details

See StrPBR.

Value

See StrPBR.

References

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

Zelen M. The randomization and stratification of patients to clinical trials[J]. Journal of chronic diseases, 1974, 27(7): 365-375.

See Also

See StrPBR for allocating patients with complete covariate data; See StrPBR.ui for the command-line user interface.

Command-line User Interface Using Stratified Permuted Block Randomization with Two-Arms Case

Description

A call to the user-iterface function used to allocate patients to one of two treatments using stratified permuted block randomization proposed by Zelen M (1974) <doi: 10.1016/0021-9681(74)90015-0>.

Usage

StrPBR.ui(path, folder = "StrPBR")

Arguments

Details

See StrPBR.

Value

It returns an object of class "carseq".

The function print is used to obtain results. The generic accessor functions assignment, covariate, cov_num, cov_profile and others extract various useful features of the value returned by StrPBR.ui.

Note

This function provides a command-line interface and users should follow the prompts to enter data including covariates as well as levels for each covariate, block size bsize and the covariate profile of the new patient.

References

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

Zelen M. The randomization and stratification of patients to clinical trials[J]. Journal of chronic diseases, 1974, 27(7): 365-375.

See Also

See StrPBR for allocating patients with complete covariate data; See StrPBR.sim for allocating patients with covariate data generating mechanism.

Bootstrap t-test

Description

Performs bootstrap t-test on treatment effects. This test is proposed by Shao et al. (2010) <doi:10.1093/biomet/asq014>.

Usage

  boot.test(data, B = 200, method = c("HuHuCAR", "PocSimMIN", "StrBCD", 
                                  "StrPBR", "DoptBCD", "AdjBCD"), 
          conf = 0.95, ...)

Arguments

Details

The bootstrap t-test is described as follows:

1) Generate bootstrap data (Y_1^*,Z_1^*), \dots, (Y_n^*,Z_n^*) as a simple random sample with replacement from the original data (Y_1,Z_1), \dots,(Y_n,Z_n), where Y_i denotes the outcome and Z_i denotes the profile of the ith patient.

2) Perform covariate-adaptive procedures on the patients' profiles to obtain new treatment assignments T_1^*,\dots,T_n^*, and define

\hat{\theta}^* = -\frac{1}{n_1^*}\sum\limits_{i=1}^n (T_i^*-2) \times Y_i^* - \frac{1}{n_0^*}\sum\limits_{i=1}^n (T_i^*-1) \times Y_i

where n_1^* is the number of patients assigned to treatment 1 and n_0^* is the number of patients assigned to treatment 2.

3) Repeat step 2 B times to generate B independent boostrap samples to obtain \hat{\theta}^*_b, b = 1,\dots,B. The variance of \bar{Y}_1 - \bar{Y}_0 can then be approximated by the sample variance of \hat{\theta}^*_b.

Value

It returns an object of class "htest".

An object of class "htest" is a list containing the following components:

References

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

Shao J, Yu X, Zhong B. A theory for testing hypotheses under covariate-adaptive randomization[J]. Biometrika, 2010, 97(2): 347-360.

Examples

#Suppose the data used is patients' profile from real world, 
#  while it is generated here. Data needs to be preprocessed 
#  and then get assignments following certain randomization.
set.seed(100)
df<- data.frame("gender" = sample(c("female", "male"), 100, TRUE, c(1 / 3, 2 / 3)),
                "age" = sample(c("0-30", "30-50", ">50"), 100, TRUE),
                "jobs" = sample(c("stu.", "teac.", "other"), 100, TRUE, c(0.4, 0.2, 0.4)), 
                stringsAsFactors = TRUE)
##data preprocessing
data.pd <- StrPBR(data = df, bsize = 4)$Cov_Assig

#Then we need to combine patients' profiles and outcomes after randomization and treatments.
outcome = runif(100)
data.combined = data.frame(rbind(data.pd,outcome), stringsAsFactors = TRUE)

#run the bootstrap t-test
B = 200
Strbt = boot.test(data.combined, B, "StrPBR", bsize = 4)
Strbt

Comparison of Powers for Different Tests under Different Randomization methods

Description

Compares the power of tests under different randomization methods and treatment effects through matrices and plots.

Usage

  compPower(powers, diffs, testname)

Arguments

Value

This function returns a list. The first element is a matrix consisting of powers of chosen tests under different values of treatment effects. The second element of the list is a plot of powers. diffs forms the vertical axis of the plot.

Examples

##settings
set.seed(100)
n = 1000
cov_num = 5
level_num = c(2,2,2,2,2)
pr = rep(0.5,10)
beta = c(1,4,3,2,5,5,4,3,2,1)
di = seq(0,0.5,0.1)
sigma = 1
type = "linear"
p=0.85
Iternum = 10 #<<for demonstration,it is suggested to be around 1000
sl = 0.05
weight = rep(0.1,5)

#comparison of corrected t-test under StrBCD and PocSim
##data generation
library("ggplot2")
Strctp=evalPower(n,cov_num,level_num,pr,type,beta,di,
                sigma,Iternum,sl,"StrBCD","corr.test",FALSE,p)
PSctp=evalPower(n,cov_num,level_num,pr,type,beta,di,sigma,
                Iternum,sl,"PocSimMIN","corr.test",FALSE,weight,p)
powers = list(Strctp,PSctp)
testname = c("StrBCD.corr","PocSimMIN.corr")

#get plot and matrix for comparison
cp = compPower(powers,di,testname)
cp

Compare Different Randomization Procedures via Tables and Plots

Description

Compares randomization procedures based on several different quantities of imbalances. Among all included randomization procedures of class "careval", two or more procedures can be compared in this function.

Usage

compRand(...)

Arguments

Details

The primary goal of using covariate-adaptive randomization in practice is to achieve balance with respect to the key covariates. We choose four rules to measure the absolute imbalances at overall, within-covariate-margin, and within-stratum levels, which are maximal, 95%quantile, median and mean of the absolute imbalances at different aspects. The Monte Carlo method is used to calculate the four types of imbalances. Let D_{n,i}(\cdot) be the final difference at the corresponding level for ith iteration, i=1,\ldots, N, and N is the number of iterations.

(1) Maximal

\max_{i = 1, \dots, N}|D_{n,i}(\cdot)|.

(2) 95% quantile

|D_{n,\lceil0.95N\rceil}(\cdot)|.

(3) Median

|D_{n,(N+1)/2}(\cdot)|

for N is odd, and

\frac{1}{2}(|D_{(N/2)}(\cdot)|+|D_{(N/2+1)}(\cdot)|)

for N is even.

(4) Mean

\frac{1}{N}\sum_{i = 1}^{N}|D_{n, i}(\cdot)|.

Value

It returns an object of class "carcomp".

An object of class "carcomp" is a list containing the following components:

References

Atkinson A C. Optimum biased coin designs for sequential clinical trials with prognostic factors[J]. Biometrika, 1982, 69(1): 61-67.

Baldi Antognini A, Zagoraiou M. The covariate-adaptive biased coin design for balancing clinical trials in the presence of prognostic factors[J]. Biometrika, 2011, 98(3): 519-535.

Hu Y, Hu F. Asymptotic properties of covariate-adaptive randomization[J]. The Annals of Statistics, 2012, 40(3): 1794-1815.

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

Pocock S J, Simon R. Sequential treatment assignment with balancing for prognostic factors in the controlled clinical trial[J]. Biometrics, 1975: 103-115.

Shao J, Yu X, Zhong B. A theory for testing hypotheses under covariate-adaptive randomization[J]. Biometrika, 2010, 97(2): 347-360.

Zelen M. The randomization and stratification of patients to clinical trials[J]. Journal of chronic diseases, 1974, 27(7): 365-375.

See Also

See evalRand or evalRand.sim to evaluate a specific randomization procedure.

Examples

## Compare stratified permuted block randomization and Hu and Hu's general CAR
cov_num <- 2
level_num <- c(2, 2)
pr <- rep(0.5, 4)
n <- 500
N <- 20 # <<adjust according to CPU
bsize <- 4
# set weight for Hu and Hu's method, it satisfies
# (1)Length should equal to cov_num
omega <- c(1, 2, 1, 1)
# Assess Hu and Hu's general CAR
Obj1 <- evalRand.sim(n = n, N = N, Replace = FALSE, cov_num = cov_num, 
                     level_num = level_num, pr = pr, method = "HuHuCAR", 
                     omega, p = 0.85)
# Assess stratified permuted block randomization
Obj2 <- evalRand.sim(n = n, N = N, Replace = FALSE, cov_num = cov_num, 
                     level_num = level_num, pr = pr, method = "StrPBR", 
                     bsize)

RES <- compRand(Obj1, Obj2)

Corrected t-test

Description

Performs corrected t-test on treatment effects. This test follows the idea of Ma et al. (2015) <doi:10.1080/01621459.2014.922469>.

Usage

  corr.test(data, conf = 0.95)

Arguments

Details

When the working model is the true underlying linear model, and the chosen covariate-adaptive design achieves that the overall imbalance and marginal imbalances for all covariates are bounded in probability, we can derive the asymptotic distribution under the null distribution, where the treatment effect of each group is the same. Subsequently, we can replace the variance estimator in a simple two sample t-test with an adjusted variance estimator. Details can be found in Ma et al.(2015).

Value

It returns an object of class "htest".

An object of class "htest" is a list containing the following components:

References

Ma W, Hu F, Zhang L. Testing hypotheses of covariate-adaptive randomized clinical trials[J]. Journal of the American Statistical Association, 2015, 110(510): 669-680.

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

Examples

##generate data
set.seed(100)
n = 1000
cov_num = 5
level_num = c(2,2,2,2,2)
pr = rep(0.5,10)
beta = c(0.1,0.4,0.3,0.2,0.5,0.5,0.4,0.3,0.2,0.1)
omega = c(0.1, 0.1, rep(0.8 / 5, times = 5))
mu1 = 0
mu2 = 0.7
sigma = 1
type = "linear"
p = 0.85

dataH = getData(n,cov_num,level_num,pr,type,beta,
                mu1,mu2,sigma,"HuHuCAR",omega,p)

#run the corrected t-test
HHct=corr.test(dataH)
HHct

Evaluation of Tests and Randomization Procedures through Power

Description

Returns powers and a plot of the chosen test and method under different treatment effects.

Usage

  evalPower(n, cov_num, level_num, pr, type, beta, di = seq(0,0.5,0.1), sigma = 1,
          Iternum, sl = 0.05, method = c("HuHuCAR", "PocSimMIN", "StrBCD", "StrPBR", 
                                         "DoptBCD","AdjBCD"), 
          test = c("boot.test", "corr.test", "rand.test"), plot = TRUE, ...)

Arguments

Value

This function returns a list. The first element is a dataframe representing the powers of the chosen test under different values of treatment effects. The second element is the execution time. An optional element is the plot of power in which di forms the vertical axis.

Examples

##settings
set.seed(2019)
n = 100#<<for demonstration,it is suggested to be larger than 1000
cov_num = 5
level_num = c(2,2,2,2,2)
pr = rep(0.5,10)
beta = c(0.1,0.4,0.3,0.2,0.5,0.5,0.4,0.3,0.2,0.1)
omega = c(0.1, 0.1, rep(0.8 / 5, times = 5))
di = seq(0,0.5,0.1)
sigma = 1
type = "linear"
p = 0.85
Iternum = 10#<<for demonstration,it is suggested to be around 1000
sl = 0.05
Reps = 10#<<for demonstration,it is suggested to be 200

#Evaluation of Power
library("ggplot2")
Strtp=evalPower(n,cov_num,level_num,pr,type,beta,di,sigma,
                Iternum,sl,"HuHuCAR","rand.test",TRUE,omega,p,Reps, nthreads = 1)
Strtp

Evaluation of Randomization Procedures

Description

Evaluates a specific randomization procedure based on several different quantities of imbalances.

Usage

evalRand(data, method = "HuHuCAR", N = 500, ...)

Arguments

Details

The data is designed for N times using method.

Value

It returns an object of class "careval".

An object of class "careval" is a list containing the following components:

References

Atkinson A C. Optimum biased coin designs for sequential clinical trials with prognostic factors[J]. Biometrika, 1982, 69(1): 61-67.

Baldi Antognini A, Zagoraiou M. The covariate-adaptive biased coin design for balancing clinical trials in the presence of prognostic factors[J]. Biometrika, 2011, 98(3): 519-535.

Hu Y, Hu F. Asymptotic properties of covariate-adaptive randomization[J]. The Annals of Statistics, 2012, 40(3): 1794-1815.

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

Pocock S J, Simon R. Sequential treatment assignment with balancing for prognostic factors in the controlled clinical trial[J]. Biometrics, 1975: 103-115.

Shao J, Yu X, Zhong B. A theory for testing hypotheses under covariate-adaptive randomization[J]. Biometrika, 2010, 97(2): 347-360.

Zelen M. The randomization and stratification of patients to clinical trials[J]. Journal of chronic diseases, 1974, 27(7): 365-375.

See Also

See evalRand.sim to evaluate a randomization procedure with covariate data generating mechanism.

Examples

# a simple use
## Access by real data
## create a dataframe
df <- data.frame("gender" = sample(c("female", "male"), 1000, TRUE, c(1 / 3, 2 / 3)), 
                 "age" = sample(c("0-30", "30-50", ">50"), 1000, TRUE), 
                 "jobs" = sample(c("stu.", "teac.", "others"), 1000, TRUE), 
                 stringsAsFactors = TRUE)
Res <- evalRand(data = df, method = "HuHuCAR", N = 500, 
                omega = c(1, 2, rep(1, ncol(df))), p = 0.85)
## view the output
Res

  ## view all patients' assignments
  Res$Assig

## Assess by simulated data
cov_num <- 3
level_num <- c(2, 3, 5)
pr <- c(0.35, 0.65, 0.25, 0.35, 0.4, 0.25, 0.15, 0.2, 0.15, 0.25)
n <- 1000
N <- 50
omega = c(1, 2, 1, 1, 2)
# assess Hu and Hu's procedure with the same group of patients
Res.sim <- evalRand.sim(n = n, N = N, Replace = FALSE, cov_num = cov_num, 
                        level_num = level_num, pr = pr, method = "HuHuCAR", 
                        omega, p = 0.85)
 
  ## Compare four procedures
  cov_num <- 3
  level_num <- c(2, 10, 2)
  pr <- c(rep(0.5, times = 2), rep(0.1, times = 10), rep(0.5, times = 2))
  n <- 100
  N <- 200 # <<adjust according to CPU
  bsize <- 4
  ## set weights for HuHuCAR
  omega <- c(1, 2, rep(1, cov_num)); 
  ## set weights for PocSimMIN
  weight = rep(1, cov_num); 
  ## set biased probability
  p = 0.80
  # assess Hu and Hu's procedure
  RH <- evalRand.sim(n = n, N = N, Replace = FALSE, cov_num = cov_num, 
                     level_num = level_num, pr = pr, method = "HuHuCAR", 
                     omega = omega, p = p)
  # assess Pocock and Simon's method
  RPS <- evalRand.sim(n = n, N = N, Replace = FALSE, cov_num = cov_num, 
                      level_num = level_num, pr = pr, method = "PocSimMIN", 
                      weight, p = p)
  # assess Shao's procedure
  RS <- evalRand.sim(n = n, N = N, Replace = FALSE, cov_num = cov_num, 
                     level_num = level_num, pr = pr, method = "StrBCD", 
                     p = p)
  # assess stratified randomization
  RSR <- evalRand.sim(n = n, N = N, Replace = FALSE, cov_num = cov_num, 
                      level_num = level_num, pr = pr, method = "StrPBR", 
                      bsize)
  
  # create containers
  C_M = C_O = C_WS = matrix(NA, nrow = 4, ncol = 4)
  colnames(C_M) = colnames(C_O) = colnames(C_WS) = 
    c("max", "95%quan", "med", "mean")
  rownames(C_M) = rownames(C_O) = rownames(C_WS) = 
    c("HH", "PocSim", "Shao", "StraRand")
  
  # assess the overall imbalance
  C_O[1, ] = RH$Imb[1, ]
  C_O[2, ] = RPS$Imb[1, ]
  C_O[3, ] = RS$Imb[1, ]
  C_O[4, ] = RSR$Imb[1, ]
  # view the result
  C_O
  
  # assess the marginal imbalances
  C_M[1, ] = apply(RH$Imb[(1 + RH$strt_num) : (1 + RH$strt_num + sum(level_num)), ], 2, mean)
  C_M[2, ] = apply(RPS$Imb[(1 + RPS$strt_num) : (1 + RPS$strt_num + sum(level_num)), ], 2, mean)
  C_M[3, ] = apply(RS$Imb[(1 + RS$strt_num) : (1 + RS$strt_num + sum(level_num)), ], 2, mean)
  C_M[4, ] = apply(RSR$Imb[(1 + RSR$strt_num) : (1 + RSR$strt_num + sum(level_num)), ], 2, mean)
  # view the result
  C_M
  
  # assess the within-stratum imbalances
  C_WS[1, ] = apply(RH$Imb[2 : (1 + RH$strt_num), ], 2, mean)
  C_WS[2, ] = apply(RPS$Imb[2 : (1 + RPS$strt_num), ], 2, mean)
  C_WS[3, ] = apply(RS$Imb[2 : (1 + RS$strt_num), ], 2, mean)
  C_WS[4, ] = apply(RSR$Imb[2 : (1 + RSR$strt_num), ], 2, mean)
  # view the result
  C_WS
  
  # Compare the four procedures through plots
  meth = rep(c("Hu", "PS", "Shao", "STR"), times = 3)
  shape <- rep(1 : 4, times = 3)
  crt <- rep(1 : 3, each = 4)
  crt_c <- rep(c("O", "M", "WS"), each = 4)
  mean <- c(C_O[, 4], C_M[, 4], C_WS[, 4])
  df_1 <- data.frame(meth, shape, crt, crt_c, mean, 
                     stringsAsFactors = TRUE)
  
  require(ggplot2)
  p1 <- ggplot(df_1, aes(x = meth, y = mean, color = crt_c, group = crt,
                         linetype = crt_c, shape = crt_c)) +
    geom_line(size = 1) +
    geom_point(size = 2) +
    xlab("method") +
    ylab("absolute mean") +
    theme(plot.title = element_text(hjust = 0.5))
  p1

Evaluation Randomization Procedures with Covariate Data Generating Mechanism

Description

Evaluates randomization procedure based on several different quantities of imbalances by simulating patients' covariate profiles under the assumption of independence between covariates and levels within each covariate.

Usage

evalRand.sim(n = 1000, N = 500, Replace = FALSE, cov_num = 2, 
             level_num = c(2, 2), pr = rep(0.5, 4), method = "HuHuCAR", ...)

Arguments

Details

See evalRand.

Value

See evalRand.

See Also

See evalRand to evaluate a randomization procedure with complete covariate data.

Data Generation

Description

Generates continuous or binary outcomes given patients' covariates, the underlying model and the randomization procedure.

Usage

  getData(n, cov_num, level_num, pr, type, beta, 
          mu1, mu2, sigma = 1, method = "HuHuCAR", ...)

Arguments

Details

To generate continuous outcomes, we use the linear model:

y_i = \mu_j+x_i^T\beta+\epsilon_i,

to generate binary outcomes, we use the logit link function:

P(y_i=1) = \frac{exp\{\mu_j+x_i^T\beta \}}{1+exp \{\mu_j+x_i^T\beta }

,

where j indicates patient i belongs to treatment j.

Value

getData returns a size cov_num+2 \times n dataframe. The first cov_num rows represent patients' profile. The next row consists of patients' assignments and the final row consists of generated outcomes.

Examples

#Parameters' Setting
set.seed(100)
n = 1000
cov_num = 5
level_num = c(2,2,2,2,2)
beta = c(1,4,3,2,5,5,4,3,2,1)
mu1 = 0
mu2 = 0
sigma = 1
type = "linear"
p = 0.85
omega = c(0.1, 0.1, rep(0.8 / 5, times = 5))
pr = rep(0.5,10)

#Data Generation
dataH = getData(n, cov_num,level_num, pr, type, beta,
                mu1, mu2, sigma, "HuHuCAR", omega, p)
dataH[1:(cov_num+2),1:5]

Data of Covariate Profile of Patients

Description

Gives the simulated covariate profile of patients for clincal trials.

Usage

data(pats)

Arguments

Randomization Test

Description

Performs randomization test on treatment effects.

Usage

  rand.test(data, Reps = 200, method = c("HuHuCAR", "PocSimMIN", "StrBCD", 
                                       "StrPBR", "DoptBCD", "AdjBCD"), 
          conf = 0.95, binwidth = 30, ...)

Arguments

Details

The randomization test is described as follows: 1) For the observed responses Y_1,\dots,Y_n and the treatment assignments T_1,T_2,\dots,T_n, compute the observed test statistic

S_{obs} = \frac{-\sum_{i=1}^nY_i*(T_i-2)}{n_1}-\frac{\sum_{i=1}^n Y_i*(T_i-1)}{n_0}

where n_1 is the number of patients assigned to treatment 1 and n_0 is the number of patients assigned to treatment 2;

2) Perform the covariate-adaptive randomization procedure to obtain the new treatment assignments and calculate the corresponding test statistic S_i. And repeat this process L times;

3) Calculate the two-sided Monte Carlo p-value estimator

p = \frac{\sum_{l=1}^L I(|S_l|\ge |S_{obs}|)}{L}

Value

It returns an object of class "htest".

An object of class "htest" is a list containing the following components:

References

Ma W, Ye X, Tu F, Hu F. carat: Covariate-Adaptive Randomization for Clinical Trials[J]. Journal of Statistical Software, 2023, 107(2): 1-47.

Rosenberger W F, Lachin J M. Randomization in clinical trials: theory and practice[M]. John Wiley & Sons, 2015.

Examples

##generate data
set.seed(100)
n = 1000
cov_num = 5
level_num = c(2,2,2,2,2)
pr = rep(0.5,10)
beta = c(0.1,0.4,0.3,0.2,0.5,0.5,0.4,0.3,0.2,0.1)
mu1 = 0
mu2 = 0.01
sigma = 1
type = "linear"
p = 0.85

dataS = getData(n, cov_num, level_num, pr, type,
               beta, mu1, mu2, sigma, "StrBCD", p)

#run the randomization test
library("ggplot2")
Strt = rand.test(data = dataS, Reps = 200,method = "StrBCD", 
                conf = 0.95, binwidth = 30,
                p = 0.85)
Strt