ECADE.sim {covadap}

Simulations of the Efficient Covariate-Adaptive Design

Description

Implements the Efficient Covariate-Adaptive DEsign by Baldi Antognini et al. (2022) for assigning patients to two treatments A and B by simulating the covariate profile of each patient using an existing dataset or specifying number and levels of the covariates. The procedure works with qualitative and quantitative covariates.

Usage

#With existing dataframe provided in data
ECADE.sim(data, covar = NULL, n = NULL, all.cat, nrep = 1000,
          rho = 0.85, alloc.function = "Efron", print.results = TRUE)
#With covariates
ECADE.sim(data = NULL, covar, n, all.cat, nrep = 1000, rho = 0.85,
          alloc.function = "Efron", print.results = TRUE)

Arguments

data

a data frame or a matrix. It can be a matrix only when all.cat = TRUE. Each row of data corresponds to the covariate profile of a patient. To be specified if covariate profiles should be sampled from an existing dataset provided in data.

covar

either a vector or a list to be specified only if data = NULL. If all.cat = TRUE is a vector with length equal to the number of covariates and elements equal to the number of levels for each covariate. Otherwise is a list containing cat, the list of the qualitative covariates with their level and quant, the list the quantitative covariates that are simulated from the normal distribution with the given mean and standard deviation.

n

number of patients (to be specified only if data = NULL)

all.cat

logical. If all the covariates in data are qualitative must be set equal to TRUE, otherwise must be set equal to FALSE.

nrep

number of trial replications.

rho

biasing probability, to be used only with the Efron allocation function (1/2 \leq \rho \leq 1). The default value is 0.85. Is NULL if other allocation functions are used.

alloc.function

a character specifying the allocation function used in the randomization procedure: ="Efron" for Efron's, if the assignment probability to A is e+(1-2e)[1-\Phi(x)] with e=0.1 alloc.function="norm1" while alloc.function="norm2" for e=0.2.

print.results

logical. If TRUE a summary of the results is printed.

Details

This function simulates nrep times a clinical study assigning patients to treatments A and B with the Efficient Covariate-Adaptive Design as described in Baldi Antognini et al. (see ECADE).

When covar is provided, the function finds all the possible combination of the levels of the covariates, i.e., the strata and, at each trial replication, the patients' covariate profiles are uniformly sampled within those strata. The specification of covar requires the specification of the number of patients n.

When data is provided, at each trial replication, the patients' covariate profiles are sampled from the observed strata with uniform distribution. In this case the number of patients equals the number of rows of data.

The summary printed when print.results = TRUE reports the averages, in absolute value, of the imbalance measures, strata imbalances and within-covariate imbalances of the nrep trial replications according to the nature of the covariates. See also ECADE.

Value

It returns an object of class "covadapsim", which is a list containing the following elements:

summary.info

Design name of the design.

Sample_size number of patients.

n_cov number of covariates.

var_names name of the covariates.

n_quantitative_variables number of quantitative covariates. Is NULL if all.cat = TRUE.

n_categorical_variables number of levels of each covariate. Is NULL if all.cat = TRUE or only quantitative covariates are present.

n_levels number of levels of each qualitative covariate. Is NULL if only quantitative covariates are present.

n.rep number of replications.

Imbalances

a list with the imbalance measures at the end of each simulated trial

Imb.measures summary of overall imbalances (Loss loss, Mahal Mahalanobis distance, overall.imb difference in the total number of patients assigned to A and B).

within.imb within-covariate imbalance: difference in the number of patients assigned to A and B for each level of each qualitative covariate (is NULL if only quantitative covariates are present).

strata.imb (only if all.cat = TRUE) the within-stratum imbalance (i.e. difference in the total number of patients assigned to A and B within the stratum).

strata.A (only if all.cat = TRUE) is the total number of patients assigned to A within the stratum.

strata.N (only if all.cat = TRUE) is the total number of patients assigned to each stratum.

diff_mean (only if all.cat = FALSE) the difference in mean in group A and B for each quantitative covariate.

obs.strata (only if all.cat = TRUE) matrix of the possible strata.

out

For each replication returns a list of the data provided in input (data) and the resulting assignments (Assignment).

References

Baldi Antognini A, Frieri R, Zagoraiou M, Novelli M. The Efficient Covariate-Adaptive Design for high-order balancing of quantitative and qualitative covariates. Statistical Papers, 2022.

See Also

See Also ECADE.

Examples

require(covadap)
# Here we set nrep = 50 for illustrative purposes,
# Set it equal to at least 5000 for more reliable Monte Carlo estimates.


### Implement with qualitative covariates (set all.cat = TRUE)
#### With an existing dataset
# Create a sample dataset with qualitative covariates
df1 <- data.frame("gender" = sample(c("female", "male"), 100, TRUE, c(1 / 3, 2 / 3)),
                  "age" = sample(c("18-35", "36-50", ">50"), 100, TRUE),
                  "bloodpressure" = sample(c("normal", "high", "hyper"), 100, TRUE),
                   stringsAsFactors = TRUE)
# To just view a summary of the metrics of the design
ECADE.sim(data = df1,  covar = NULL, n = NULL, all.cat = TRUE,
          alloc.function = "Efron", rho = 0.85, nrep = 50)
# To view a summary
# and create a list containing all the metrics of the design
res1 <- ECADE.sim(data = df1, covar = NULL, n = NULL, all.cat = TRUE,
                  alloc.function = "Efron", rho = 0.85, nrep = 50)

#### By specifying the covariates
# e.g. two binary covariates and one with three levels and 100 patients
res2 <- ECADE.sim(data = NULL, covar = c(2,3,3), n = 100, all.cat = TRUE,
                  alloc.function = "Efron",  rho = 0.85, nrep = 50)



### Implement with quantitative or mixed covariates
# Create a sample dataset with covariates of mixed nature
ff1 <- data.frame("gender" = sample(c("female", "male"), 100, TRUE, c(1 / 3, 2 / 3)),
                 "age" = sample(c("0-30", "30-50", ">50"), 100, TRUE),
                 "bloodpressure" = sample(c("normal", "high", "hypertension"), 10,
                  TRUE),
                 "smoke" = sample(c("yes", "no"), 100, TRUE, c(2 / 3, 1 / 3)),
                 "cholesterol" = round(rnorm(100, 200, 8),1),
                 "height" = rpois(100,160),
                  stringsAsFactors = TRUE)

### With quantitative covariates only (set all.cat = FALSE)
#### With an existing dataset
# select only column 5 and 6 of the sample dataset
# To just view a summary of the metrics of the design
ECADE.sim(data = ff1[,5:6], covar = NULL, n = NULL,  all.cat = FALSE,
          alloc.function = "Efron", rho = 0.85, nrep = 50)
# To view a summary and create a list containing all the metrics of the design
res3 <- ECADE.sim(data = ff1[,5:6],  covar = NULL, n = NULL, all.cat = FALSE,
                  alloc.function = "Efron", rho = 0.85, nrep = 50)
#### By specifying the covariates
# e.g. 2 quantitative covariates:
# BMI normally distributed with mean 26 and standard deviation 5
# cholesterol normally distributed with mean 200 and standard deviation 34
covar = list(quant = list(BMI = c(26, 5), cholesterol = c(200, 34)))
# To just view a summary of the metrics of the design
ECADE.sim(data = NULL, covar = covar, n = 100, all.cat = FALSE,
          alloc.function = "Efron", rho = 0.85, nrep = 50)
# To view a summary
# and create a list containing all the metrics of the design
res4 <- ECADE.sim(data = NULL, covar = covar, n = 100, all.cat = FALSE,
                  alloc.function = "Efron", rho = 0.85,  nrep = 50)



### With mixed covariates (set all.cat = FALSE)
#### With an existing dataset
# To just view a summary of the metrics of the design
ECADE.sim(data = ff1, covar = NULL, n = NULL,  all.cat = FALSE,
          alloc.function = "Efron",  rho = 0.85, nrep = 50)
# To view a summary
# and create a list containing all the metrics of the design
res5 <- ECADE.sim(data = ff1, covar = NULL, n = NULL,  all.cat = FALSE,
                  alloc.function = "Efron", rho = 0.85, nrep = 50)
#### By specifying the covariates
# e.g. one qualitative covariate and 2 quantitative covariates:
# gender with levels M and F
# BMI normally distributed with mean 26 and standard deviation 5
# cholesterol normally distributed with mean 200 and standard deviation 34
covar = list(cat = list(gender = c("M", "F")),
             quant = list(BMI = c(26, 5), cholesterol = c(200, 34)))
# To just view a summary of the metrics of the design
ECADE.sim(data = NULL, covar = covar, n = 100, all.cat = FALSE,
          alloc.function = "Efron", rho = 0.85, nrep = 50)
# To view a summary and
# create a list containing all the metrics of the design
res6 <- ECADE.sim(data = NULL, covar = covar, n = 100, all.cat = FALSE,
                  alloc.function = "Efron", rho = 0.85, nrep = 50)