| Title: | Evaluate Treatment Selection Biomarkers |
|---|---|
| Description: | A suite of descriptive and inferential methods designed to evaluate one or more biomarkers for their ability to guide patient treatment recommendations. Package includes functions to assess the calibration of risk models; and plot, evaluate, and compare markers. Please see the reference Janes H, Brown MD, Huang Y, et al. (2014) <doi:10.1515/ijb-2012-0052> for further details. |
| Authors: | Marshall Brown and Holly Janes |
| Maintainer: | Marshall Brown <[email protected]> |
| License: | GPL-3 |
| Version: | 2.1.1 |
| Built: | 2025-02-02 03:09:55 UTC |
| Source: | https://github.com/mdbrown/treatmentselection |
A suite of descriptive and inferential methods designed to evaluate one or more biomarkers for their ability to guide patient treatment recommendations.
| Package: | TreatmentSelection |
| Type: | Package |
| Version: | 2.0.- |
| Date: | 2016-07-28 |
| License: | GPL-2 |
Marshall Brown and Holly Janes
Maintainer: Marshall Brown <[email protected]>
Janes H, Brown MD, Huang Y, et al. An approach to evaluating and comparing biomarkers for patient treatment selection. **Int J Biostat.** 2014;10(1):99-121.
trtsel_measures for evaluating the performance of a user-specified marker-based treatment rule,
trtsel for creating trtsel objects,
plot.trtsel for plotting risk curves and more,
evaluate.trtsel for evaluating marker performance,
calibrate.trtsel for assessing model calibration, and
compare.trtsel to compare two trtsel object.
# See individual function man pages for examples. ?trtsel_measures ?trtsel ?plot.trtsel ?evaluate.trtsel ?compare.trtsel ?calibrate.trtsel# See individual function man pages for examples. ?trtsel_measures ?trtsel ?plot.trtsel ?evaluate.trtsel ?compare.trtsel ?calibrate.trtsel
method for calibrating trtsel objects
calibrate(x, ...)calibrate(x, ...)
x |
object |
... |
not used |
Assess calibration of fitted models for risk and treatment effect given marker. Plots are used to compare observed vs. fitted risks and treatment effects and Hosmer-Lemeshow goodness-of-fit tests are reported. An object of class "trtsel" must first be created using the function "trtsel" by supplying a data.frame containing marker, treatment, and event status information.
## S3 method for class 'trtsel' calibrate(x, ..., groups = 10, plot.type = "calibration", trt.names = c("Treatment", "No Treatment"), line.color = "black", point.color = "grey10", ci = 0.95, main = NULL, ylim = NULL, xlim = NULL, ylab = NULL, xlab = NULL)## S3 method for class 'trtsel' calibrate(x, ..., groups = 10, plot.type = "calibration", trt.names = c("Treatment", "No Treatment"), line.color = "black", point.color = "grey10", ci = 0.95, main = NULL, ylim = NULL, xlim = NULL, ylab = NULL, xlab = NULL)
x |
An object of class "trtsel", created by using the function "trtsel." |
... |
ignored. |
groups |
Number of groups; observations are split into groups based on quantiles of predicted risk or treatment effect, depending on plot.type. For plot.type = "treatment effect", observations are split into groups based on quantile of predicted treatment effect; for plot.type= "calibration", "risk.t0", or "risk.t1", and for the Hosmer-Lemshow test statistic, observations on each treatment are split into groups based on quantile of predicted risk. The default value is 10. |
plot.type |
Which type of plot to produce. Options are "calibration" (default), which plots average predicted vs. observed risks on a log scale; "risk.t1" and "risk.t0" which overlays observed risks on fitted risk curves for T = 1 and T = 0 subjects, respectively; and "treatment effect" which overlays observed treatment effects on the fitted treatment effect curve. |
trt.names |
A vector of length 2 indicating the names for the two treatment options, T= 1 and T = 0, respectively, for the plot legend. This option is only used when plot.type="calibration". The default value is c("Treatment", "No Treatment"). |
line.color |
color for lines in calibration plots. |
point.color |
color for points in calibration plots. |
ci |
numeric value (default 0.95) specifying the level for confidence intervals. |
main |
The main title for the plot. Only applies if plot.type is specified. |
ylim |
The limits for the y-axis of the plot, in the form c(lower,upper). Only applies if plot.type is specified. |
xlim |
The limits for the x-axisof the plot, in the form c(lower,upper). Only applies if plot.type is specified. |
ylab |
A label for the y-axis. Default values depend on plot.type. Only applies if plot.type is specified. |
xlab |
A label for the x-axis. Default values depend on plot.type. Only applies if plot.type is specified. |
A list with the following components:
HL.TestStat |
Hosmer-Lemeshow test statistic for assessing fit of the risk models for the T = 0 and T = 1 groups. |
p.value |
P-values for the Hosmer-Lemeshow tests in each treatment group. |
Df |
Degrees of freedom for the chi-square distribution used to generate a p-value for the Hosmer-Lemeshow chi-square test. This equals "groups" - 2. |
plot |
If plot output was created, the ggplot plotting object. |
trtsel for creating trtsel objects,
plot.trtsel for plotting risk curves and more,
evaluate.trtsel for evaluating marker performance, and
compare.trtsel to compare two trtsel object.
data(tsdata) ########################### ## Create trtsel objects ########################### trtsel.Y1 <- trtsel(event ~ Y1*trt, treatment.name = "trt", data = tsdata, study.design = "RCT", default.trt = "trt all") trtsel.Y1 ############################## ## Assess model calibration ############################## cali.Y1 <- calibrate(trtsel.Y1, plot.type = "calibration") cali.Y1 # A "treatment effect" plot calibrate(trtsel.Y1, line.color = "coral", plot.type = "treatment effect")data(tsdata) ########################### ## Create trtsel objects ########################### trtsel.Y1 <- trtsel(event ~ Y1*trt, treatment.name = "trt", data = tsdata, study.design = "RCT", default.trt = "trt all") trtsel.Y1 ############################## ## Assess model calibration ############################## cali.Y1 <- calibrate(trtsel.Y1, plot.type = "calibration") cali.Y1 # A "treatment effect" plot calibrate(trtsel.Y1, line.color = "coral", plot.type = "treatment effect")
method to compare trtsel objects
compare(x, ...)compare(x, ...)
x |
object |
... |
not used |
Evaluates and compares the performance of two treatment selection markers measured in the same data. (Bias-corrected) summary measures for the performance of each marker are estimated and confidence intervals are provided. Differences in measures of performance between markers are estimated along with confidence intervals, and the results of tests comparing marker performance measures are returned. "Treatment effect curves" for each marker are overlaid on the same plot. An object of class 'trtsel' must first be created for each marker using the function 'trtsel' by supplying a data.frame containing marker, treatment, and event status information; treatment and event data must be identical for the two markers.
## S3 method for class 'trtsel' compare(x, ..., x2, bootstraps = 500, bias.correct = TRUE, alpha = 0.05, plot = TRUE, ci = "horizontal", fixed.values = NULL, offset = 0.01, conf.bands = TRUE, conf.bandsN = 100, model.names = c("Model 1", "Model 2"), xlab = NULL, ylab = NULL, xlim = NULL, ylim = NULL, main = NULL, annotate.plot = TRUE)## S3 method for class 'trtsel' compare(x, ..., x2, bootstraps = 500, bias.correct = TRUE, alpha = 0.05, plot = TRUE, ci = "horizontal", fixed.values = NULL, offset = 0.01, conf.bands = TRUE, conf.bandsN = 100, model.names = c("Model 1", "Model 2"), xlab = NULL, ylab = NULL, xlim = NULL, ylim = NULL, main = NULL, annotate.plot = TRUE)
x |
An object of class "trtsel" created by using function "trtsel". This is created using data for the first marker. Note: event and treatment vectors provided to create this trtsel object must be identical to those used to create the x2 object. |
... |
ignored. |
x2 |
An object of class "trtsel" created by using function "trtsel". This is created using data for the second marker. |
bootstraps |
Number of bootstrap replicates for creating confidence intervals and bands. Default value is 500. Set bootstraps=0 if no confidence intervals or bands are desired. |
bias.correct |
logical indicator of whether to bias-correct measures for over-optimism using bootstrap-bias correction. When the same data is used to fit and evaluate the model, performance measures are over-optimistic. Setting this equal to TRUE uses a bootstrap method to bias-correct performance measures. |
alpha |
(1-alpha)*100% confidence intervals are calculated. Default value is alpha = 0.05 which yields 95% CI's. |
plot |
Indication of whether a plot showing treatment effect curves for the two markers should be created. TRUE (default) or FALSE. |
ci |
If plot = TRUE, indication of whether horizontal or vertical confidence intervals be plotted. Character string of either "horizontal" (default) or "vertical." Only applies if plot = TRUE. |
fixed.values |
A numeric vector indicating fixed values on the x- or y-axes at which bootstrap confidence intervals are provided. If "fixed.values" are provided, point-wise confidence intervals will be printed (i.e. conf.bands will be taken as FALSE). This option applies to the plot only. |
offset |
If confidence intervals are to be plotted for specified fixed.values, offset is the amount of distance to offset confidence intervals so that they do not overlap on the plot. The default value is 0.01. Only applies if plot = TRUE. |
conf.bands |
Indication of whether pointwise confidence intervals are shown for the curve(s). TRUE (default) or FALSE. If "fixed.values" are input, this option is ignored and no confidence bands are produced. Only applies if plot = TRUE. |
conf.bandsN |
If conf.bands = TRUE, the number of points along the x- or y-axis at which to calculate the pointwise confidence intervals. The default is 100. Only applies if plot = TRUE. |
model.names |
A vector of length 2 indicating the names for the two markers in x, and x2, respectively, for the plot legend. The default value is c("Model 1", "Model 2"). |
xlab |
A label for the x-axis. Default values depend on plot.type. Only applies if plot = TRUE. |
ylab |
A label for the y-axis. Default values depend on plot.type. Only applies if plot = TRUE. |
xlim |
The limits for the x-axisof the plot, in the form c(x1,x2). Only applies if plot = TRUE. |
ylim |
The limits for the y-axis of the plot, in the form c(y1,y2). Only applies if plot = TRUE. |
main |
The main title for the plot. Only applies if plot = TRUE. |
annotate.plot |
Only applies to comparison of two discrete markers. Should the plot be annotated with the marker group percentages? default is TRUE. |
A list with components (see Janes et al. (2013) for a description of the summary measures and estimators):
estimates.marker1 |
Point estimates of the summary measures: p.neg, p.pos, B.neg, B.pos, Theta, Var.Delta, TG and event rates for marker 1. |
estimates.marker2 |
Point estimates for the same summary measures for marker 2. |
estimates.diff |
Estimated difference in summary measures (marker 1 - marker 2). |
ci.marker1 |
2x9 data.frame with confidence intervals for marker 1 performance measures. |
ci.marker2 |
2x9 data.frame with confidence intervals for marker 2 performance measures. |
ci.diff |
2x9 data.frame with confidence intervals for differences in performance measures. |
p.values |
1x9 data.frame with p-values for each difference corresponding to a test of H0: marker 1 performance = marker 2 performance. |
bootstraps |
bootstraps value provided. |
In addition, if plot = TRUE:
plot |
ggplot object containing the generated plot. |
plot.ci.marker1 |
A data.frame containing the bounds of the bootstrap-based confidence intervals for marker1, along with the fixed.values they are centered around, where applicable. |
plot.ci.marker2 |
a data.frame containing the bounds of the bootstrap-based confidence intervals for marker 2, along with the fixed.values they are centered around, where applicable. |
Plot output is only produced when comparing a continuous (discrete) marker to a continuous (discrete) marker because confidence bands are calculated differently for continuous vs. discrete markers. See the note under ?plot.trtsel, for a description of the differences between how the bootstrap confidence bands are calculated.
Janes, Holly; Brown, Marshall D; Pepe, Margaret; Huang, Ying; "An Approach to Evaluating and Comparing Biomarkers for Patient Treatment Selection" The International Journal of Biostatistics. Volume 0, Issue 0, ISSN (Online) 1557-4679, ISSN (Print) 2194-573X, DOI: 10.1515/ijb-2012-0052, April 2014
trtsel for creating trtsel objects,
plot.trtsel for plotting risk curves and more,
evaluate.trtsel for evaluating marker performance, and
calibrate.trtsel for assessing model calibration..
data(tsdata) ########################### ## Create trtsel objects ########################### trtsel.Y1 <- trtsel(event ~ Y1*trt, treatment.name = "trt", data = tsdata, study.design = "RCT", default.trt = "trt all") trtsel.Y1 trtsel.Y2 <- trtsel(event ~ Y2*trt, treatment.name = "trt", data = tsdata, default.trt = "trt all") trtsel.Y2 ############################### ## Compare marker performance ############################### # Plot treatment effect curves with pointwise confidence intervals ## use more bootstraps in practice compare(x = trtsel.Y1, x2 = trtsel.Y2, bootstraps = 10, plot = TRUE, ci = "horizontal", conf.bands = TRUE)data(tsdata) ########################### ## Create trtsel objects ########################### trtsel.Y1 <- trtsel(event ~ Y1*trt, treatment.name = "trt", data = tsdata, study.design = "RCT", default.trt = "trt all") trtsel.Y1 trtsel.Y2 <- trtsel(event ~ Y2*trt, treatment.name = "trt", data = tsdata, default.trt = "trt all") trtsel.Y2 ############################### ## Compare marker performance ############################### # Plot treatment effect curves with pointwise confidence intervals ## use more bootstraps in practice compare(x = trtsel.Y1, x2 = trtsel.Y2, bootstraps = 10, plot = TRUE, ci = "horizontal", conf.bands = TRUE)
a method for evaluating a trtsel object
evaluate(x, ...)evaluate(x, ...)
x |
object |
... |
not used |
Evaluates the ability of one or more biomarkers for their ability to guide patient treatment recommendations. (Bias-corrected) summary measures of marker performance are estimated and confidence intervals are provided. This function accepts as input an object of class "trtsel", created using the function "trtsel".
## S3 method for class 'trtsel' evaluate(x, ..., bias.correct = TRUE, bootstraps = 1000, alpha = 0.05)## S3 method for class 'trtsel' evaluate(x, ..., bias.correct = TRUE, bootstraps = 1000, alpha = 0.05)
x |
An object of class "trtsel", created by using the function "trtsel." |
... |
ignored. |
bias.correct |
logical indicator of whether to bias-correct measures for over-optimism using bootstrap-bias correction. When the same data is used to fit and evaluate the model, performance measures are over-optimistic. Setting this equal to TRUE uses a bootstrap method to bias-correct performance measures. See details for more information. |
bootstraps |
Number of bootstrap replicates for creating confidence intervals for each performance measure. The default value is 1000. Set bootstraps = 0 if no confidence intervals are desired. |
alpha |
(1-alpha)*100% confidence intervals are calculated. Default value is alpha = 0.05 which yields 95% CI's. The same alpha is used for the two-sided type-I error for the test of H0: No decrease in event rate under marker-based treatment. |
A list with the following components (see Janes et al. (2013) for a description of the summary measures and estimators):
test.Null |
List of results of a test of the null hypothesis H0: No decrease in event rate under marker-based treatment. Contains "reject" (logical; was H0 rejected), p.value, z.statistic, and alpha |
estimates |
data.frame of dimension 1x9 of summary measure estimates. Includes: p.rec.trt : proportion recommended treatment; p.rec.notrt : proportion recommended no treatment; B.neg.emp, B.neg.mod: Average benefit of no treatment among those recommended no trt, empirical and model-based estimates; B.pos.emp, B.neg.mod: Average benefit of treatment among those recommended trt, empirical and model-based estimates; Theta.emp, Theta.mod: Decrease in rate of outcomes under marker-based treatment, empirical and model-based estimates; Var.Delta: variance in estimated treatment effect; TG: Total gain. ER.trt0.emp/mod, ER.trt1.emp/mod, ER.mkrbased.emp/mod: Event rates under trt = 0, trt = 1 or for marker-based treatment. Marker.Thresh: Marker positivity threshold– defined as the maximum marker value such that estimated treatment effect < "thresh" (=treatment effect used to define the treatment rule, this is set when creating the trtsel object). If all observations are marker negative (or all are positive), Marker.Thresh has value NA |
conf.intervals |
data.frame of dimension 2x9 with bootstrap-based confidence intervals for each summary measures. If bootstraps = 0 or boot = FALSE, this component is NULL. |
The evaluate function used this way both fit and evaluates a risk model using the same data, which is known to bias performance measure estimates to be overly optimistic. To correct for this bias, the evaluate function by default sets bias.correct=TRUE. This implements bootstrap bias correction via the “refined bootstrap" method described in Efron and Tibshirani 1994. In short, we sample BB bootstrap datasets. For each, obtain a new treatment selection rule based on the re-fit model and calculate the difference in estimated performance of this rule using the bootstrap vs. original data. The average of these differences estimates the bias. We shift naive performance estimates and confidence intervals down by the estimated bias.
trtsel for creating trtsel objects, plot.trtsel for plotting risk curves and more, calibrate.trtsel for assessing model calibration, and compare.trtsel to compare two trtsel object.
data(tsdata) ########################### ## Create trtsel objects ########################### trtsel.Y1 <- trtsel(event ~ Y1*trt, treatment.name = "trt", data = tsdata, study.design = "RCT", family = binomial(link = "logit"), default.trt = "trt all") trtsel.Y1 ################################# ## Evaluate marker performance ################################# # Marker Y1 estimates.Y1 <- evaluate(trtsel.Y1, bootstraps = 50) estimates.Y1data(tsdata) ########################### ## Create trtsel objects ########################### trtsel.Y1 <- trtsel(event ~ Y1*trt, treatment.name = "trt", data = tsdata, study.design = "RCT", family = binomial(link = "logit"), default.trt = "trt all") trtsel.Y1 ################################# ## Evaluate marker performance ################################# # Marker Y1 estimates.Y1 <- evaluate(trtsel.Y1, bootstraps = 50) estimates.Y1
Function to check if an object is of class "trtsel"
is.trtsel(x)is.trtsel(x)
x |
Any R object. |
Returns TRUE or FALSE depending on whether x is a "trtsel" object or not.
Plots a treatment selection marker. Estimated "risk curves" and "treatment effect curves" are plotted. An object of class "trtsel" must first be created using the function "trtsel" by supplying a data.frame containing marker, treatment, and event status information.
## S3 method for class 'trtsel' plot(x, bootstraps = 500, plot.type = c("treatment effect", "risk", "cdf", "selection impact"), ci = c("default", "horizontal", "vertical", "none"), alpha = 0.05, fixed.values = NULL, offset = 0.01, conf.bands = TRUE, conf.bandsN = 100, trt.names = c("Treatment", " No \nTreatment"), xlab = NULL, ylab = NULL, xlim = NULL, ylim = NULL, main = NULL, show.marker.axis = TRUE, ...)## S3 method for class 'trtsel' plot(x, bootstraps = 500, plot.type = c("treatment effect", "risk", "cdf", "selection impact"), ci = c("default", "horizontal", "vertical", "none"), alpha = 0.05, fixed.values = NULL, offset = 0.01, conf.bands = TRUE, conf.bandsN = 100, trt.names = c("Treatment", " No \nTreatment"), xlab = NULL, ylab = NULL, xlim = NULL, ylim = NULL, main = NULL, show.marker.axis = TRUE, ...)
x |
An object of class "trtsel", created by using the function "trtsel." |
bootstraps |
Number of bootstrap replicates for creating confidence intervals and bands. Default value is 500. Set bootstraps=0 if no confidence intervals or bands are desired. |
plot.type |
Type of plot to produce. Options are "risk" (default) for risk curves which show risk of adverse event as a function of marker and treatment, "treatment effect" for the treatment effect curve which shows the difference in marker-specific risk of adverse event with vs. without treatment, "cdf" for the cumulative distribution function of the treatment effect, or "selection impact" to show a plot of the estimated event rate if different proportions of the population are treated. Cdf plots cannot be generated for a discrete marker. |
ci |
Indication of whether horizontal or vertical confidence intervals are desired. Character string of either "horizontal" (default) or "vertical." For a discrete marker only vertical confidence bands can be produced. See note below for more information. |
alpha |
(1-alpha)*100% confidence intervals are calculated. Default value is alpha = 0.05 which yields 95% CI's. |
fixed.values |
A numeric vector indicating fixed values on the x- or y-axes at which bootstrap confidence intervals are provided. If "fixed.values" are provided, point-wise confidence intervals will be printed (i.e. conf.bands will be taken as FALSE). Only applies to a continuous marker. |
offset |
If confidence intervals are to be plotted for specified fixed.values, offset is the amount of distance to offset confidence intervals so that they do not overlap on the plot. The default value is 0.01. Only applies to a continuous marker. |
conf.bands |
Indication of whether pointwise confidence intervals are shown for the curve(s). TRUE (default) or FALSE. If "fixed.values" are input, this option is ignored and no confidence bands are produced. |
conf.bandsN |
If conf.bands = TRUE, the number of points along the x- or y-axis at which to calculate the pointwise confidence intervals. The default is 100. |
trt.names |
A vector of length 2 indicating the names for the two treatment options, T= 1 and T = 0, respectively, for the plot legend. This option is only used when plot.type="risk". The default value is c("Treatment", "No Treatment"). |
xlab |
A label for the x-axis. Default values depend on plot.type. |
ylab |
A label for the y-axis. Default values depend on plot.type. |
xlim |
The limits for the x-axisof the plot, in the form c(x1,x2) |
ylim |
The limits for the y-axis of the plot, in the form c(y1,y2) |
main |
The main title for the plot. |
show.marker.axis |
For risk curve plots with a continuous marker, should an axis showing marker values be displayed? default is TRUE. |
... |
N/A |
Generates a plot. In addition, if the function call is assigned to a variable (as in "myplot <- plot(mytrtsel)"), plot.trtsel returns a list composed of:
plot |
ggplot object containing the printed plot. |
ci.bounds |
A data.frame containing the bounds of the bootstrap-based confidence intervals, along with the fixed.values they are centered around, if applicable. |
For a discrete marker, vertical confidence intervals are generated by fixing the marker value and generating a bootstrap distribution for risk given marker. Bands are then generated based on the percentiles of the empirical bootstrap distribution. For a continuous marker, vertical confidence intervals are generated by fixing the empirical marker quantiles, and generating the empirical distribution of risk given marker percentile.
trtsel for creating trtsel objects,
evaluate.trtsel for evaluating marker performance,
calibrate.trtsel for assessing model calibration, and
compare.trtsel to compare two trtsel object.
data(tsdata) ########################### ## Create trtsel objects ########################### trtsel.Y1 <- trtsel(event ~ Y1*trt, treatment.name = "trt", data = tsdata, study.design = "RCT", default.trt = "trt all") ########################## ## Use the plot function ########################## # Plot risk curves plot(trtsel.Y1, main = "Marker Y1", plot.type = "risk", bootstraps = 10, #set higher in practice trt.names=c("trt","no trt")) # Now with confidence intervals around fixed.values plot(trtsel.Y1, main = "Marker Y1", plot.type = "risk", ci = "horizontal", fixed.values = c(.2, .5), offset = .01, bootstraps = 10, trt.names=c("trt","no trt")) # Plot treatment effect curves #with confidence intervals around fixed.values plot(trtsel.Y1, main = "Marker Y1", plot.type = "treatment effect", ci = "vertical", conf.bands = FALSE, fixed.values = c(10, 20), bootstraps = 10)data(tsdata) ########################### ## Create trtsel objects ########################### trtsel.Y1 <- trtsel(event ~ Y1*trt, treatment.name = "trt", data = tsdata, study.design = "RCT", default.trt = "trt all") ########################## ## Use the plot function ########################## # Plot risk curves plot(trtsel.Y1, main = "Marker Y1", plot.type = "risk", bootstraps = 10, #set higher in practice trt.names=c("trt","no trt")) # Now with confidence intervals around fixed.values plot(trtsel.Y1, main = "Marker Y1", plot.type = "risk", ci = "horizontal", fixed.values = c(.2, .5), offset = .01, bootstraps = 10, trt.names=c("trt","no trt")) # Plot treatment effect curves #with confidence intervals around fixed.values plot(trtsel.Y1, main = "Marker Y1", plot.type = "treatment effect", ci = "vertical", conf.bands = FALSE, fixed.values = c(10, 20), bootstraps = 10)
S3 method for class ”trtsel”
## S3 method for class 'calibrate.trtsel' print(x, ...)## S3 method for class 'calibrate.trtsel' print(x, ...)
x |
object of class "calibrate.trtsel", output from the calibrate.trtsel function |
... |
ignored |
S3 method for class ”trtsel”
## S3 method for class 'compare.trtsel' print(x, ...)## S3 method for class 'compare.trtsel' print(x, ...)
x |
object of class "compare.trtsel", output from the compare.trtsel function |
... |
ignored |
S3 method for class ”trtsel”
## S3 method for class 'eval.trtsel' print(x, ...)## S3 method for class 'eval.trtsel' print(x, ...)
x |
object of class "eval.trtsel", output from the eval.trtsel function |
... |
ignored |
S3 method for class ”trtsel”
## S3 method for class 'trtsel' print(x, ...)## S3 method for class 'trtsel' print(x, ...)
x |
object of class "trtsel", which can be created using function "trtsel." See ?trtsel for more information. |
... |
ignored |
S3 method for class ”trtsel_measures”
## S3 method for class 'trtsel_summary_measures' print(x, ...)## S3 method for class 'trtsel_summary_measures' print(x, ...)
x |
object of class "trtsel_summary_measures", output from the estimate_measures function |
... |
ignored |
Simulated data set consisting of two continuous markers, two discrete markers, treatment, and time-to-event status.
data(surv_tsdata)data(surv_tsdata)
A data frame with 1000 simulated observations reflecting the following clinical context. Marker Y for identifying a subset of women with estrogen-receptor positive breast cancer who do not benefit from adjuvant chemotherapy over and above tamoxifen. The clinical outcome of interest, termed "event", is 5-year breast cancer recurrence or death. Data come from a hypothetical randomized trial where subjects are randomly assigned to tamoxifen alone or tamoxifen plus chemotherapy and followed to ascertain this outcome; markers Y1 and Y2 are measured at baseline.
xia numeric vector specifying follow up time for right censored data.
dia numeric vector indicating event status (1 for recurrence or death within 5 years, 0 for censoring)
Ya numeric vector of marker values.
trta numeric vector indicating treatment status.
trtsel for creating trtsel objects, plot.trtsel for plotting risk curves and more, evaluate.trtsel for evaluating marker performance, calibrate.trtsel for assessing model calibration, and compare.trtsel to compare two trtsel object.
Creates an object of class "trtsel" given a data.frame containing marker, treatment, and adverse event status information. The functions "plot.trtsel", "evaluate.trtsel", and "calibrate.trtsel" can then be used to plot risk and treatment effect curves, estimate summary measures, and check model calibration. The function "compare.trtsel" can also be used to compare two treatment selection markers.
trtsel(formula, treatment.name, data, fittedrisk.t0 = NULL, fittedrisk.t1 = NULL, thresh = 0, prediction.time = NULL, study.design = c("RCT", "nested case-control", "stratified nested case-control"), cohort.attributes = NULL, family, default.trt = c("trt all", "trt none"))trtsel(formula, treatment.name, data, fittedrisk.t0 = NULL, fittedrisk.t1 = NULL, thresh = 0, prediction.time = NULL, study.design = c("RCT", "nested case-control", "stratified nested case-control"), cohort.attributes = NULL, family, default.trt = c("trt all", "trt none"))
formula |
a 'formula' object consisting of outcome ~ markers and marker by treatment interactions for the treatment selection model to be evaluated. The outcome can be continuous, binary or a 'Surv' object for time-to-event outcomes. Binary variable should equal 1 for cases and 0 for controls. For continuous outcomes, we assume that larger values are associated with worse outcomes. |
treatment.name |
Name of the treatment variable in data.frame "data". The treatment variable must be coded 1 for "treated" and 0 for "un-treated." |
data |
data.frame object used to fit and evaluate the model. |
fittedrisk.t0 |
Instead of providing a marker, fitted risks for T=0 and T=1 may be provided. This should be the column name of the fitted risk for T=0 that can be found in 'data'. If fitted risks are provided, a model will not be fit, and all bootstrap confidence intervals will be conditional on the model fit provided. |
fittedrisk.t1 |
Name of for the fitted risks given treatment = 1. |
thresh |
The treatment effect threshold used to define the treatment rule: Do not treat if the marker-specific treatment effect is less than "thresh". This is a numeric constant with a default value of 0. |
prediction.time |
a landmark prediction time used only when the outcome is a time-to-event Surv object |
study.design |
Character string indicating the study design used to collect the data. The three options are "RCT" (default), "nested case-control", or "stratified nested case-control". A "RCT" design is simply a randomized trial comparing T = 0 to T = 1 with the marker measured at baseline. A nested case-control or stratified nested case-control study samples cases and controls for marker measurement, perhaps stratified on treatment assignment, from a randomized trial comparing T = 0 to T = 1. See Janes et al. (2013) for a full description of these designs. If a "nested case-control" or "stratified nested case-control" design is specified, "cohort.attributes"" must be provided (see below). |
cohort.attributes |
If a "nested case-control" or "stratified nested case-control" design is specified, "cohort.attributes" must be provided. Order does matter. For the "nested case-control" design, specify the following attributes of
the randomized trial "cohort" from which the case-control sample was
selected: For the "stratitified nested case-control" design, specify the following
attributes of the randomized trial "cohort" from which the stratified
case-control sample was selected: |
family |
function passed to 'glm' describing the error distribution and link function to be used in the model. Defaults to binomial(link = "logit") when the outcome is numeric with two values 0,1 and gaussian(link = "identity") otherwise. Ignored for time-to-event outcomes. For non RCT study designs, methods only exist for family = binomial(link = "logit"). |
default.trt |
The default treatment assignment to compare with marker-based treatment. Can either be set at "trt all" (default) or "trt none". Use "trt all" if everyone is treated and the aim is to discover those who would benefit from no treatment, but use "trt none" if the common practice is to treat no-one and the goal is to discover those who would benefit from treatment. |
An object of class "trtsel," which is a list containing:
model.fit |
A list containing "coefficients" – a 4 x 4 matrix with columns for coefficient estimates, standard errors, t-statistics, and two-sided p-values. "cohort.attributes" – the vector of cohort.attributes provided "study.design" – character string of study.design provided |
derived.data |
A data.frame with event, trt, and marker information along with "fittedrisk.t0" (risk estimates given no treatment), "fittedrisk.t1" (risk estimates given treatment), "trt.effect" (treatment effect estimates), and "trt.rec" (indicator of trt recommendation) columns. |
functions |
For internal package use only |
Janes, Holly; Brown, Marshall D; Pepe, Margaret; Huang, Ying; "An Approach to Evaluating and Comparing Biomarkers for Patient Treatment Selection" The International Journal of Biostatistics. Volume 0, Issue 0, ISSN (Online) 1557-4679, ISSN (Print) 2194-573X, DOI: 10.1515/ijb-2012-0052, April 2014
plot.trtsel for plotting risk curves and more,
evaluate.trtsel for evaluating marker performance,
calibrate.trtsel for assessing model calibration, and
compare.trtsel to compare two trtsel object.
data(tsdata) ########################### ## Create trtsel objects ########################### trtsel.Y1 <- trtsel(event ~ Y1*trt, treatment.name = "trt", data = tsdata, study.design = "RCT", family = binomial("logit"), default.trt = "trt all") trtsel.Y1 trtsel.Y2 <- trtsel(event ~ Y2*trt, treatment.name = "trt", data = tsdata, default.trt = "trt all") trtsel.Y2 # calculate fitted risks using a logistic model #(one can use any model here, the point is that the fitted risks are provided ) mymod <- glm(event~trt*Y2, data= tsdata, family = binomial("logit")) tsdata$fitted.t0 <- predict(mymod, newdata=data.frame(trt = 0, Y2 = tsdata$Y2), type = "response") tsdata$fitted.t1 <- predict(mymod, newdata=data.frame(trt = 1, Y2 = tsdata$Y2), type = "response") #all bootstrapping done using this object will be conditional on the model fit. myfitted.trtsel <- trtsel( event~trt, treatment.name = "trt", data = tsdata, fittedrisk.t0 = "fitted.t0", fittedrisk.t1 = "fitted.t1", default.trt = "trt all")data(tsdata) ########################### ## Create trtsel objects ########################### trtsel.Y1 <- trtsel(event ~ Y1*trt, treatment.name = "trt", data = tsdata, study.design = "RCT", family = binomial("logit"), default.trt = "trt all") trtsel.Y1 trtsel.Y2 <- trtsel(event ~ Y2*trt, treatment.name = "trt", data = tsdata, default.trt = "trt all") trtsel.Y2 # calculate fitted risks using a logistic model #(one can use any model here, the point is that the fitted risks are provided ) mymod <- glm(event~trt*Y2, data= tsdata, family = binomial("logit")) tsdata$fitted.t0 <- predict(mymod, newdata=data.frame(trt = 0, Y2 = tsdata$Y2), type = "response") tsdata$fitted.t1 <- predict(mymod, newdata=data.frame(trt = 1, Y2 = tsdata$Y2), type = "response") #all bootstrapping done using this object will be conditional on the model fit. myfitted.trtsel <- trtsel( event~trt, treatment.name = "trt", data = tsdata, fittedrisk.t0 = "fitted.t0", fittedrisk.t1 = "fitted.t1", default.trt = "trt all")
Provides point estimates for summary measures to evaluate a rule used to select treatment.
trtsel_measures(event, trt, trt.rule, trt.effect, time, default.trt = c("trt all", "trt none"), prediction.time = NULL, silent = FALSE)trtsel_measures(event, trt, trt.rule, trt.effect, time, default.trt = c("trt all", "trt none"), prediction.time = NULL, silent = FALSE)
event |
vector for adverse event. Can be binary (1 is bad, 0 is good) or continuous (large numbers are worse). If failure time variable 'time' is set, event is used as the adverse event status indicator. |
trt |
binary trt status 1 for "treated" and 0 for "un-treated." |
trt.rule |
a binary treatment rule used to recommend treatment where 1 means recommend treatment and 0 means recommend no treatment. |
trt.effect |
estimated treatment effects. |
time |
the failure time for survival outcomes. |
default.trt |
The default treatment assignment to compare with marker-based treatment. Can either be set at "trt all" (default) or "trt none". Use "trt all" if everyone is treated and the aim is to discover those who would benefit from no treatment, but use "trt none" if the common practice is to treat no-one and the goal is to discover those who would benefit from treatment. |
prediction.time |
a landmark prediction time used only when the 'time' variable is set. |
silent |
suppress messages |
data(tsdata) #The user must specify a vector of clinical outcomes, #a vector of treatment assigments, and a vector of #marker-based treatment recommendations based on the pre-specified rule. #Here we let Y1_disc represent a user-specified treatment #rule and evaluate its performance. trtsel_measures(event = tsdata$event, trt = tsdata$trt, trt.rule = 1- tsdata$Y1_disc ) #We can also fit our own risk model using GLM, use this model #to develop a marker-based treatment recommendation, and evaluate its performance. #This allows us to obtain model-based estimates of performance: mod <- glm(event~trt*Y1_disc, data = tsdata, family = binomial()) tsdata.0 <- tsdata; tsdata.0$trt = 0 tsdata.1 <- tsdata; tsdata.1$trt = 1 delta.hat <- predict(mod, newdata= tsdata.0, type = "response") - predict(mod, newdata= tsdata.1, type = "response") trtsel_measures(event = tsdata$event, trt = tsdata$trt, trt.rule = 1- tsdata$Y1_disc, trt.effect = delta.hat )data(tsdata) #The user must specify a vector of clinical outcomes, #a vector of treatment assigments, and a vector of #marker-based treatment recommendations based on the pre-specified rule. #Here we let Y1_disc represent a user-specified treatment #rule and evaluate its performance. trtsel_measures(event = tsdata$event, trt = tsdata$trt, trt.rule = 1- tsdata$Y1_disc ) #We can also fit our own risk model using GLM, use this model #to develop a marker-based treatment recommendation, and evaluate its performance. #This allows us to obtain model-based estimates of performance: mod <- glm(event~trt*Y1_disc, data = tsdata, family = binomial()) tsdata.0 <- tsdata; tsdata.0$trt = 0 tsdata.1 <- tsdata; tsdata.1$trt = 1 delta.hat <- predict(mod, newdata= tsdata.0, type = "response") - predict(mod, newdata= tsdata.1, type = "response") trtsel_measures(event = tsdata$event, trt = tsdata$trt, trt.rule = 1- tsdata$Y1_disc, trt.effect = delta.hat )
Simulated data set consisting of two continuous markers, two discrete markers, treatment, and event status.
data(tsdata)data(tsdata)
A data frame with 1000 simulated observations reflecting the following clinical context. Markers Y1 and Y2 are candidates for identifying a subset of women with estrogen-receptor positive breast cancer who do not benefit from adjuvant chemotherapy over and above tamoxifen. The clinical outcome of interest, termed "event", is 5-year breast cancer recurrence or death. Data come from a hypothetical randomized trial where subjects are randomly assigned to tamoxifen alone or tamoxifen plus chemotherapy and followed to ascertain this outcome; markers Y1 and Y2 are measured at baseline.
trta numeric vector distinguishing chemotherapy-treated individuals (trt = 1) vs individuals treated with tamoxifen alone (trt = 0)
eventa numeric vector indicating event status (1 for recurrence or death within 5 years, 0 otherwise)
Y1a numeric vector of values for marker 1. This marker has relatively weak performance.
Y2a numeric vector of values for marker 2. This marker has strong performance.
Y1_disca discrete version of marker 1, coded 1 if Y1 > mean(Y1) and 0 otherwise.
Y2_disca discrete version of marker 2, coded 1 if Y2 > 0, and 0 otherwise.
Janes, Holly; Brown, Marshall D; Pepe, Margaret; Huang, Ying; "An Approach to Evaluating and Comparing Biomarkers for Patient Treatment Selection" The International Journal of Biostatistics. Volume 0, Issue 0, ISSN (Online) 1557-4679, ISSN (Print) 2194-573X, DOI: 10.1515/ijb-2012-0052, April 2014
trtsel for creating trtsel objects, plot.trtsel for plotting risk curves and more, evaluate.trtsel for evaluating marker performance, calibrate.trtsel for assessing model calibration, and compare.trtsel to compare two trtsel object.
Simulated case-cohort data set consisting of two continuous markers, two discrete markers, treatment, and event status.
data(tsdata)data(tsdata)
A data frame with 468 observations reflecting a 1:1 case control subcohort sample from the tsdata dataset. See ?tsdata for the clinical context these data were simulated under.
trta numeric vector distinguishing chemotherapy-treated individuals (trt = 1) vs individuals treated with tamoxifen alone (trt = 0)
eventa numeric vector indicating event status (1 for recurrence or death within 5 years, 0 otherwise)
Y1a numeric vector of values for marker 1. This marker has relatively weak performance.
Y2a numeric vector of values for marker 2. This marker has strong performance.
Y1_disca discrete version of marker 1, coded 1 if Y1 > mean(Y1) and 0 otherwise.
Y2_disca discrete version of marker 2, coded 1 if Y2 > 0, and 0 otherwise.
In order to evaluate the markers in this dataset, we need to provide the function trtsel with information from the full cohort tsdata. See the example below for help.
Janes, Holly; Brown, Marshall D; Pepe, Margaret; Huang, Ying; "An Approach to Evaluating and Comparing Biomarkers for Patient Treatment Selection" The International Journal of Biostatistics. Volume 0, Issue 0, ISSN (Online) 1557-4679, ISSN (Print) 2194-573X, DOI: 10.1515/ijb-2012-0052, April 2014
trtsel for creating trtsel objects, plot.trtsel for plotting risk curves and more, evaluate.trtsel for evaluating marker performance, calibrate.trtsel for assessing model calibration, and compare.trtsel to compare two trtsel object.
Simulated stratified case-control data set consisting of two continuous markers, two discrete markers, treatment, and event status.
data(tsdata)data(tsdata)
A data frame with 468 observations reflecting a 1:1 stratified case control subcohort sample from the tsdata dataset. Observations are stratified on treatment status. See ?tsdata for the clinical context these data were simulated under.
trta numeric vector distinguishing chemotherapy-treated individuals (trt = 1) vs individuals treated with tamoxifen alone (trt = 0)
eventa numeric vector indicating event status (1 for recurrence or death within 5 years, 0 otherwise)
Y1a numeric vector of values for marker 1. This marker has relatively weak performance.
Y2a numeric vector of values for marker 2. This marker has strong performance.
Y1_disca discrete version of marker 1, coded 1 if Y1 > mean(Y1) and 0 otherwise.
Y2_disca discrete version of marker 2, coded 1 if Y2 > 0, and 0 otherwise.
In order to evaluate the markers in this dataset, we need to provide the function trtsel with information from the full cohort tsdata. See the example below for help.
Janes, Holly; Brown, Marshall D; Pepe, Margaret; Huang, Ying; "An Approach to Evaluating and Comparing Biomarkers for Patient Treatment Selection" The International Journal of Biostatistics. Volume 0, Issue 0, ISSN (Online) 1557-4679, ISSN (Print) 2194-573X, DOI: 10.1515/ijb-2012-0052, April 2014
trtsel for creating trtsel objects, plot.trtsel for plotting risk curves and more, evaluate.trtsel for evaluating marker performance, calibrate.trtsel for assessing model calibration, and compare.trtsel to compare two trtsel object.