calcWINS.data.frame: Win statistics calculation using a data frame
In hce: Design and Analysis of Hierarchical Composite Endpoints
View source: R/calcWINS_data_frame.R
calcWINS.data.frame R Documentation
Win statistics calculation using a data frame
Description
Win statistics calculation using a data frame
Usage
## S3 method for class 'data.frame'
calcWINS(
x,
AVAL,
TRTP,
ref,
alpha = 0.05,
WOnull = 1,
SE_WP_Type = c("biased", "unbiased"),
...
)
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).
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.
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.
See Also
calcWINS(), calcWINS.hce(), calcWINS.formula().
Examples
# Example 1 - Simple use
calcWINS(x = COVID19b, AVAL = "GROUP", TRTP = "TRTP", ref = "Placebo")
# 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
n0 <- 5; n1 <- 7; p0 <- 0.2; p1 <- 0.5; x <- 1:20; delta <- 0.5
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"
CL2 <- calcWINS(x = dat, AVAL = "AVAL", TRTP = "TRTP",
ref = "P", SE_WP_Type = "unbiased")$WP
CL2$Type <- "unbiased"
DAT <- rbind(DAT, CL1, CL2)
}
WP <- DAT$WP[DAT$Type == "unbiased"]
plot(x, WP, pch = 19, xlab = "Simulations", ylab = "Win Probability", ylim = c(0., 1.1))
points(x + 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 = "red")
abline(h = c(WP0, 1), col = "blue", lty = 3)
legend("bottomleft", legend = c("True WP", "Biased", "Unbiased"),
col = c(4, 2, 3), lty = c(3, 1, 1 ), cex = 0.75)
hce documentation built on Aug. 23, 2025, 1:11 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
View source: R/calcWINS_data_frame.R
| calcWINS.data.frame | R Documentation |
Win statistics calculation using a data frame
Description
Win statistics calculation using a data frame
Usage
## S3 method for class 'data.frame'
calcWINS(
x,
AVAL,
TRTP,
ref,
alpha = 0.05,
WOnull = 1,
SE_WP_Type = c("biased", "unbiased"),
...
)
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).
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-1transformation 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
gammastatistic.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
gammaand its confidence interval.SE a data frame containing standard errors used to calculated the Confidence intervals for win statistics.
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
gammastatistic 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
gammaand CI: matches implementation inDescTools::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.
See Also
calcWINS(), calcWINS.hce(), calcWINS.formula().
Examples
# Example 1 - Simple use
calcWINS(x = COVID19b, AVAL = "GROUP", TRTP = "TRTP", ref = "Placebo")
# 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
n0 <- 5; n1 <- 7; p0 <- 0.2; p1 <- 0.5; x <- 1:20; delta <- 0.5
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"
CL2 <- calcWINS(x = dat, AVAL = "AVAL", TRTP = "TRTP",
ref = "P", SE_WP_Type = "unbiased")$WP
CL2$Type <- "unbiased"
DAT <- rbind(DAT, CL1, CL2)
}
WP <- DAT$WP[DAT$Type == "unbiased"]
plot(x, WP, pch = 19, xlab = "Simulations", ylab = "Win Probability", ylim = c(0., 1.1))
points(x + 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 = "red")
abline(h = c(WP0, 1), col = "blue", lty = 3)
legend("bottomleft", legend = c("True WP", "Biased", "Unbiased"),
col = c(4, 2, 3), lty = c(3, 1, 1 ), cex = 0.75)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.