balance_patients: Utility function for determining the optimal values for...
In stepp: Subpopulation Treatment Effect Pattern Plot (STEPP)

balance_patients

R Documentation

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)

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

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

Author(s)

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.

Examples

## Not run: 
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)

## End(Not run)

stepp documentation built on June 22, 2024, 9:24 a.m.