Learn R Programming

hce (version 0.8.8)

calcWINS.data.frame: Win statistics calculation using a data frame

Description

Win statistics calculation using a data frame

Usage

# S3 method for data.frame
calcWINS(
  x,
  AVAL,
  TRTP,
  ref,
  alpha = 0.05,
  WOnull = 1,
  SE_WP_Type = c("biased", "unbiased"),
  ...
)

Value

a list containing win statistics and their confidence intervals. It contains the following named data frames:

  • summary a data frame containing number of wins, losses, and ties of the active treatment group and the overall number of comparisons.

  • WP a data frame containing the win probability and its confidence interval.

  • NetBenefit a data frame containing the net benefit and its confidence interval. This is just a 2x-1 transformation of WP and its CI.

  • WO a data frame containing the win odds and its confidence interval.

  • WR1 a data frame containing the win ratio and its confidence interval, using the transformed standard error of the gamma statistic.

  • WR2 a data frame containing the win ratio and its confidence interval, using the standard error calculated using Pties.

  • gamma a data frame containing Goodman Kruskal's gamma and its confidence interval.

  • SE a data frame containing standard errors used to calculated the Confidence intervals for win statistics.

When SE_WP_Type = "unbiased", the WP, WO and NetBenefit estimators use the unbiased variance estimator of WP. Additionally, a Wilson-type range-preserving confidence interval is provided:

  • WP_W a data frame containing the win probability and its range-preserving confidence interval.

  • NetBenefit_W a data frame containing the net benefit and its range-preserving confidence interval.

  • WO_W a data frame containing the win odds and its range-preserving confidence interval.

Arguments

x

a data frame containing subject-level data.

AVAL

variable in the data with ordinal analysis values.

TRTP

the treatment variable in the data.

ref

the reference treatment group.

alpha

2-sided significance level. The default is 0.05.

WOnull

the null hypothesis. The default is 1.

SE_WP_Type

biased or unbiased standard error for win probability. The default is biased.

...

additional parameters.

Details

When SE_WP_Type = "unbiased", the calculations for win proportion, net benefit, and win odds utilize the unbiased standard error from Brunner-Konietschke (2025) paper which is a reformulation of the original formula proposed by Bamber (1975). In this case, Wilson-type confidence intervals are calculated for the win probability, net benefit, and win odds, following the approach proposed by Schüürhuis, Konietschke, and Brunner (2025).

References

The theory of win statistics is covered in the following papers:

  • Win proportion and win odds confidence interval calculation:

    Somers RH (1962) “A New Asymmetric Measure of Association for Ordinal Variables." American Sociological Review 27.6: 799-811. doi:10.2307/2090408.

    Bamber D (1975) "The area above the ordinal dominance graph and the area below the receiver operating characteristic graph." Journal of Mathematical Psychology 12.4: 387-415. doi:10.1016/0022-2496(75)90001-2.

    DeLong ER et al. (1988) "Comparing the Areas Under Two or More Correlated Receiver Operating Characteristic Curves: A Nonparametric Approach." Biometrics 44.3: 837-845. doi:10.2307/2531595.

    Brunner E et al. (2021) "Win odds: an adaptation of the win ratio to include ties." Statistics in Medicine 40.14: 3367-3384. doi:10.1002/sim.8967.

    Gasparyan SB et al. (2021) "Adjusted win ratio with stratification: calculation methods and interpretation." Statistical Methods in Medical Research 30.2: 580-611. doi:10.1177/0962280220942558.

    Gasparyan SB et al. (2021) "Power and sample size calculation for the win odds test: application to an ordinal endpoint in COVID-19 trials." Journal of Biopharmaceutical Statistics 31.6: 765-787. doi:10.1080/10543406.2021.1968893.

    Brunner E, Konietschke F. (2025) "An unbiased rank-based estimator of the Mann–Whitney variance including the case of ties." Statistical Papers 66.20. doi:10.1007/s00362-024-01635-0.

  • Win ratio: the first CI utilizes the standard error derived from the gamma statistic standard error as outlined by:

    Gasparyan SB, Kowalewski EK, Buenconsejo J, Koch GG. (2023) "Hierarchical Composite Endpoints in COVID-19: The DARE-19 Trial." In Case Studies in Innovative Clinical Trials, Chapter 7, 95–148. Chapman; Hall/CRC. doi:10.1201/9781003288640-7.

  • Win ratio: the second CI utilizes the standard error presented by:

    Yu RX, Ganju J. (2022) "Sample size formula for a win ratio endpoint." Statistics in Medicine 41.6: 950-63. doi:10.1002/sim.9297.

  • Goodman Kruskal's gamma and CI: matches implementation in DescTools::GoodmanKruskalGamma() and based on:

    Agresti A. (2002) Categorical Data Analysis. John Wiley & Sons, pp. 57-59. doi:10.1002/0471249688.

    Brown MB, Benedetti JK. (1977) "Sampling Behavior of Tests for Correlation in Two-Way Contingency Tables." Journal of the American Statistical Association 72, 309-315. doi:10.1080/01621459.1977.10480995.

    Goodman LA, Kruskal WH. (1954) "Measures of association for cross classifications." Journal of the American Statistical Association 49, 732-764. doi:10.1080/01621459.1954.10501231.

    Goodman LA, Kruskal WH. (1963) "Measures of association for cross classifications III: Approximate sampling theory." Journal of the American Statistical Association 58, 310-364. doi:10.1080/01621459.1963.10500850.

  • Unbiased variance estimator for WP and Wilson-type range -preserving confidence intervals are based on:

    Brunner E, Konietschke F. (2025) "An unbiased rank-based estimator of the Mann–Whitney variance including the case of ties." Statistical Papers 66: 20. doi:10.1007/s00362-024-01635-0.

    Schüürhuis S, Konietschke F, Brunner E. (2025) "A New Approach to the Nonparametric Behrens–Fisher Problem With Compatible Confidence Intervals." Biometrical Journal 67.6. doi:10.1002/bimj.70096.

See Also

calcWINS(), calcWINS.hce(), calcWINS.formula().

Examples

Run this code
# Example 1 - Simple use
calcWINS(x = COVID19b, AVAL = "GROUP", TRTP = "TRTP", ref = "Placebo")
calcWINS(x = COVID19b, AVAL = "GROUP", TRTP = "TRTP", ref = "Placebo", SE_WP_Type = "unbiased")
# Example 2 - Different variance estimators  
FREQ <- c(16, 5, 0, 1, 0, 4, 1, 5, 7, 2)
dat0 <- data.frame(AVAL = rep(5:1, 2), TRTP = rep(c('A', 'P'), each = 5))
dat <- dat0[rep(row.names(dat0), FREQ),]
## By default, the variance estimator applies a 1/n weighting to the coefficients
## This approach matches the Somers' D (C|R) estimator, where `C|R` indicates that 
## the column variable Y is treated as the independent variable and the row
## variable X is treated as the dependent variable.
calcWINS(AVAL ~ TRTP, data = dat)$WP
## The Brunner-Konietschke estimator
UNB <- calcWINS(AVAL ~ TRTP, data = dat,  SE_WP_Type = "unbiased")
cbind(UNB$WP, SE = UNB$SE$WP_SE)
## The Brunner-Munzel test, based on the DeLong-Clarke-Pearson formula for the variance estimation,
## applies 1/(n - 1) weighting to the coefficients.
dat1 <- IWP(data = dat, AVAL = "AVAL", TRTP = "TRTP", ref = "P")
WP <- tapply(dat1$AVAL_, dat1$TRTP, mean)
VAR <- tapply(dat1$AVAL_, dat1$TRTP, var)
N <- tapply(dat1$AVAL_, dat1$TRTP, length)
SE <- sqrt(sum(VAR/N))
c(WP = WP[[1]], SE = SE)
# Example 3 - Simulations: Biased vs unbiased vs Wilson confidence intervals for Win Probability
set.seed(1)
n0 <- 5; n1 <- 7; p0 <- 0.2; p1 <- 0.5; x <- 1:20; delta <- 0.15
WP0 <- (p1 - p0)/2 + 0.5
DAT <- NULL
for(i in x){
  dat <- data.frame(AVAL = c(rbinom(n1, size = 1, p1), rbinom(n0, size = 1, p0)), 
  TRTP = c(rep("A", n1), rep("P", n0)))
  CL1 <- calcWINS(x = dat, AVAL = "AVAL", TRTP = "TRTP", ref = "P")$WP
  CL1$Type <- "biased"
  fit <- calcWINS(x = dat, AVAL = "AVAL", TRTP = "TRTP", 
                ref = "P", SE_WP_Type = "unbiased")
  CL2 <- fit$WP
  CL2$Type <- "unbiased"
  CL3 <- fit$WP_W
  CL3$Type <- "Wilson"
  DAT <- rbind(DAT, CL1, CL2, CL3)
  }
WP <- DAT$WP[DAT$Type == "unbiased"]
plot(x, WP, pch = 19, xlab = "Simulations", ylab = "Win Probability", 
            ylim = c(0., 1.1), xlim = c(0, max(x) + 1))
points(x + delta, WP, pch = 19)
points(x + 2*delta, WP, pch = 19)
arrows(x, DAT$LCL[DAT$Type == "unbiased"], 
       x, DAT$UCL[DAT$Type == "unbiased"], angle = 90, code = 3, length = 0.05, "green")
       arrows(x + delta, DAT$LCL[DAT$Type == "biased"], 
       x + delta, DAT$UCL[DAT$Type == "biased"], angle = 90, code = 3, 
       length = 0.05, col = "orange")
arrows(x + 2*delta, DAT$LCL[DAT$Type == "Wilson"], 
       x + 2*delta, DAT$UCL[DAT$Type == "Wilson"], angle = 90, code = 3, 
       length = 0.05, col = "blue")
abline(h = c(WP0, 1), col = c("darkgreen", "darkred"), lty = c(3, 4))
legend("bottomleft", legend = c("True WP", "UnBiased", "Biased", "Wilson", "Null"), 
       col = c("darkgreen", "green", "orange", "blue", "darkred"), 
       lty = c(3, 1, 1, 1, 4), cex = 0.75, ncol = 3)
       title("Win Probability: Biased vs Unbiased vs Wilson CI")
# End of Example 3

Run the code above in your browser using DataLab