Package 'hce'

Event-Time dataset for kidney outcomes.

Description

A dataset with multiple kidney outcomes over time scale outcomes of 1500 patients in the ADSL dataset.

Usage

ADET

Format

a data frame with 604 rows (events) and 6 variables:

ID

patient identifiers, numeric

AVAL

occurence time of the event, numeric

PARAM

name of the event, character

PARAMCD

coded name of the event, character

PARAMN

type of the event, outcomes 1-7, where a higher value means a better outcome, numeric

TRTPN

treatment values, 1 Active or 2 Placebo, numeric

Source

Heerspink HL et al "Development and validation of a new hierarchical composite endpoint for clinical trials of kidney disease progression." Journal of the American Society of Nephrology (2023): https://doi.org/10.1681/ASN.0000000000000243.

Examples

head(ADET)
# Number of unique patients
length(unique(ADET$ID)) 
# Number of events per event type
barplot(table(ADET$PARAM))

---

Laboratory dataset for Glomerular Filtration Rate (GFR) measurements.

Description

A dataset of laboratory measurements of kidney function over time for the 1500 patients in the ADSL dataset.

Usage

ADLB

Format

a data frame with 13980 rows and 8 variables:

ID

patient identifiers, numeric

TRTPN

treatment values, 1 Active or 2 Placebo, numeric

AVAL

measurement value, numeric

ADAY

measurement day in the study, numeric

AVISITN

hospital visit number, numeric

PARAM

name of the event, GFR measurements, character

PARAMCD

coded name of the event, GFR, character

PARAMN

type of the event is set to 7 for all measurements, numeric

Source

Heerspink HL et al "Development and validation of a new hierarchical composite endpoint for clinical trials of kidney disease progression." Journal of the American Society of Nephrology (2023): https://doi.org/10.1681/ASN.0000000000000243.

Examples

head(ADLB)

---

Baseline characteristics dataset of patients with kidney function assessments.

Description

A data frame with baseline characteristics for 1500 patients used to derive KHCE dataset.

Usage

ADSL

Format

a data frame with 1500 rows and 4 variables:

ID

patient identifiers, numeric

TRTPN

treatment values, 1 Active or 2 Placebo, numeric

EGFRBL

Baseline GFR values of patients, numeric

STRATAN

strata 1-4, higher value means a higher risk for kidney disease progression, numeric

Source

Heerspink HL et al "Development and validation of a new hierarchical composite endpoint for clinical trials of kidney disease progression." Journal of the American Society of Nephrology (2023): https://doi.org/10.1681/ASN.0000000000000243.

Examples

head(ADSL)

---

A generic function for coercing data structures to hce objects

Description

A generic function for coercing data structures to hce objects

Usage

as_hce(x, ...)

Arguments

x	an object used to select a method.
...	additional parameters.

Value

an hce object.

See Also

as_hce.data.frame(), as_hce.default().

Examples

### data frames 
data(HCE1)
HCE <- as_hce(HCE1)
calcWINS(HCE)

---

Coerce a data frame to an hce object

Description

Coerce a data frame to an hce object

Usage

## S3 method for class 'data.frame'
as_hce(x, ...)

Arguments

x	a data frame.
...	additional parameters.

Value

an hce object.

See Also

as_hce(), as_hce.default().

Examples

# The case when all required variables `AVAL0`, `GROUP`, `PADY`, and `TRTP` are present.
KHCE <- as_hce(KHCE)
## Converts to an `adhce` object
class(KHCE)
calcWO(KHCE)
# The case when only `AVAL` and `TRTP`.
## Converts to an `hce` object
dat <- KHCE[, c("TRTP", "AVAL")]
dat <- as_hce(dat)
class(dat)
summaryWO(dat)

---

Coerce a data frame to an hce object

Description

Coerce a data frame to an hce object

Usage

## Default S3 method:
as_hce(x, ...)

Arguments

x	an object.
...	additional parameters.

Value

an hce object.

See Also

as_hce(), as_hce.data.frame().

Examples

dat <- KHCE
class(dat) <- "moo" # non-existent class
as_hce(dat) # tries to convert to an hce object
## It still works because the inheritance converted it to a data frame

---

A generic function for calculating win statistics

Description

A generic function for calculating win statistics

Usage

calcWINS(x, ...)

Arguments

x	an object used to select a method.
...	further arguments passed to or from other methods.

Value

a data frame containing calculated values.

See Also

calcWINS.hce(), calcWINS.formula(), calcWINS.data.frame() methods.

---

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). 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).

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.

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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/10.1002/bimj.70096.

See Also

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

Examples

# 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

---

Win statistics calculation using formula syntax

Description

Win statistics calculation using formula syntax

Usage

## S3 method for class 'formula'
calcWINS(x, data, ...)

Arguments

x	an object of class formula.
data	a data frame.
...	additional parameters.

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.

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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/10.1002/bimj.70096.

See Also

calcWINS(), calcWINS.hce(), calcWINS.data.frame().

Examples

# Example 1
calcWINS(x = GROUP ~ TRTP, data = COVID19b)
# Example 2
calcWINS(x = GROUP ~ TRTP, data = COVID19, ref = "Placebo", alpha = 0.01, WOnull = 1.2)
#' Example 3
calcWINS(x = GROUP ~ TRTP, data = COVID19)$WP
calcWINS(x = GROUP ~ TRTP, data = COVID19, SE_WP_Type = "unbiased")$WP

---

Win statistics calculation for hce objects

Description

Win statistics calculation for hce objects

Usage

## S3 method for class 'hce'
calcWINS(x, ...)

Arguments

x	an hce object.
...	additional parameters.

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.

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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/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. https://doi.org/10.1002/bimj.70096.

See Also

calcWINS(), calcWINS.formula(), calcWINS.data.frame().

Examples

# Example 1
COVID19HCE <- hce(GROUP = COVID19$GROUP, TRTP = COVID19$TRTP)
calcWINS(COVID19HCE)
# Example 2
COVID19bHCE <- hce(GROUP = COVID19b$GROUP, TRTP = COVID19b$TRTP)
calcWINS(COVID19bHCE, ref = "Placebo", WOnull = 1.1, alpha = 0.01)
# Example 3
calcWINS(COVID19HCE, SE_WP_Type = "unbiased")$WP
calcWINS(COVID19HCE, SE_WP_Type = "biased")$WP

---

A generic function for calculating win odds

Description

A generic function for calculating win odds

Usage

calcWO(x, ...)

Arguments

x	an object used to select a method.
...	further arguments passed to or from other methods.

Value

a data frame containing calculated values.

See Also

calcWO.hce(), calcWO.formula(), calcWO.data.frame() methods.

---

Win odds calculation using a data frame

Description

Win odds calculation using a data frame

Usage

## S3 method for class 'data.frame'
calcWO(x, AVAL, TRTP, ref, alpha = 0.05, WOnull = 1, ...)

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	significance level. The default is 0.05.
WOnull	the null hypothesis. The default is 1.
...	additional parameters.

Value

a data frame containing the win odds and its confidence interval. It contains the following columns:

• WO calculated win odds.

• LCL lower confidence limit.

• UCL upper confidence limit.

• SE standard error of the win odds.

• WOnull win odds of the null hypothesis (specified in the WOnull argument).

• alpha two-sided significance level for calculating the confidence interval (specified in the alpha argument).

• Pvalue p-value associated with testing the null hypothesis.

• WP calculated win probability.

• LCL_WP lower confidence limit for WP.

• UCL_WP upper confidence limit for WP.

• SE_WP standard error of the win probability.

• SD_WP standard deviation of the win probability, calculated as SE_WP multiplied by sqrt(N).

• N total number of patients in the analysis.

References

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

See Also

calcWO(), calcWO.hce(), calcWO.formula().

Examples

data(HCE4)
calcWO(x = HCE4, AVAL = "AVAL", TRTP = "TRTP", ref = "P")

---

Win odds calculation using formula syntax

Description

Win odds calculation using formula syntax

Usage

## S3 method for class 'formula'
calcWO(x, data, ...)

Arguments

x	an object of class formula.
data	a data frame.
...	additional parameters.

Value

a data frame containing the win odds and its confidence interval. It contains the following columns:

• WO calculated win odds.

• LCL lower confidence limit.

• UCL upper confidence limit.

• SE standard error of the win odds.

• WOnull win odds of the null hypothesis (specified in the WOnull argument).

• alpha two-sided significance level for calculating the confidence interval (specified in the alpha argument).

• Pvalue p-value associated with testing the null hypothesis.

• WP calculated win probability.

• LCL_WP lower confidence limit for WP.

• UCL_WP upper confidence limit for WP.

• SE_WP standard error of the win probability.

• SD_WP standard deviation of the win probability, calculated as SE_WP multiplied by sqrt(N).

• N total number of patients in the analysis.

• formula returning the specified formula in the x argument.

• ref showing how the reference group was selected. Can be modifying by specifying the ref argument.

References

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

See Also

calcWO(), calcWO.hce(), calcWO.data.frame().

Examples

#Example 1
data(HCE1)
calcWO(AVAL ~ TRTP, data = HCE1)

#Example 2
calcWO(GROUP ~ TRTP, data = COVID19, ref = "Placebo", alpha = 0.01)

---

Win odds calculation for hce objects

Description

Win odds calculation for hce objects

Usage

## S3 method for class 'hce'
calcWO(x, ...)

Arguments

x	an hce object.
...	additional parameters.

Value

a data frame containing the win odds and its confidence interval. It contains the following columns:

• WO calculated win odds.

• LCL lower confidence limit.

• UCL upper confidence limit.

• SE standard error of the win odds.

• WOnull win odds of the null hypothesis (specified in the WOnull argument).

• alpha two-sided significance level for calculating the confidence interval (specified in the alpha argument).

• Pvalue p-value associated with testing the null hypothesis.

• WP calculated win probability.

• LCL_WP lower confidence limit for WP.

• UCL_WP upper confidence limit for WP.

• SE_WP standard error of the win probability.

• SD_WP standard deviation of the win probability, calculated as SE_WP multiplied by sqrt(N).

• N total number of patients in the analysis.

References

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

See Also

calcWO(), calcWO.formula(), calcWO.data.frame().

Examples

Rates_A <- c(1, 1.5) 
Rates_P <- c(2, 2) 
dat <- simHCE(n = 500, TTE_A = Rates_A, TTE_P = Rates_P, CM_A = 1.25, CM_P = 1)
calcWO(dat)
calcWO(dat, ref = "A", WOnull = 1, alpha = 0.01)

---

COVID-19 ordinal scale dataset (full report).

Description

A dataset with COVID-19 ordinal scale outcomes for 1062 patients.

Usage

COVID19

Format

a data frame with 1062 rows and 2 variables:

GROUP

type of the event, ordinal outcomes 1-8, where a higher value means a better outcome

TRTP

treatment values, A Active or P Placebo, character

Source

Beigel JH et al. "Remdesivir for the treatment of Covid-19-final report." New England Journal of Medicine 383.19 (2020): 1813-1836. https://doi.org/10.1056/NEJMoa2007764.

Examples

#Frequencies
table(COVID19)
mosaicplot(table(COVID19), col = c(1, 8, 6, 2, 4, 5, 3, 7), 
xlab = "Treatment", ylab = "Ordinal Scale", main = "COVID-19 ordinal scale")
# Convert to an hce object
COVID19HCE <- hce(GROUP = COVID19$GROUP, TRTP = COVID19$TRTP)
# Summary wins, losses, and ties with win odds
summaryWO(COVID19HCE, ref = "Placebo")

---

COVID-19 ordinal scale dataset (preliminary report).

Description

A dataset with COVID-19 ordinal scale outcomes for 844 patients.

Usage

COVID19b

Format

a data frame with 844 rows and 2 variables:

GROUP

type of the event, ordinal outcomes 1-8, where a higher value means a better outcome

TRTP

treatment values, Active or Placebo, character

Source

Beigel JH et al. "Remdesivir for the treatment of Covid-19-final report." New England Journal of Medicine 383.19 (2020): 1813-1836. https://doi.org/10.1056/NEJMoa2007764.

Examples

#Frequencies
table(COVID19b)
mosaicplot(table(COVID19b), col = c(1, 8, 6, 2, 4, 5, 3, 7), 
xlab = "Treatment", ylab = "Ordinal Scale", main = "COVID-19 ordinal scale")
# Calculate win statistics
calcWINS(x = COVID19b, AVAL = "GROUP", TRTP = "TRTP", ref = "Placebo")

---

COVID-19 ordinal scale dataset for a combination therapy.

Description

A dataset with COVID-19 ordinal scale outcomes for 1033 patients.

Usage

COVID19plus

Format

a data frame with 1033 rows and 4 variables:

ID

patient identifiers, numeric

TRTP

treatment values, A Active or P Placebo, character

GROUP

type of the event, ordinal outcomes 1-8, where a higher value means a better outcome

BASE

baseline ordinal values

Source

Kalil AC et al. "Baricitinib plus Remdesivir for Hospitalized Adults with Covid-19." New England Journal of Medicine 384.9 (2021): 795-807. https://doi.org/10.1056/NEJMoa2031994.

Examples

COVID19HCE <- hce(GROUP = COVID19plus$GROUP, TRTP = COVID19plus$TRTP)
# Summary wins, losses, and ties with win odds
summaryWO(COVID19HCE, ref = "P")

---

A generic function for calculating win odds based on a threshold

Description

A generic function for calculating win odds based on a threshold

Usage

deltaWO(x, delta, ...)

Arguments

x	an object used to select a method.
delta	a numeric threshold.
...	further arguments passed to or from other methods.

Value

a data frame containing calculated values.

See Also

deltaWO.adhce() method.

---

Win odds calculation based on a threshold for adhce objects

Description

Win odds calculation based on a threshold for adhce objects

Usage

## S3 method for class 'adhce'
deltaWO(x, delta, ref = unique(x$TRTP)[1], alpha = 0.05, WOnull = 1, ...)

Arguments

x	an adhce object.
delta	a numeric threshold.
ref	the reference treatment group.
alpha	significance level. The default is 0.05.
WOnull	the null hypothesis. The default is 1.
...	additional parameters.

Value

a data frame containing the win odds and its confidence interval. It contains the following columns:

• WO calculated win odds.

• LCL lower confidence limit.

• UCL upper confidence limit.

• SE standard error of the win odds.

• WOnull win odds of the null hypothesis (specified in the WOnull argument).

• alpha two-sided significance level for calculating the confidence interval (specified in the alpha argument).

• Pvalue p-value associated with testing the null hypothesis.

• WP calculated win probability.

• LCL_WP lower confidence limit for WP.

• UCL_WP upper confidence limit for WP.

• SE_WP standard error of the win probability.

• SD_WP standard deviation of the win probability, calculated as SE_WP multiplied by sqrt(N).

• N total number of patients in the analysis.

• ref the reference group.

• delta the threshold.

See Also

deltaWO(), calcWO().

Examples

# Example using the kidney dataset
dat <- as_hce(KHCE)
calcWO(dat, ref = "P")
## The exact same result
deltaWO(dat, delta = 0, ref = "P")
## A large threshold
deltaWO(dat, delta = 10, ref = "P")

---

The Generalized Log-Logistic Distribution

Description

Density, distribution function, quantile function, hazard, cumulative hazard, and random generation for the generalized log-logistic distribution.

Usage

dGLL(x, rate, shape = 1, theta = 0, log = FALSE)

pGLL(q, rate, shape = 1, theta = 0)

qGLL(p, rate, shape = 1, theta = 0)

rGLL(n, rate, shape = 1, theta = 0)

hGLL(x, rate, shape = 1, theta = 0)

HGLL(x, rate, shape = 1, theta = 0)

Arguments

x, q	vector of quantiles.
rate	positive rate parameter of the distribution.
shape	positive shape parameter of the distribution.
theta	non-negative additional parameter of the distribution, with default value 0.
log	logical; if TRUE, densities are given as logarithms.
p	vector of probabilities.
n	number of observations. Must be a single non-negative integer.

Details

The generalized log-logistic distribution with rate parameter $\lambda > 0$, shape parameter $\alpha > 0$, and parameter $\theta \ge 0$ has survival function

$S(t \mid \lambda, \alpha, \theta) = \left(1 + \theta \lambda t^\alpha\right)^{-1 / \theta}, \qquad \theta > 0.$

The corresponding cumulative distribution function is

$F(t \mid \lambda, \alpha, \theta) = 1 - \left(1 + \theta \lambda t^\alpha\right)^{-1 / \theta}.$

The quantile function is

$Q(p \mid \lambda, \alpha, \theta) = \left( \frac{(1 - p)^{-\theta} - 1}{\theta \lambda} \right)^{1 / \alpha}, \qquad 0 \le p \le 1,\ \theta > 0.$

The cumulative hazard function is

$H(t \mid \lambda, \alpha, \theta) = \frac{\log\left(1 + \theta \lambda t^\alpha\right)}{\theta}.$

The density function is

$f(t \mid \lambda, \alpha, \theta) = \lambda \alpha t^{\alpha - 1} \left(1 + \theta \lambda t^\alpha\right)^{-1 / \theta - 1}.$

For dGLL(..., log = TRUE), the logarithm of the density is returned. For $\theta > 0$,

$\log f(t \mid \lambda, \alpha, \theta) = \log(\lambda) + \log(\alpha) + (\alpha - 1)\log(t) - \left(\frac{1}{\theta} + 1\right)\log\left(1 + \theta \lambda t^\alpha\right).$

The hazard function is

$h(t \mid \lambda, \alpha, \theta) = \frac{\lambda \alpha t^{\alpha - 1}} {1 + \theta \lambda t^\alpha}.$

Random generation is performed by inverse transform sampling. If $U \sim \mathrm{Uniform}(0,1)$, then

$T = Q(U \mid \lambda, \alpha, \theta)$

has the generalized log-logistic distribution.

As $\theta \to 0$, this reduces to the Weibull distribution with survival function

$S(t \mid \lambda, \alpha) = \exp\left(-\lambda t^\alpha\right).$

The corresponding quantile function is

$Q(p \mid \lambda, \alpha) = \left( \frac{-\log(1 - p)}{\lambda} \right)^{1 / \alpha}.$

In this case, dGLL(..., log = TRUE) returns the corresponding Weibull log-density. This corresponds to the Weibull distribution in stats::dweibull(), stats::pweibull(), stats::qweibull(), and stats::rweibull() with shape = shape and scale = rate^(-1 / shape).

When $\theta = 1$, the survival function becomes

$S(t \mid \lambda, \alpha, 1) = \left(1 + \lambda t^\alpha\right)^{-1},$

corresponding to the log-logistic distribution.

Value

For dGLL(), pGLL(), qGLL(), hGLL(), and HGLL(), a numeric vector of the same length as the main input (x, q, or p). For rGLL(), a numeric vector of length n.

References

Wienke A. Frailty Models in Survival Analysis. Chapman and Hall/CRC (2010).

See Also

rweibullGF() for simulation of a Weibull distribution with gamma frailty.

Examples

## Example 1: Compare the density of GLL with different values of `theta`
x <- seq(0, 10, length.out = 100)
y1 <- pGLL(x, rate = 0.5, shape = 2, theta = 1)
y0 <- pGLL(x, rate = 0.5, shape = 2, theta = 0)
plot(x, y1, type = "l", ylab = "Cumulative distribution function")
lines(x, y0, col = "red", lty = 2)

---

Helper function for hce objects

Description

Helper function for hce objects

Usage

hce(GROUP, TRTP, AVAL0 = NULL, PADY = NULL)

Arguments

GROUP	a character vector or a factor containing events. If a factor, its levels are used to define the hierarchy. Otherwise, the vector is converted to a factor.
TRTP	a character vector of the same length as GROUP, indicating assigned treatment groups.
AVAL0	a numeric vector of the same length as GROUP, indicating containing analysis values within each category. The default is 0.
PADY	numeric specifying the length of follow-up in years.

Value

an object of class hce or adhce (if AVAL0 is provided). The result is a subject-level data frame, where each row corresponds to one subject,

See Also

as_hce() for coercing to hce objects.

Examples

# Example 1 - Both `AVAL0` and `PADY` are provided. The output is an `adhce` object.
GROUP <- COVID19$GROUP
TRTP <- rep(c("A", "P"), each = 531)
dat <- hce(GROUP, TRTP, PADY = 10, AVAL0 = rnorm(1062))
class(dat)
calcWO(dat)
summaryWO(dat) # Uses the `GROUP` variable for summary.
# Example 2 - Only `AVAL0` is provided, `PADY` is calculated as the maximum of `AVAL0`. 
# The output is an `adhce` object.
set.seed(2022)
d <- hce(GROUP = sample(x = c("A", "B", "C"), size = 10, replace = TRUE), 
TRTP = rep(c("Active", "Control"), each = 5), 
AVAL0 = c(rnorm(5, mean = 1), rnorm(5)))
calcWO(d, ref = "Control")
## modify the hierarchy by proving a factor for the GROUP variable. 
## calcWO() applied to an hce rederives `AVAL` based on the `GROUP` variable.
d$GROUP <- factor(d$GROUP, levels = c("C", "B", "A"))
calcWO(d, ref = "Control")
# Example 3 - Provide only `PADY` and not `AVAL0` will not make any difference.
GROUP <- COVID19$GROUP
TRTP <- rep(c("A", "P"), each = 531)
dat <- hce(GROUP, TRTP, PADY = 10)
class(dat)
calcWO(dat)
dat <- hce(GROUP, TRTP)
class(dat)
calcWO(dat)

---

HCE1, HCE2, HCE3, HCE4 datasets for 1000 patients with different treatment effects.

Description

A simulated dataset containing the ordinal values and other attributes for 1000 patients. HCE1

Usage

HCE1

Format

a data frame with 1000 rows and 6 variables:

ID

subject ID, numbers from 1 to 1000

TRTP

treatment values, A Active or P Placebo, character

GROUP

type of the event, either Time-To-Event (TTE) or Continuous (C), character

GROUPN

type of the event, for the ordering of outcomes in the GROUP variable, numeric

AVALT

the timing of the time-to-event outcomes, numeric

AVAL0

original values for each type of the event, time for TTE outcomes, numeric values for Continuous outcomes, numeric

AVAL

AVAL = AVAL0 + GROUPN, ordinal analysis values for the HCE analysis. For the continuous outcome the values of AVAL0 are shifted to start always from 0. Numeric, but caution NOT to apply numeric operations; will give meaningless results

PADY

primary analysis day, the length of fixed follow-up in days, numeric

---

HCE1, HCE2, HCE3, HCE4 datasets for 1000 patients with different treatment effects.

Description

A simulated dataset containing the ordinal values and other attributes for 1000 patients. HCE2

Usage

HCE2

Format

a data frame with 1000 rows and 6 variables:

ID

subject ID, numbers from 1 to 1000

TRTP

treatment values, A Active or P Placebo, character

GROUP

type of the event, either Time-To-Event (TTE) or Continuous (C), character

GROUPN

type of the event, for the ordering of outcomes in the GROUP variable, numeric

AVALT

the timing of the time-to-event outcomes, numeric

AVAL0

original values for each type of the event, time for TTE outcomes, numeric values for Continuous outcomes, numeric

AVAL

AVAL = AVAL0 + GROUPN, ordinal analysis values for the HCE analysis. For the continuous outcome the values of AVAL0 are shifted to start always from 0. Numeric, but caution NOT to apply numeric operations; will give meaningless results

PADY

primary analysis day, the length of fixed follow-up in days, numeric

---

HCE1, HCE2, HCE3, HCE4 datasets for 1000 patients with different treatment effects.

Description

A simulated dataset containing the ordinal values and other attributes for 1000 patients. HCE3

Usage

HCE3

Format

a data frame with 1000 rows and 6 variables:

ID

subject ID, numbers from 1 to 1000

TRTP

treatment values, A Active or P Placebo, character

GROUP

type of the event, either Time-To-Event (TTE) or Continuous (C), character

GROUPN

type of the event, for the ordering of outcomes in the GROUP variable, numeric

AVALT

the timing of the time-to-event outcomes, numeric

AVAL0

original values for each type of the event, time for TTE outcomes, numeric values for Continuous outcomes, numeric

AVAL

AVAL = AVAL0 + GROUPN, ordinal analysis values for the HCE analysis. For the continuous outcome the values of AVAL0 are shifted to start always from 0. Numeric, but caution NOT to apply numeric operations; will give meaningless results

PADY

primary analysis day, the length of fixed follow-up in days, numeric

---

HCE1, HCE2, HCE3, HCE4 datasets for 1000 patients with different treatment effects.

Description

A simulated dataset containing the ordinal values and other attributes for 1000 patients. HCE4

Usage

HCE4

Format

a data frame with 1000 rows and 6 variables:

ID

subject ID, numbers from 1 to 1000

TRTP

treatment values, A Active or P Placebo, character

GROUP

type of the event, either Time-To-Event (TTE) or Continuous (C), character

GROUPN

type of the event, for the ordering of outcomes in the GROUP variable, numeric

AVALT

the timing of the time-to-event outcomes, numeric

AVAL0

original values for each type of the event, time for TTE outcomes, numeric values for Continuous outcomes, numeric

AVAL

AVAL = AVAL0 + GROUPN, ordinal analysis values for the HCE analysis. For the continuous outcome the values of AVAL0 are shifted to start always from 0. Numeric, but caution NOT to apply numeric operations; will give meaningless results

PADY

primary analysis day, the length of fixed follow-up in days, numeric

---

Calculates patient-level individual win proportions

Description

Calculates patient-level individual win proportions

Usage

IWP(data, AVAL, TRTP, ref)

Arguments

data	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.

Value

the input data frame with a new column of individual win proportions named using the input AVAL value with ⁠_⁠.

References

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

See Also

calcWO(), calcWO.hce(), calcWO.formula().

Examples

KHCE1 <- IWP(data = KHCE, AVAL = "EGFRBL", TRTP = "TRTPN", ref = 2)
WP <- tapply(KHCE1$EGFRBL_, KHCE1$TRTPN, mean)
VAR <- tapply(KHCE1$EGFRBL_, KHCE1$TRTPN, function(x) (length(x)-1)*var(x)/length(x))
N <- tapply(KHCE1$EGFRBL_, KHCE1$TRTPN, length)
SE <- sqrt(sum(VAR/N))
c(WP = WP[[1]], SE = SE)
calcWO(EGFRBL ~ TRTP, data = KHCE)[c("WP", "SE_WP")]

---

Kidney Hierarchical Composite Endpoint dataset.

Description

A dataset with kidney ordinal scale outcomes of 1500 patients in the ADSL dataset.

Usage

KHCE

Format

a data frame with 1500 rows and 11 variables:

ID

patient identifiers, numeric

TRTPN

treatment values, 1 Active or 2 Placebo, numeric

AVAL0

original values for each type of the event, time for TTE outcomes 1-6, numeric values for Continuous outcome 7, numeric

AVAL

AVAL = AVAL0 + GROUPN, ordinal analysis values for the HCE analysis, numeric, but caution NOT to apply numeric operations; will give meaningless results

GROUP

name of the event, character

GROUPN

ordinal outcomes corresponding to PARAMN values, numeric

PARAMCD

coded name of the event, character

PARAMN

severity of the event, outcomes 1-7, where a higher value means a better outcome, character

STRATAN

strata 1-4, higher value means more severe kidney disease, numeric

EGFRBL

Baseline GFR values of patients, numeric

TRTP

treatment values, A Active or P Placebo, character

PADY

primary analysis day (in years), length of the fixed follow-up, numeric

Source

Heerspink HL et al "Development and validation of a new hierarchical composite endpoint for clinical trials of kidney disease progression." Journal of the American Society of Nephrology (2023): https://doi.org/10.1681/ASN.0000000000000243.

Examples

# Adjusted win odds
res <- regWO(x = KHCE, AVAL = "AVAL", TRTP = "TRTP", COVAR = "STRATAN", ref = "P")
res
# Convert the dataset to an adhce object.
## First check that `GROUP` is a factor with the correct ordering of outcomes.
class(KHCE$GROUP) # "factor"
levels(KHCE$GROUP)
dat1 <- as_hce(KHCE)
class(dat1)
calcWO(dat1)
## Re-derive individual patient eGFR slopes using a linear regression model, 
## based on the eGFR measurements in the `ADLB` dataset
dat2 <- KHCE
l <- lapply(
split(ADLB, ADLB$ID), 
function(x) coef(lm(AVAL ~ ADAY, data = x))[2])
new_slopes <- do.call(rbind, l)
new_slopes <- as.data.frame(new_slopes)
names(new_slopes) <- "LINEAR"
new_slopes$ID <- as.numeric(row.names(new_slopes))
dat2 <- merge(KHCE, new_slopes, by = "ID", all.x = TRUE)
dat2$AVAL0[dat2$PARAMCD == "eGFR"] <- dat2$LINEAR[dat2$PARAMCD == "eGFR"]
dat2$AVAL0[is.na(dat2$AVAL0)] <- 0 
dat2 <- as_hce(dat2)
calcWO(dat2)

---

Minimum detectable or WO for alternative hypothesis for given power (no ties)

Description

Minimum detectable or WO for alternative hypothesis for given power (no ties)

Usage

minWO(N, power = 0.5, SD = NULL, k = 0.5, alpha = 0.05, WOnull = 1, digits = 2)

Arguments

N	a numeric vector of sample size values (two arms combined).
power	the given power. The default is 0.5 corresponding to the minimum detectable win odds. A numeric vector of length 1.
SD	assumed standard deviation of the win proportion. By default uses the conservative SD. A numeric vector of length 1.
k	proportion of active group in the overall sample size. Default is 0.5 (balanced randomization). A numeric vector of length 1.
alpha	the significance level for the 2-sided test. Default is 0.05. A numeric vector of length 1.
WOnull	the win odds value of the null hypothesis (default is 1). A numeric vector of length 1.
digits	precision to use for reporting calculated win odds.

Value

a data frame containing the calculated WO with input values.

References

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. https://doi.org/10.1080/10543406.2021.1968893.

See Also

powerWO(), sizeWO() for WO power and sample size calculation.

Examples

minWO(N = 100, digits = 5)
minWO(N = 1200, power = 0.9, k = 0.75)
# Compare the minimum detectable win odds from shifted alternatives to max and ordered alternatives
WO <- minWO(N = 1200, k = 0.5, power = 0.67, digits = 7)$WO
powerWO(N = 1200, WO = WO, k = 0.5, alternative = "shift")
powerWO(N = 1200, WO = WO, k = 0.5, alternative = "ordered")
powerWO(N = 1200, WO = WO, k = 0.5, alternative = "max")

---

A plot method for hce objects

Description

Ordinal dominance graph for hce objects

Usage

## S3 method for class 'hce'
plot(x, fill = FALSE, ...)

Arguments

x	an object of class hce created by as_hce().
fill	logical; if TRUE fill the area above the graph.
...	additional arguments to be passed to base::plot() function.

Value

no return value, called for plotting.

References

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

Examples

d <- as_hce(KHCE)
d$TRTP <- factor(d$TRTP, levels = c("P", "A"))
res <- calcWO(AVAL ~ TRTP, data = d)
# Ordinal Dominance Graph
plot(d, col = 3, type = 'l')
grid()
# Area above the Ordinal Dominance Graph
plot(d, fill = TRUE, col = "#865A4F", type = 'l', 
     lwd = 2, xlab = "Control", ylab = "Active")
legend("bottomright", legend = paste0("WP = ", round(res$WP, 5)))
abline(a = 0, b = 1, lwd = 2, lty = 2, col = "#999999")

---

A print method for hce_results objects

Description

A print method for hce_results objects

Usage

## S3 method for class 'hce_results'
plot(x, ...)

Arguments

x	an object of class hce_results.
...	additional arguments to be passed to base::plot() function.

Value

no return value, called for plotting.

Examples

WO <- minWO(N = 100:1000)
plot(WO)
POW <- powerWO(N = 100:1000, WO = 1.2)
plot(POW, ylim = c(0, 1))

---

Power calculation for the win odds test (no ties)

Description

Power calculation for the win odds test (no ties)

Usage

powerWO(
  N,
  WO,
  SD = NULL,
  k = 0.5,
  alpha = 0.05,
  WOnull = 1,
  alternative = c("shift", "max", "ordered")
)

Arguments

N	a numeric vector of sample size values.
WO	the given win odds for the alternative hypothesis. A numeric vector of length 1.
SD	assumed standard deviation of the win proportion. By default uses the conservative SD. A numeric vector of length 1.
k	proportion of active group in the overall sample size. Default is 0.5 (balanced randomization). A numeric vector of length 1.
alpha	the significance level for the 2-sided test. Default is 0.05. A numeric vector of length 1.
WOnull	the win odds value of the null hypothesis (default is 1). A numeric vector of length 1.
alternative	a character string specifying the class of the alternative hypothesis, must be one of "shift" (default), "max" or "ordered". You can specify just the initial letter.

Details

alternative = "max" refers to the maximum variance of the win proportion across all possible alternatives. The maximum variance equals WP*(1 - WP)/k where the win probability is calculated as ⁠WP = WO/(WO + 1).⁠ alternative = "shift" specifies the variance across alternatives from a shifted family of distributions (Wilcoxon test). The variance formula, as suggested by Noether, is calculated based on the null hypothesis as follows ⁠1/(12*k*(1 - k)).⁠ alternative = "ordered" specifies the variance across alternatives from stochastically ordered distributions which include shifted distributions.

Value

a data frame containing the calculated power with input values.

References

• All formulas were presented in
  
  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. https://doi.org/10.1016/0022-2496(75)90001-2.

• Noether's formula for shifted alternatives
  
  Noether GE (1987) "Sample size determination for some common nonparametric tests." Journal of the American Statistical Association 82.398: 645-7. https://doi.org/10.1080/01621459.1987.10478478.

• For shift alternatives see also
  
  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. https://doi.org/10.1080/10543406.2021.1968893.

See Also

sizeWO(), minWO() for WO sample size or minimum detectable WO calculation.

Examples

# Example 1- Use the default standard deviation
powerWO(N = 1000, WO = 1.2)
powerWO(N = seq(500, 1500, 100), WO = 1.2)
# Example 2 - Use data-driven win odds and standard deviation from the COVID19 dataset
res <- calcWO(x = COVID19, AVAL = "GROUP", TRTP = "TRTP", ref = "Placebo")
print(res)
powerWO(N = 500, WO = res$WO, SD = res$SD_WP)
powerWO(N = 500, WO = res$WO) # power with the default standard deviation for the win proportion.
# Example 3 - Non-balanced 3:1 randomization
powerWO(N = 1000, WO = 1.2, k = 0.75)
# Example 4 - Comparison of different alternatives
powerWO(N = 1000, WO = 1.2, alternative = "m")
powerWO(N = 1000, WO = 1.2, alternative = "s")
powerWO(N = 1000, WO = 1.2, alternative = "o")

---

A print method for hce_results objects

Description

A print method for hce_results objects

Usage

## S3 method for class 'hce_results'
print(x, ...)

Arguments

x	an object of class hce_results.
...	additional arguments to be passed to base::print() function.

Value

no return value, called for printing.

Examples

print(powerWO(N = 1000, WO = 1.2))

---

Proportion of wins/losses/ties given the win odds and the win ratio

Description

Proportion of wins/losses/ties given the win odds and the win ratio

Usage

propWINS(WO, WR, Overall = 1, alpha = NULL, N = NULL)

Arguments

WO	win odds.
WR	win ratio.
Overall	number of comparisons, the sample size of the active treatment multiplied by the sample size of the placebo. The default is 1, hence gives the proportion.
alpha	significance level for the win ratio confidence interval. The default is NULL hence the confidence interval is not produced.
N	the combined sample size of two treatment groups. The default is NULL. If alpha is specified then either N should be specified or Overall > 1. For given Overall, the pooled sample size is calculated as N = 2*sqrt(Overall).

Details

Value

a data frame with a number (or proportion if Overall = 1) of wins/losses/ties. If alpha is specified returns also WR confidence interval.

References

• For the relationship between win odds and win ratio see
  
  Gasparyan SB et al. "Hierarchical Composite Endpoints in COVID-19: The DARE-19 Trial". Case Studies in Innovative Clinical Trials, Chapter 7 (2023): 95-148. Chapman and Hall/CRC. https://doi.org/10.1201/9781003288640-7.

• The win ratio CI uses the standard error presented in
  
  Yu RX, Ganju J. (2022) "Sample size formula for a win ratio endpoint." Statistics in Medicine 41.6: 950-63. https://doi.org/10.1002/sim.9297.

Examples

# Example 1
propWINS(WR = 2, WO = 1.5)
# Example 2 - Back-calculation 
COVID19HCE <- hce(GROUP = COVID19$GROUP, TRTP = COVID19$TRTP)
res <- calcWINS(COVID19HCE)
WR <- res$WR1$WR
WO <- res$WO$WO
Overall <- res$summary$TOTAL
propWINS(WR = WR, WO = WO, Overall = Overall)
## Verify 
res$summary
# Example 3 - Confidence interval
 propWINS(WR = 1.4, WO = 1.3, alpha = 0.05, Overall = 2500)
 propWINS(WR = 2, WO = 1.5, alpha = 0.01, N = 500)

---

A generic function for win odds regression

Description

A generic function for win odds regression

Usage

regWO(x, ...)

Arguments

x	an object used to select a method.
...	further arguments passed to or from other methods.

Value

a data frame containing calculated values.

See Also

regWO.data.frame(), regWO.formula() methods.

---

Win Odds Regression Using a Data Frame

Description

This function performs regression analysis for the win odds using a single numeric covariate.

Usage

## S3 method for class 'data.frame'
regWO(x, AVAL, TRTP, COVAR, ref, alpha = 0.05, WOnull = 1, ...)

Arguments

x	a data frame containing subject-level data.
AVAL	a variable in the data with ordinal analysis values.
TRTP	the treatment variable in the data.
COVAR	a numeric covariate.
ref	the reference treatment group.
alpha	the significance level, with a default value of 0.05.
WOnull	the null hypothesis value for win odds. The default is 1.
...	additional parameters.

Value

a data frame containing the calculated win odds and its confidence interval, including:

• WO_beta adjusted win odds.

• LCL lower confidence limit for adjusted WO.

• UCL upper confidence limit for adjusted WO.

• SE standard error of the adjusted win odds.

• WOnull win odds of the null hypothesis (specified in the WOnull argument).

• alpha two-sided significance level for calculating the confidence interval (specified in the alpha argument).

• Pvalue p-value associated with testing the null hypothesis.

• N total number of patients in the analysis.

• beta adjusted win probability.

• LCL_beta lower confidence limit for adjusted win probability.

• UCL_beta upper confidence limit for adjusted win probability.

• SE_beta standard error for the adjusted win probability.

• SD_beta standard deviation for the adjusted win probability.

• WP (non-adjusted) win probability.

• SE_WP standard error of the non-adjusted win probability.

• SD_WP standard deviation of the non-adjusted win probability.

• WO non-adjusted win odds.

• COVAR_MEAN_DIFF mean difference between two treatment groups of the numeric covariate.

• COVAR_VAR sum of variances of two treatment groups of the numeric covariate.

• COVAR_COV covariance between the response and the numeric covariate.

References

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

See Also

regWO(), regWO.formula().

Examples

# A baseline covariate that is highly correlated with the outcome
set.seed(2023)
dat <- COVID19
n <- nrow(dat)
dat$Severity <- ifelse(dat$GROUP > 4, rnorm(n, 0), rnorm(n, 100))
tapply(dat$Severity, dat$TRTP, mean)
regWO(x = dat, AVAL = "GROUP", TRTP = "TRTP", COVAR = "Severity", ref = "Placebo")
# Without adjustment
calcWO(x = dat, AVAL = "GROUP", TRTP = "TRTP", ref = "Placebo")

---

Win Odds Regression Using a Formula Syntax

Description

This function performs regression analysis for the win odds using a single numeric covariate.

Usage

## S3 method for class 'formula'
regWO(x, data, ...)

Arguments

x	an object of class formula.
data	a data frame.
...	additional parameters.

Value

a data frame containing the calculated win odds and its confidence interval, including:

• WO_beta adjusted win odds.

• LCL lower confidence limit for adjusted WO.

• UCL upper confidence limit for adjusted WO.

• SE standard error of the adjusted win odds.

• WOnull win odds of the null hypothesis (specified in the WOnull argument).

• alpha two-sided significance level for calculating the confidence interval (specified in the alpha argument).

• Pvalue p-value associated with testing the null hypothesis.

• N total number of patients in the analysis.

• beta adjusted win probability.

• LCL_beta lower confidence limit for adjusted win probability.

• UCL_beta upper confidence limit for adjusted win probability.

• SE_beta standard error for the adjusted win probability.

• SD_beta standard deviation for the adjusted win probability.

• WP (non-adjusted) win probability.

• SE_WP standard error of the non-adjusted win probability.

• SD_WP standard deviation of the non-adjusted win probability.

• WO non-adjusted win odds.

• COVAR_MEAN_DIFF mean difference between two treatment groups of the numeric covariate.

• COVAR_VAR sum of variances of two treatment groups of the numeric covariate.

• COVAR_COV covariance between the response and the numeric covariate.

• formula returning the specified formula in the x argument.

• ref showing how the reference group was selected. Can be modifying by specifying the ref argument.

References

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

See Also

regWO(), regWO.data.frame().

Examples

regWO(AVAL ~ TRTP, data = KHCE)
regWO(AVAL ~ TRTP + EGFRBL, data = KHCE)

---

Simulate random numbers from a Weibull distribution with gamma frailty

Description

Simulate random numbers from a Weibull distribution with gamma frailty

Usage

rweibullGF(n, rate, shape = 1, theta = 1)

Arguments

n	number of observations.
rate	rate parameter of the Weibull distribution.
shape	shape parameter of the Weibull distribution, with a default value of 1 (exponential).
theta	variance parameter of the gamma frailty distribution, with a default value of 1.

Details

Let $\gamma$ denote a frailty term following a gamma distribution with $shape = 1 / \theta$ and $scale = \theta$. Then $\gamma$ has mean 1 and variance $\theta$.

Conditional on $\gamma$, the survival function is

$S(t \mid \lambda, \alpha, \gamma) = \exp\left(-\gamma \lambda t^\alpha\right), \qquad \alpha > 0,\ \lambda > 0,$

where $\alpha$ is the shape parameter and $\lambda$ is the rate parameter.

Integrating over the gamma frailty distribution gives the marginal survival function

$S(t \mid \lambda, \alpha, \theta) = \left(1 + \theta \lambda t^\alpha\right)^{-1 / \theta}, \qquad \alpha > 0,\ \lambda > 0,\ \theta > 0.$

This corresponds to the generalized log-logistic distribution (GLL) as implemented in GLL().

As $\theta \to 0$, this reduces to the standard Weibull distribution without frailty, with survival function

$S(t \mid \lambda, \alpha) = \exp\left(-\lambda t^\alpha\right).$

This corresponds to the Weibull distribution in stats::pweibull() with shape = shape and scale = rate^(-1 / shape).

When $\theta = 1$, the survival function becomes

$S(t \mid \lambda, \alpha, 1) = \left(1 + \lambda t^\alpha\right)^{-1},$

which is the survival function of a log-logistic distribution.

Value

a vector of random numbers of length n.

References

Wienke A. "Frailty Models in Survival Analysis." Chapman and Hall/CRC (2010).

See Also

simTTE() for simulation of a two-event time-to-event endpoint from this distribution under the illness-death model.

pGLL() provides the cumulative distribution function of the generalized log-logistic distribution.

Examples

## Example 1: each patient has a sampled time with potentially different
## shape, rate, and theta values.
set.seed(123)
n <- 1000
d <- data.frame(ID = 1:(2*n), TRTP = rep(c("A", "P"), each = n), 
rate = rep(c(0.1, 0.15), each = n), shape = 1.5, theta = 1)
d$time1 <- rweibullGF(n = 2*n, rate = d$rate, shape = d$shape, theta = d$theta)
tapply(d$time1, d$TRTP, summary)
## Example 2: all patients share the same parameter values.
d$time2 <- rweibullGF(n = 2*n, rate = 0.1, theta = 0)
tapply(d$time2, d$TRTP, summary)

---

Simulate an hce object

Description

Simulate an hce object with multiple, possibly correlated (Hougaard copula) Weibull time‑to‑event outcomes and a single continuous endpoint (normal or log‑normal)

Usage

simHCE(
  n,
  n0 = n,
  TTE_A,
  TTE_P,
  CM_A,
  CM_P,
  CSD_A = 1,
  CSD_P = CSD_A,
  fixedfy = 1,
  yeardays = 360,
  pat = 100,
  shape = 1,
  theta = 1,
  logC = FALSE,
  seed = NULL,
  dec = 2,
  all_data = FALSE
)

Arguments

n	sample size in the active treatment group.
n0	sample size in the placebo group.
TTE_A	event rates per year in the active group for the time-to-event outcomes.
TTE_P	event rates per year in the placebo group for the time-to-event outcomes. Should have the same length as TTE_A.
CM_A	mean value for the continuous outcome of the active group.
CM_P	mean value for the continuous outcome of the placebo group.
CSD_A	standard deviation for the continuous outcome of the active group.
CSD_P	standard deviation for the continuous outcome of the placebo group.
fixedfy	length of follow-up in years.
yeardays	number of days in a year.
pat	scale of provided event rates (per pat-years).
shape	shape of the Weibull distribution for time-to-event outcomes. Default is exponential distribution with shape = 1.
theta	Gumbel dependence coefficient of the Weibull distributions for time-to-event outcomes. Default is theta = 1 which assumes independence of time-to-event outcomes. Must be above or equal to 1.
logC	logical, whether to use log-normal distribution for the continuous outcome.
seed	for generating random numbers.
dec	decimal places for the continuous outcome used for rounding. The default is dec = 2.
all_data	logical, whether to return source datasets ADET (an event-time dataset for all time-to-event outcomes per patient) and BDS (a basic data structure for the continuous outcome for all patients).

Value

an object of class hce containing the following columns:

• ID subject identifier.

• TRTP planned treatment group - "A" for active, "P" for Placebo.

• GROUP type of the outcome, either "TTE" for time-to-event outcomes or "C" for continuous. Only one continuous outcome is possible, but no restriction on the number of "TTE" outcomes.

• GROUPN order of outcomes in GROUP, with a higher value signifying a better outcome.

• AVALT the timing of the time-to-event outcomes.

• AVAL0 numeric values of the continuous outcome and the timing of "TTE" outcomes.

• AVAL analysis values derived as AVAL0 + GROUPN. For the continuous outcome the values of AVAL0 are shifted to start always from 0.

• seed the seed of the random sample. If not specified in seed argument will be selected based on system time.

• PADY primary analysis day, the length of fixed follow-up in days calculated as yeardays multiplied by fixedfy.

If all_data = TRUE, the function returns a list containing the hce dataset, along with its source datasets: ADET (an event-time dataset for all time-to-event outcomes per patient) and BDS (a basic data structure for the continuous outcome for all patients).

See Also

hce(), as_hce() for the helper a coerce function to hce objects.

Examples

# Example 1
Rates_A <- c(1.72, 1.74, 0.58, 1.5, 1)
Rates_P <- c(2.47, 2.24, 2.9, 4, 6)
dat <- simHCE(n = 2500, TTE_A = Rates_A, TTE_P = Rates_P,
              CM_A = -3, CM_P = -6, CSD_A = 16, CSD_P = 15, fixedfy = 3)
head(dat)

# Example 2
Rates_A <- 10
Rates_P <- 15
dat <- simHCE(n = 1000, n0 = 500, TTE_A = Rates_A, TTE_P = Rates_P, 
              CM_A = 0.1, CM_P = 0, seed = 5, shape = 0.2, logC = TRUE, dec = 0)
summaryWO(dat)

# Example 3: Comparison of dependent and independent outcomes
Rates_A <- c(10, 20)
Rates_P <- c(20, 20)
dat1 <- simHCE(n = 2500, TTE_A = Rates_A, TTE_P = Rates_P, 
CM_A = -3, CM_P = -6, CSD_A = 15, fixedfy = 3, theta = 1, seed = 1)
dat2 <- simHCE(n = 2500, TTE_A = Rates_A, TTE_P = Rates_P, 
CM_A = -3, CM_P = -6, CSD_A = 15, fixedfy = 3, theta = 1.0001, seed = 1)
calcWO(dat1)
calcWO(dat2)

---

Simulate a kidney disease hce dataset

Description

Simulate a kidney disease hce dataset, capturing eGFR (Estimated Glomerular Filtration Rate) progression over time, along with a competing and dependent terminal event: KFRT (Kidney Failure Replacement Therapy)

Usage

simKHCE(
  n,
  CM_A,
  CM_P = -4,
  n0 = n,
  TTE_A = 1000,
  TTE_P = TTE_A,
  fixedfy = 2,
  Emin = 20,
  Emax = 100,
  sigma = NULL,
  Sigma = 3,
  m = 10,
  theta = -0.4605,
  phi = 0,
  two_meas = c("no", "base", "postbase", "both"),
  df_sigma = Inf
)

Arguments

n	sample size in the active treatment group.
CM_A	annualized eGFR slope in the active group.
CM_P	annualized eGFR slope in the control group.
n0	sample size in the control treatment group.
TTE_A	event rate per year in the active group for KFRT.
TTE_P	event rate per year in the placebo group for KFRT.
fixedfy	length of follow-up in years.
Emin	lower limit of eGFR at baseline.
Emax	upper limit of eGFR at baseline.
sigma	within-patient standard deviation.
Sigma	between-patient standard deviation.
m	number of equidistant visits.
theta	coefficient of dependence of eGFR values and the risk of KFRT.
phi	coefficient of proportionality (between 0 and 1) of the treatment effect. The case of 0 corresponds to the uniform treatment effect.
two_meas	determines whether to use duplicate measurements at baseline and/or at fixedfy. The default is to use a single measurement.
df_sigma	degrees of freedom for the measurement error distribution. The default Inf gives normal measurement errors; must be more than 2.

Details

The default setting is TTE_A = TTE_P because, conditional on eGFR level, the treatment effect does not influence the event rate of KFRT. In this model, the effect of treatment on KFRT operates entirely through its impact on eGFR decline.

Let CM_A and CM_P be denoted by $\beta_A$ and $\beta_P$, respectively. Let TTE_A and TTE_P be denoted by $\lambda_A$ and $\lambda_P$, respectively. Let theta be denoted by $\theta$, phi by $\phi$, sigma by $\sigma$, Sigma by $\Sigma$, and df_sigma by $\nu$.

The parameters TTE_A and theta are chosen so that when GFR is 15, the event rate is 1 per patient per year, and when GFR is 25, the event rate is 0.01 per patient per year. These parameter values are obtained by solving

$\lambda_g \exp(\theta \cdot \mathrm{GFR}) = \mathrm{rate}$

for the group-specific baseline rate $\lambda_g$ and $\theta$. When the observed eGFR is above 30, the event rate is set to a very low value (10e-7), while when the observed eGFR is below or equal to 7, the event rate is set to a very high value (10e5). This ensures that patients with observed low eGFR values always experience KFRT, while those with high eGFR values do not.

By default, the within-patient standard deviation, sigma, is set to NULL. When left as NULL, sigma is calculated as

$\sigma_{ij} = \sqrt{0.67 \cdot \mu_{ij}},$

where $\mu_{ij}$ denotes the predicted eGFR for patient $i$ at visit $j$. This yields time-dependent measurement variability, with lower predicted eGFR values corresponding to lower variability. In the implementation, to prevent the variance from becoming negative or too small, the quantity $0.67 \cdot \mu_{ij}$ is truncated below at 0.1 before taking the square root.

When df_sigma = Inf (the default), measurement errors are normally distributed:

$\varepsilon_{ij} \sim N(0, \sigma_{ij}^2).$

When df_sigma is finite and greater than 2, measurement errors follow a Student t distribution with heavier tails:

$\varepsilon_{ij} = \sigma_{ij}\sqrt{\frac{\nu - 2}{\nu}} T_{\nu},$

where $\nu =$ df_sigma and $T_{\nu}$ is a standard t random variable with $\nu$ degrees of freedom. This scaling preserves the same time-dependent standard deviation defined by sigma, so that

$\mathrm{Var}(\varepsilon_{ij}) = \sigma_{ij}^2.$

Given the overall effect Delta and the placebo progression rate CM_P, a fully uniform (purely additive) treatment effect—meaning the same average effect applies to all patients regardless of baseline progression—is implemented by setting $\phi = 0$ and

$\beta_A = \Delta + \beta_P.$

A fully proportional treatment effect—no additive component, the effect scales with the baseline rate—is implemented by setting

$\beta_A = \beta_P$

and

$\phi = \frac{\Delta}{|\beta_P|}.$

A more relativistic intermediate effect (half additive and half proportional) is obtained by setting

$\phi = \frac{\Delta}{2|\beta_P|}$

and

$\beta_A = \frac{\Delta}{2} + \beta_P.$

The kidney hierarchical composite endpoint is defined in the following order: (1) Kidney Failure Replacement Therapy (KFRT); (2) Sustained eGFR < 15; (3) Sustained 57 percent or more decline in eGFR; (4) Sustained 50 percent or more decline in eGFR; (5) Sustained 40 percent or more decline in eGFR; and (6) Change in eGFR. In practice, because KFRT is frequently initiated when true eGFR is very low, sustained eGFR < 15 events are rarely observed.

If two_meas is not "no", a second measurement is generated using the same latent baseline eGFR and subject-specific slope, but with an independent measurement error draw from the same distribution as above. The two measurements are then averaged at baseline when two_meas = "base", at the final visit when two_meas = "postbase", or at both baseline and the final visit when two_meas = "both". This implementation preserves correlation between the duplicate measurements because they share the same underlying true trajectory.

See Also

simHCE() for a general function of simulating hce datasets.

Examples

# Example - Specifying the most important variables
set.seed(2022)
## The overall treatment effect
Delta <- 0.75
## The placebo progression rate
CM_P <- - 4.5
## Intermediate effect (half additive and half proportional)
delta <- Delta/2
CM_A <- delta + CM_P 
phi <- Delta / (2*abs(CM_P))
L <- simKHCE(n = 1000, CM_A = CM_A, CM_P = CM_P, 
fixedfy = 4, Emin = 25, Emax = 75, phi = phi)
dat <- L$HCE
calcWO(dat)

---

Simulate ordinal variables for two treatment groups using categorization of beta distributions

Description

Simulate ordinal variables for two treatment groups using categorization of beta distributions

Usage

simORD(n, n0 = n, M, alpha1 = 8, beta1 = 7, alpha0 = 5, beta0 = 5)

Arguments

n	sample size in the active treatment group.
n0	sample size in the placebo group.
M	number of ordinal values to be simulated.
alpha1	shape1 parameter for the beta distribution in the active group.
beta1	shape2 parameter for the beta distribution in the active group.
alpha0	shape1 parameter for the beta distribution in the placebo group.
beta0	shape2 parameter for the beta distribution in the placebo group.

Value

a data frame containing the following columns:

• ID subject identifier.

• TRTP planned treatment group - "A" for active, "P" for Placebo.

• GROUPN ordinal values. The number of unique values is specified by the variable M0.

• tau the theoretical win odds.

• theta the theoretical win probability.

See Also

simHCE() for simulating hce objects.

Examples

# Example 1
set.seed(2024)
alpha1 <- 8
beta1 <- 8
alpha0 <- 4
beta0 <- 5
d <- simORD(n = 1500, n0 = 1500, M = 5, alpha1 = alpha1, beta1 = beta1, 
alpha0 = alpha0, beta0 = beta0)
x <- seq(0, 1, 0.01)
plot(x, dbeta(x, shape1 = alpha1, shape2 = beta1), 
type = "l", ylab = "Density of beta distribution", col = 2)
lines(x, dbeta(x, shape1 = alpha0, shape2 = beta0), col = 3, lty = 2)
legend("topleft", lty = c(1, 2), col = c(2, 3), legend = c("Control", "Active"))
D <- hce(GROUP = d$GROUPN, TRTP = d$TRTP)
table(D$TRTP, D$GROUP)
calcWO(D)
# Example 2
set.seed(2024)
d <- simORD(n = 100, n0 = 50, M = 2)
d_hce <- hce(GROUP = d$GROUPN, TRTP = d$TRTP)
calcWO(d_hce)
### compare with the theoretical values of the continuous distributions 
c(tau = unique(d$tau), theta = unique(d$theta))
# Example 2 - Convergence of the win odds to its theoretical value
set.seed(2024)
N <- NULL
size <- c(seq(10, 500, 1))
for(i in size){
  d <- simORD(n = i, M = 2)
  d_hce <- hce(GROUP = d$GROUPN, TRTP = d$TRTP)
  TAU <- calcWO(d_hce)
  D <- data.frame(WO = TAU$WO, n = i, tau = unique(d$tau))
  N <- rbind(N, D)
}
plot(N$n, N$WO, log = "y", ylim = c(0.5, 2), ylab = "Win Odds", xlab = "Sample size", type = "l")
lines(N$n, N$tau, col = "darkgreen", lty = 2, lwd = 2)
abline(h = 1, lty = 4, col = "red")
legend("bottomright", legend = c("Theoretical Win Odds", "Null", "Win Odds Estimate"), 
lty = c(4, 2, 1), col = c("darkgreen", "red", "black"))
title("Convergence of the win odds to its theoretical value")

---

Simulate an adhce dataset with two correlated outcomes (illness - death model)

Description

Simulate an adhce dataset with two correlated outcomes - death and hospitalization - from a heterogeneous population. The correlation between these outcomes arises from population heterogeneity. Models the risk of death following hospitalization as dependent on the timing of the hospitalization, reflecting strong dependence between the times to the first and second events (i.e., event clustering).

Usage

simTTE(
  n,
  n0 = n,
  TTE_A,
  TTE_P = TTE_A,
  shape = 1,
  shape0 = shape,
  fixedfy = 2,
  theta = 1,
  alpha0 = 1,
  alpha = 1,
  rHR = 1,
  m = Inf,
  hce_type = c("mi", "md")
)

Arguments

n	sample size in the active treatment group.
n0	sample size in the placebo treatment group.
TTE_A	event rates in the active group for the time-to-event outcomes; a numeric vector of length two.
TTE_P	event rates in the placebo group for the time-to-event outcomes; a numeric vector of length two.
shape	shape parameter of the Weibull distribution for time-to-event outcomes in the active group. Default is 1 (exponential distribution).
shape0	shape parameter of the Weibull distribution for time-to-event outcomes in the placebo group. Default is 1 (exponential distribution).
fixedfy	length of follow-up.
theta	heterogeneity coefficient for the first event, modeled via a gamma distribution with mean 1; theta controls the variance. When theta = 0, there is no heterogeneity, which implies that death and hospitalization are independent.
alpha0	exponential heterogeneity coefficient for modeling the heterogeneity of risk of death as the first event.
alpha	exponential heterogeneity coefficient for modeling the heterogeneity of risk of death after hospitalization; the heterogeneity of the second event is the inverse of the time of the first event.
rHR	recurrence hazard ratio comparing the active group to the control group for the second event, based on gap time measured from the first event.
m	categorization number used for to discretize time to death and time to hospitalization. Defaults to Inf (no discretization).
hce_type	the type of the hierarchical composite endpoint: use mi for the most-important outcome or md for the move-down approach. This parameter only affects results when m is finite.

Details

The default setting assumes TTE_A = TTE_P. Both TTE_A and TTE_P must be numeric vectors of length two, corresponding to the event rates (Weibull distribution) for the first event of hospitalization and death. The parameters shape and shape0 identify the shape parameters of Weibull distributions for the first event, simulated from a distribution with a cumulative hazard of

$\gamma\cdot rate\cdot t^{shape}$

for hospitalization and

$\gamma^{\alpha_0}\cdot rate\cdot t^{shape}$

for death, where $\gamma$ (gamma) is a patient-specific frailty drawn from a gamma distribution with mean 1 and variance $\theta$, shared between death and hospitalization for a given patient. The parameter $\theta$ (theta) represents population heterogeneity and also induces correlation between death and hospitalization as competing first events. The parameter $\alpha_0$ (alpha0) controls the heterogeneity of time to death through its effect on heterogeneity. Death after hospitalization is simulated from an exponential distribution with a constant hazard that depends on the timing $t_1$ of the first event (hospitalization) as

$\frac{TTE_A[2] + TTE_P[2]}{2}\cdot \left(\frac{t_1}{fixedfy}\right)^{\alpha}\cdot \gamma^{\alpha_0}$

for the placebo arm and

$\frac{TTE_A[2] + TTE_P[2]}{2}\cdot rHR \cdot \left(\frac{t_1}{fixedfy}\right)^{\alpha}\cdot \gamma^{\alpha_0}$

for the active arm where rHR is the recurrence hazard ratio. When $\alpha < 0$, earlier hospitalization (smaller $t_1$) increases the risk of death following hospitalization.

By default, events are simulated in continuous time. When m is specified as a positive numeric value, the event times are discretized into m intervals over the follow-up period.

Value

an object of class adhce.

See Also

simHCE() for a general adhce dataset simulation, and simKHCE() for kidney disease-specific adhce simulation.

Examples

## Example 1 - positive correlation
i <- 1764002323
set.seed(i)
PADY <- 2
D <- simTTE(n = 1000, TTE_A = c(0.1, 0.04), 
TTE_P = c(.15, 0.045), theta = 4, alpha0 = 2, alpha = -1, shape = 2, 
fixedfy = PADY, rHR = 1)
####### Summary of first events by treatment group ########
table(D$EVENT1, D$TRTP)
####### Summary of second events by treatment group ########
table(D$EVENT2, D$TRTP)
######## Calculate win odds #########################
calcWO(D, ref = "P")
## Plot the ordinal dominance graph ######
D$TRTP <- factor(D$TRTP, levels = c("P", "A"))
plot(D, type = "l", col = 2, fill = TRUE)
abline(a = 0, b = 1, lwd = 2, lty = 3, col = "darkgreen")
grid()
################################################################
## Example 2 - Move-down approach (discrete‑time case only)
PADY <- 2
# Continuous-time
set.seed(2)
D <- simTTE(n = 1000, TTE_A = c(0.1, 0.04), 
TTE_P = c(.15, 0.045), theta = 4, alpha0 = 2, alpha = -1, shape = 2, 
fixedfy = PADY, rHR = 1, m = Inf)
summaryWO(D, ref = "P")$summary_by_GROUP
# Discrete-time (more-ties)
D0 <- simTTE(n = 1000, TTE_A = c(0.1, 0.04), 
TTE_P = c(.15, 0.045), theta = 4, alpha0 = 2, alpha = -1, shape = 2, 
fixedfy = PADY, rHR = 1, m = 5)
summaryWO(D0, ref = "P")$summary_by_GROUP
# Discrete-time and move-down approach (less ties on death)
D1 <- simTTE(n = 1000, TTE_A = c(0.1, 0.04), 
TTE_P = c(.15, 0.045), theta = 4, alpha0 = 2, alpha = -1, shape = 2, 
fixedfy = PADY, rHR = 1, m = 5, hce_type = "md")
summaryWO(D1, ref = "P")$summary_by_GROUP

---

Sample size calculation for the win odds test (no ties)

Description

Sample size calculation for the win odds test (no ties)

Usage

sizeWO(
  WO,
  power,
  SD = NULL,
  k = 0.5,
  alpha = 0.05,
  WOnull = 1,
  alternative = c("shift", "max", "ordered")
)

Arguments

WO	a numeric vector of win odds values.
power	the given power. A numeric vector of length 1.
SD	assumed standard deviation of the win proportion. By default uses the conservative SD. A numeric vector of length 1.
k	proportion of active group in the overall sample size. Default is 0.5 (balanced randomization). A numeric vector of length 1.
alpha	the significance level for the 2-sided test. Default is 0.05. A numeric vector of length 1.
WOnull	the win odds value of the null hypothesis (default is 1). A numeric vector of length 1.
alternative	a character string specifying the class of the alternative hypothesis, must be one of "shift" (default), "max" or "ordered". You can specify just the initial letter.

Details

alternative = "max" refers to the maximum variance of the win proportion across all possible alternatives. The maximum variance equals WP*(1 - WP)/k where the win probability is calculated as ⁠WP = WO/(WO + 1).⁠ alternative = "shift" specifies the variance across alternatives from a shifted family of distributions (Wilcoxon test). The variance formula, as suggested by Noether, is calculated based on the null hypothesis as follows ⁠1/(12*k*(1 - k)).⁠ alternative = "ordered" specifies the variance across alternatives from stochastically ordered distributions which include shifted distributions.

Value

a data frame containing the sample size with input values.

References

• All formulas were presented in
  
  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. https://doi.org/10.1016/0022-2496(75)90001-2.

• Noether's formula for shifted alternatives
  
  Noether GE (1987) "Sample size determination for some common nonparametric tests." Journal of the American Statistical Association 82.398: 645-7. https://doi.org/10.1080/01621459.1987.10478478.

• For shift alternatives see also
  
  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. https://doi.org/10.1080/10543406.2021.1968893.

See Also

powerWO(), minWO() for WO power or minimum detectable WO calculation.

Examples

sizeWO(WO = 1.25, power = 0.9)
sizeWO(WO = 1.25, power = 0.9, k = 0.75)
sizeWO(WO = seq(1.05, 1.5, 0.05), power = 0.9)
# Comparison of different alternatives
x <- seq(1.05, 5, 0.05)
N1 <- sizeWO(WO = x, power = 0.9, alternative = "m")$SampleSize
N2 <- sizeWO(WO = x, power = 0.9, alternative = "o")$SampleSize
N3 <- sizeWO(WO = x, power = 0.9, alternative = "s")$SampleSize
d <- data.frame(WO = x, N_m = N1, N_o = N2, N_s = N3)
## Check the power for the ordered alternative
check <- c()
for(i in seq_along(x)){
check[i] <- powerWO(N = d[i, "N_o"], WO = d[i, "WO"], alternative = "o")$power
}
d$power_check_o <- check
print(d)

---

Sample size calculation for the win ratio test (with WR = 1 null hypothesis)

Description

Sample size calculation for the win ratio test (with WR = 1 null hypothesis)

Usage

sizeWR(WR, power, WO = NULL, Pties = NULL, k = 0.5, alpha = 0.05)

Arguments

WR	a numeric vector of win odds values.
power	the given power. A numeric vector of length 1.
WO	win odds. Should be specified only if Pties is not specified. A numeric vector of length 1.
Pties	probability of ties. A numeric vector of length 1.
k	proportion of active group in the overall sample size. Default is 0.5 (balanced randomization). A numeric vector of length 1.
alpha	the significance level for the 2-sided test. Default is 0.05. A numeric vector of length 1.

Value

a data frame containing the sample size with input values.

References

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

See Also

sizeWO() for WO sample size calculation.

Examples

sizeWR(WR = 1.35, Pties = 0.125, power = 0.8)
sizeWR(WR = 1.35, WO = 1.3, power = seq(0.5, 0.9, 0.05))

---

A generic function for stratified win odds with adjustment

Description

A generic function for stratified win odds with adjustment

Usage

stratWO(x, ...)

Arguments

x	an object used to select a method.
...	further arguments passed to or from other methods.

Value

a list containing the stratified results and results by strata.

See Also

stratWO.data.frame() methods.

---

Stratified win odds with adjustment

Description

Stratified win odds with adjustment

Usage

## S3 method for class 'data.frame'
stratWO(
  x,
  AVAL,
  TRTP,
  STRATA,
  ref,
  COVAR = NULL,
  alpha = 0.05,
  WOnull = 1,
  ...
)

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.
STRATA	a character variable for stratification.
ref	the reference treatment group.
COVAR	a numeric covariate.
alpha	the reference treatment group.
WOnull	the null hypothesis. The default is 1.
...	additional parameters.

Value

a data frame containing the following columns:

• WO stratified (or adjusted/stratified) win odds.

• LCL lower confidence limit for adjusted (or adjusted/stratified) WO.

• UCL upper confidence limit for adjusted (or adjusted/stratified) WO.

• SE standard error of the adjusted (or adjusted/stratified) win odds.

• WOnull win odds of the null hypothesis (specified in the WOnull argument).

• alpha two-sided significance level for calculating the confidence interval (specified in the alpha argument).

• Pvalue p-value associated with testing the null hypothesis.

• WP adjusted (or adjusted/stratified) win probability.

• LCL_WP lower confidence limit for adjusted (or adjusted/stratified) WP.

• UCL_WP upper confidence limit for adjusted (or adjusted/stratified) WP.

• SE_WP standard error for the adjusted (or adjusted/stratified) win probability.

• SD_WP standard deviation of the adjusted (or adjusted/stratified) win probability.

• N total number of patients in the analysis.

• Type "STRATIFIED" or "STRATIFIED/ADJUSTED" depending on whether COVAR is specified.

References

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

See Also

stratWO().

Examples

# Stratified win odds
res <- stratWO(x = KHCE, AVAL = "AVAL", TRTP = "TRTP", 
               STRATA = "STRATAN", ref = "P")
res
## Compare with the non-stratified win odds
res0 <- calcWO(AVAL ~ TRTP, data = KHCE,  ref = "P")
res0
## Compare with the win odds in each stratum separately
l <- lapply(split(KHCE, KHCE$STRATAN), calcWO, AVAL = "AVAL", TRTP = "TRTP", ref = "P")
l <- do.call(rbind, l)
l <- l[, c("WO", "LCL", "UCL", "N")]
l$STRATA <- as.numeric(row.names(l))
plot(y = l$WO, x = l$STRATA, ylim = c(0.5, 2.5), log = "y", xlim = c(0, 6),
      ylab = "Win Odds", xlab = "", xaxt = "n")
axis(1, at = 1:6, labels = c(paste0("STR = ", l$STRATA), "Stratified", "Non-stratified"))
arrows(l$STRATA, l$LCL, l$STRATA, 
       l$UCL, angle = 90, code = 3, length = 0.05, col = "darkgreen")
points(5, res$WO)
arrows(5, res$LCL, 5, res$UCL, angle = 90, code = 3, 
       length = 0.05, col = "darkblue")
abline(h = c(1, res$WO), col = "red", lty = 4)
points(6, res0$WO)
arrows(6, res0$LCL, 6, res0$UCL, angle = 90, code = 3, 
       length = 0.05, col = "darkred")
# Stratified and adjusted win odds
res <- stratWO(x = KHCE, AVAL = "AVAL", COVAR = "EGFRBL", 
              TRTP = "TRTP", STRATA = "STRATAN", ref = "P")
res

---

A generic function for summarizing win odds

Description

A generic function for summarizing win odds

Usage

summaryWO(x, ...)

Arguments

x	an object used to select a method.
...	further arguments passed to or from other methods.

Value

a data frame containing calculated values.

See Also

summaryWO.adhce(), summaryWO.hce(), summaryWO.formula(), summaryWO.data.frame() methods.

---