run5STAR: Run 5-STAR Algorithm

In rmarceauwest/fiveSTAR: Run 5-STAR Algorithm

Run 5-STAR Algorithm

Description

Runs 5-STAR algorithm for forming homogeneous risk strata and calculating an overall treatment effect estimate amalgamated from the formed strata

Usage

run5STAR(yy, arm, X, family = "cox", measure = ifelse(family == "cox",
  "HR", ifelse(family == "binomial", "RD", "MD")),
  alternative = ifelse(measure %in% c("HR", "RD"), "less", "greater"),
  cilevel = ifelse(alternative == "two.sided", 0.05, 0.025),
  vartype = "alt", missthreshold = c(0.1, 0.2), timeunit = NULL,
  tau = NULL, inclfrailty = FALSE, verbose = 0, plot = TRUE,
  filter.hyper = filter_control(), tree.hyper = if (family ==
  "gaussian") {     tree_control(minbucket = 30) } else tree_control(),
  distList = c("weibull", "lognormal", "loglogistic"), ucvar = 1,
  shading = FALSE, fplottype = "overall")

Arguments

yy	Trait/response (currently must be either continous, binary, or a Surv() object summarizing follow-up time for right-censored data and status indicator where 1=dead, 0=censored)
arm	Binary treatment indicator, 1 = test treatment, 0 = control
X	Data frame of all covariates (as specified in Step 1 of 5-STAR)
family	Trait family, current options: "cox", "binomial", and "gaussian" (note: binomial and gaussian are still experimental!)
measure	Response of interest; current options are: for survival traits: "HR" (hazard ratio, default when family = "cox") and "TR" (time ratio from model averaging of AFT models); for binary traits: "RD" (risk difference, default when family = "binomial"); for continuous traits: "MD" (mean difference, default when family = "gaussian")
alternative	For tests, whether alternative hypothesis is "less", "greater", or "two.sided". Currently ignored for family!="cox" (all others assume a 2-sided test for now)
cilevel	Confidence level alpha for overall result and confidence intervals (default = 0.025, for one-tailed tests)
vartype	Whether stratum-level variances used to calculate the correlation between sample size ni and ni/sqrt(Vi) test statistics should be calculated under the null ("null") or estimated via the Cox PH model ("alt"). "alt" is default, and must be used when measure != "HR"
timeunit	Optional parameter for plots defining scale of time to event data (e.g., "Months", "Years"); ignored for family!="cox" and plot == FALSE
tau	Optional numeric variable specifying end time point for rmst calculations; if NULL, will calculate the minimum of maximum times over arm within each formed stratum; ignored when measure != "RMST"
inclfrailty	A logical variable - whether or not to include a frailty term to each within-strata Cox PH model fit for added robustness against unexplained heterogeneity. Ignored when measure != "HR".
verbose	Numeric variable indicating amount of information to print to the terminal (0 = nothing, 1 = notes only, 2+ = notes and intermediate output)
plot	Logical, whether to return summary plots (filtering plots, within strata and pooled KM plots, and forest plots summarizing strata-level and overall results)
filter.hyper	A list of control parameters for filtering step (Step 2), (see filter_control)
tree.hyper	A list of control parameters for strata building step (Step 3) (see tree_control)
distList	Vector of models (survival distributions for parametric AFT fit) to include in model averaging; Each element must be the name of an element from survreg.distributions (see also survreg); default is c("weibull","lognormal","loglogistic"); ignored when family != "cox"
ucvar	Estimator for the unconditional variance of the model averaging estimate to use. 1 uses Buckland et al. (1997) analytical estimator, and 2 uses the more conservative estimator of Burnham and Anderson (2002) related to Bayesian model averaging. For more details see Turek 2013. Default is "1".
shading	For plotting, whether to add shaded confidence intervals around the pooled KM curves to better differentiate how similar the survival curves are. Default is FALSE. Ignored when plot = FALSE and/or family != "cox"
missthrehold	Optional parameter specifying proportion of missingness allowed for each covariate. See prep5STAR for more details.

Details

Filtering step is performed on complete case basis (e.g., removing all individuals with any missing covariate data)

Value

• inputcovs: vector containing names of all covariates input into the algorithm (after removing those with too much missingness, as defined by missthreshold, or can't be split on) (see prep5STAR for details)

• filteredcovs: vector containing names of all covariates left after filtering step (step 2)

• filterdetails: list containing additional output from filter step; for method=ENET, this includes:

  • cvout: containing fraction of null deviance explained, mean cross validation error, and optimal lambda and alpha value (see cv.glmnet and glmnet for more details)

  • beta: the coefficients of glmnet fit given tuned choice of alpha and lambda

  • ENETplot: plots of deviance and solution path over alpha/lambda parameters

  For method=RF or RFbest, this includes:

  • varselectmat: matrix of VIMP confidence intervals, p-values, and selection decision for each variable

  • VIMPplot: default variable importance CI plot, output if plot = TRUE

  • varselect2plot: variable selection information from subsample.rfsrc for making customizable VIMP CI plots

  • forest: rfsrc object

• prelimtree: ctree object; preliminary tree (3A) built by ctree, in terms of covariates

• prelimstratadefn: vector of rules defining the preliminary strata (step 3A), as defined by covariates chosen in initial ctree run, ordered from highest to lowest risk

• prelimstrataids: vector of preliminary (3A) strata membership for each subject (where 1 indicates highest risk, and the largest number indicates lowest risk, i.e., matching order of prelimstratadefn)

• prelimstratasurvfits: a survfit object, summarizing survival curves in each preliminary (3A) strata, pooled by treatment assignment; returned when family=="cox"

• prelimbystratasummary: matrix summarizing model fits within each preliminary (3A) strata, including estimated (log) hazard ratio (or TR, OR, RD, etc. when measure!="HR"), corresponding (1-cilevel)x100% CI, Gramsch and Therneau test of non-PH p-value, and sample size, inverse variance, and adaptive weights

• prelimsinglewtres: Preliminary results using only a single weighting scheme (e.g., just ni sample size weights or just ni/Vi weights)

• prelimres5star: Summary of amalgamated estimand, variance, p-value, and (1-cilevel)x100% confidence interval for adaptive weights from preliminary strata (3A)

• finaltree: ctree object; final, pruned tree (3B) built by ctree, in terms of preliminary strata

• stratadefn: vector of rules defining the final strata (step 3B), as defined by covariates translated from pooling ctree run, ordered from highest to lowest risk

• strataids: vector of final (3B) strata membership for each subject (where 1 indicates highest risk, and the largest number indicates lowest risk, i.e., matching order of stratadefn)

• stratasurvfits: a survfit object, summarizing survival curves in each final (3B) strata, pooled by treatment assignment; returned when family=="cox"

• bystratasummary: matrix summarizing model fits within each final (3B) strata, including estimated (log) hazard ratio (or OR, RD, etc. when measure!="HR"), corresponding (1-cilevel)x100% CI, Gramsch and Therneau test of non-PH p-value, and sample size, inverse variance, and adaptive weights

• singlewtres: Final results using only a single weighting scheme (e.g., just ni sample size weights or just ni/Vi weights)

• res5star: Summary of amalgamated estimand, variance, p-value, and cilevelx100

• prelimbetweenstrataKM: Kaplan-Meier survival curve plots from pooled treatment assignment data from each preliminary (3A) strata, returned if plot == TRUE and family == "cox"

• prelimbystrataKM: Kaplan-Meier survival curve plots within each preliminary (3A) strata, returned if plot == TRUE and family == "cox"

• prelimforestplot: a forest plot summarizing estimated coefficient and confidence interval for each preliminary (3A) strata, as well as amalgamated result, returned when plot == TRUE and family == "cox"

• betweenstrataKM: Kaplan-Meier survival curve plots from pooled treatment assignment data from each final (3B) strata, returned if plot == TRUE and family == "cox"

• bystrataKM: Kaplan-Meier survival curve plots within each final (3B) strata, returned if plot == TRUE and family == "cox"

• forestplot: a forest plot summarizing estimated coefficient and confidence interval for each final (3B) strata, as well as amalgamated result, returned if plot == TRUE and family == "cox"

See Also

filter_control

tree_control

rmarceauwest/fiveSTAR documentation built on June 30, 2023, 7:38 a.m.