C.for.Benefit: C-for-benefit

In CHMMaas/HTEPredictionMetrics: Heterogeneous treatment effect prediction metrics

C-for-benefit

Description

This function calculates the C-for-benefit, as proposed by D. van Klaveren et al. (2018), which measures the discriminative ability of models predicting individualized treatment effect. The C-for-benefit corresponds to the probability that from two randomly chosen matched patient pairs with unequal observed treatment effect, the pair with greater observed treatment effect also has a higher predicted treatment effect. Please note, this function is only applicable for binary outcomes.

Usage

C.for.Benefit(
  Y = NULL,
  W = NULL,
  X = NULL,
  p.0 = NULL,
  p.1 = NULL,
  tau.hat = NULL,
  matched.patients = NULL,
  CI = FALSE,
  nr.bootstraps = 50,
  message = TRUE,
  measure = "nearest",
  distance = "mahalanobis",
  estimand = NULL,
  ...
)

Arguments

Y	a vector of binary outcomes; 1 if an unfavourable event; 0 if not
W	a vector of treatment assignment; 1 for active treatment; 0 for control (or alternative treatment), note: make sure that W consists only of values of 0 and 1
X	a matrix or data.frame of patient characteristics or individualized treatment effect predictions, categorical variables may be coded as.factor() to create dummy variables when matching, do not include Y or W in this matrix
p.0	a vector of outcome probabilities under control (or alternative treatment)
p.1	a vector of outcome probabilities under active treatment
tau.hat	a vector of individualized treatment effect predictions
matched.patients	dataframe; optional if you want to provide your own dataframe (including matched.tau.hat, matched.tau.obs, and also include subclass if confidence interval needs to be computed) of matched patients, otherwise patients will be matched (default=NULL)
CI	boolean; TRUE compute confidence interval; default=FALSE do not compute confidence interval (default=FALSE)
nr.bootstraps	boolean; number of bootstraps to use for confidence interval computation (default=1)
message	boolean; TRUE display computation time message; FALSE do not display message (default=TRUE)
measure	measure option of matchit function from MatchIt package (default="nearest")
distance	distance option of matchit function from MatchIt package (default="mahalanobis)
estimand	default ATC meaning treated units are selected to be matched with control units
...	additional arguments for matchit function from MatchIt package

Value

The output of the C.for.Benefit function is a "list" with the following components.

matched.patients

a dataframe containing the matched patients.

C.for.benefit

the resulting C-for-benefit value.

lower.CI

the lower bound of the confidence interval (if CI = TRUE).

upper.CI

the upper bound of the confidence interval (if CI = TRUE).

Examples

library(HTEPredictionMetrics)
set.seed(1)
n <- 100
Y <- sample(0:1, n, replace=TRUE)
W <- sample(0:1, n, replace=TRUE)
X <- matrix(rnorm(n*3), n, 3)
p.0 <- runif(n)
p.1 <- runif(n)
tau.hat <- runif(n)
CB.out <- C.for.Benefit(Y=Y, W=W, X=X, p.0=p.0, p.1=p.1, tau.hat=tau.hat,
                        CI=TRUE, nr.bootstraps=100, message=TRUE,
                        matched.patients=NULL,
                        measure="nearest", distance="mahalanobis",
                        estimand=NULL)
CB.out

# alternatively, use a dataframe of matched patients and calculate the C-for-Benefit
out.matched <- match.patients(Y=Y, W=W, X=X,
                              p.0=p.0, p.1=p.1, tau.hat=tau.hat,
                              print=TRUE, measure="nearest",
                              distance="mahalanobis", estimand=NULL)
CB.out <- C.for.Benefit(matched.patients=out.matched$df.matched.pairs,
                        CI=TRUE, nr.bootstraps=100, message=TRUE)
CB.out

CHMMaas/HTEPredictionMetrics documentation built on June 2, 2025, 5:04 a.m.