stepp (version 3.2.6)

balance_patients: Utility function for determining the optimal values for generating the subpopulations.

Description

Utility function for determining the optimal values of the number of subpopulations and the corresponding r1 and r2 values for creating subpopulations with the sliding window approach. The optimal values are those that make the subpopulations more balanced by minimizing the variance of the subpopulation sizes.

Usage

balance_patients(range.r1, range.r2, maxnsubpops, covar, verbose = FALSE,
    plot = FALSE, contour = FALSE, nlevels = 5, showstatus = TRUE)

Value

The balance_patients() function returns a list with the following items:

r1_best

length-one numeric vector with overall best value of the r1 parameter

r2_best

length-one numeric vector with overall best value of the r2 parameter

var_best

length-one numeric vector with overall minimum value of the sizes variance

nsubpops_best

length-one numeric vector with overall best value for the number of subpopulations

all_res

numeric matrix with the details of all the calculations

Arguments

range.r1

numeric vector with two elements providing the range of values for the r1 parameter

range.r2

numeric vector with two elements providing the range of values for the r2 parameter

maxnsubpops

length-one numeric vector providing the maximum number of subpopulations to consider

covar

numeric vector containing the covariate values to use for generating the subpopulations

verbose

length-one logical vector; if TRUE prints a summary of the results in the console

plot

length-one logical vector; if TRUE produces a diagram showing the results of the calculations

contour

length-one logical vector; if TRUE adds to the plot the variance contour lines for each subpopulation number

nlevels

length-one numeric vector providing the number of contour lines to plot

showstatus

length-one logical vector; if TRUE displays a bar showing the progress of the calculations; default is TRUE

Author

Marco Bonetti, Sergio Venturini

References

Bonetti M, Gelber RD. Patterns of treatment effects in subsets of patients in clinical trials. Biostatistics 2004; 5(3):465-481.

Bonetti M, Zahrieh D, Cole BF, Gelber RD. A small sample study of the STEPP approach to assessing treatment-covariate interactions in survival data. Statistics in Medicine 2009; 28(8):1255-68.

Lazar AA, Cole BF, Bonetti M, Gelber RD. Evaluation of treatment-effect heterogeneity using biomarkers measured on a continuous scale: subpopulation treatment effect pattern plot. Journal of Clinical Oncology, 2010; 28(29): 4539-4544.

See Also

stwin, stsubpop, stepp.win, stepp.subpop, stepp.KM

Examples

if (FALSE) {
data(balance_example, package = "stepp")
ranger2 <- c(950, 1050)
ranger1 <- c(300, 500)
maxnsubpops <- 50

res_bal <- balance_patients(ranger1, ranger2, maxnsubpops, balance_example$covar,
  plot = TRUE, verbose = TRUE, contour = TRUE, nlevels = 6)
}