hce package introLoad the package hce and check the version
library(hce)
packageVersion("hce")
#> [1] '0.5.0'For citing the package run citation("hce") (Samvel B. Gasparyan 2022).
List the functions and the datasets in the package
ls("package:hce")
#> [1] "COVID19" "COVID19b" "HCE1" "HCE2" "HCE3"
#> [6] "HCE4" "calcWINS" "calcWO" "hce" "minWO"
#> [11] "new_hce" "powerWO" "propWINS" "regWO" "simHCE"
#> [16] "sizeWO" "sizeWR" "summaryWO" "validate_hce"In brief, the package contains the following:
HCE1 - HCE4 that contain two
treatment groups and analysis values AVAL of an
hierarchical composite endpoint. The datasets COVID19,
COVID19b of COVID-19 ordinal scale outcomes (Beigel et al. 2020).hce objects -
hce(), new_hce(), validate_hce(), simHCE() (see Samvel B. Gasparyan et al. (2022)).calcWO(), summaryWO()
(see Samvel B. Gasparyan, Folkvaljon, et al.
(2021), Samvel B. Gasparyan, Kowalewski,
et al. (2021)).gamma) and their confidence intervals calculation function
- calcWINS(). Backward calculation of number of wins,
losses, and ties given the win odds and win ratio using the
propWINS() function.regWP() function.powerWO(), sizeWO(), minWO() (see Samvel B. Gasparyan, Kowalewski, et al. (2021),
Samvel B. Gasparyan, Kowalewski, and Koch
(2022)). Win ratio sample size calculation formula
sizeWR() (Yu and Ganju
2022).hce_results objects,
generated by functions powerWO(), sizeWO(), minWO().hce objectshce() functionThe main objects in the package are called hce objects
which are data frames with a specific structure, matching the design of
hierarchical composite endpoints (HCE), which are complex
endpoints combining into a composite events of different clinical
importance using a hierarchy for prioritizing in the analysis the
clinically most important event of a patient. These endpoints are
implemented in clinical trials in different therapeutic areas. See for
example, Samvel B. Gasparyan et al. (2022)
for an implementation in COVID-19 setting and some practical
considerations for constructing hierarchical composite endpoints.
HCE are ordinal endpoints that can be thought of as having ‘greater’, ‘less’ or ‘equal’ defined for them but without having the definition by how much greater or less. In this sense the ordinal outcomes can be represented as numeric vectors as long as numeric operations (e.g. sum or division) are not performed on them.
hce objects can be constructed using the helper function
hce() which has three arguments
args("hce")
#> function (GROUP = character(), TRTP = character(), AVAL0 = 0,
#> ORD = sort(unique(GROUP)))
#> NULLWe see that the required arguments are EVENT, which
specifies clinically the most important event of a patient to be
included in the analysis and TRTP which specifies the
(planned) treatment group of a patient (exactly two treatment groups
should be present). Note that
hce structure assumes that only one event per
patient is present for the analysis, meaning that the resulting
hce object created by the hce() function is a
patient-level dataset. The function hce() does not do a
selection of the clinically most important event of the patient but
requires it to be already done when calling it.
argument TRTP should have exactly two
levels.
Consider the following example of ordinal outcomes ‘I’, ‘II’, and ‘III’:
set.seed(2022)
n <- 100
dat <- hce(GROUP = rep(x = c("I", "II", "III"), each = 100),
TRTP = sample(x = c("Active", "Control"), size = n*3, replace = TRUE))
class(dat)
#> [1] "hce" "data.frame"This dataset has the appropriate structure of hce
objects, but its class inherits from an object of class
data.frame. Meaning that all functions available for data
frame can be applied to hce objects, for example the
function head()
head(dat)
#> TRTP GROUP GROUPN AVAL AVAL0 ord
#> 1 Control I 0 0 0 1
#> 2 Active I 0 0 0 1
#> 3 Control I 0 0 0 1
#> 4 Active I 0 0 0 1
#> 5 Active I 0 0 0 1
#> 6 Control I 0 0 0 1We see that the dataset has a very specific structure. The column
GROUPN shows how the function hce() generated
the order of given events (it uses usual alphabetic order for the unique
values in GROUP column to determine the clinical importance
of events)
unique(dat[, c("GROUP", "GROUPN")])
#> GROUP GROUPN
#> 1 I 0
#> 101 II 1
#> 201 III 2In the class hce the higher values for the ordering mean
clinically less important event. For example, death which is the most
important event always should get the lowest ordinal value. If there is
a need to specify the order of outcomes, then the argument
ORD can be used
set.seed(2022)
n <- 100
dat <- hce(GROUP = rep(x = c("I", "II", "III"), each = 100),
TRTP = sample(x = c("A", "P"), size = n*3, replace = TRUE), ORD = c("III", "II", "I"))
unique(dat[, c("GROUP", "GROUPN")])
#> GROUP GROUPN
#> 1 I 2
#> 101 II 1
#> 201 III 0This means that the clinically most important event is ‘III’ instead
of ‘I’. The argument AVAL0 is meant to help in the cases
where we want to introduce sub-ordering within each GROUP
category. For example, if two events in the group ‘I’ can be compared
based on other parameters, then AVAL0 argument can be
specified to take that into account.
Below we use the built-in data frame HCE1 to construct
an hce object. Before specifying the order of events it is
a good idea to check what are the unique events included in the
GROUP column
data(HCE1)
unique(HCE1$GROUP)
#> [1] "C" "TTE4" "TTE1" "TTE2" "TTE3"Therefore, we can construct the following hce object
HCE <- hce(GROUP = HCE1$GROUP, TRTP = HCE1$TRTP, AVAL0 = HCE1$AVAL0,
ORD = c("TTE1", "TTE2", "TTE3", "TTE4", "C"))
class(HCE)
#> [1] "hce" "data.frame"
head(HCE)
#> TRTP GROUP GROUPN AVAL AVAL0 ord
#> 1 A C 40000 39997.79 -2.21 10000
#> 2 P C 40000 40017.06 17.06 10000
#> 3 A TTE4 30000 30966.00 966.00 10000
#> 4 P TTE4 30000 30352.00 352.00 10000
#> 5 A C 40000 39987.55 -12.45 10000
#> 6 P C 40000 40044.62 44.62 10000hce object from a data frameConsider the dataset HCE1 which is part of the package
hce
data(HCE1, package = "hce")
class(HCE1)
#> [1] "data.frame"
head(HCE1)
#> SUBJID GROUP GROUPN AVAL0 AVAL TRTP
#> 1 1 C 40000 -2.21 39997.79 A
#> 2 2 C 40000 17.06 40017.06 P
#> 3 3 TTE4 30000 966.00 30966.00 A
#> 4 4 TTE4 30000 352.00 30352.00 P
#> 5 5 C 40000 -12.45 39987.55 A
#> 6 6 C 40000 44.62 40044.62 PThis dataset has the appropriate structure of hce
objects, but its class is data.frame. The constructor
function new_hce() can be used to construct an
hce object. The constructor function will call the
validator function validate_hce() to check whether the
structure of the given data frame is corresponding to an
hce object structure, and if yes, then it will convert the
data frame to an object of class hce.
dat2 <- new_hce(HCE1)
class(dat2)
#> [1] "hce" "data.frame"hce objects using simHCE()To simulate values from a hierarchical composite endpoint we use the
function simHCE(), which has the following arguments
args("simHCE")
#> function (n, n0 = n, TTE_A, TTE_P, CM_A, CM_P, CSD_A = 1, CSD_P = 1,
#> fixedfy = 1, yeardays = 360, pat = 100, ord = 10000, seed = NULL)
#> NULLThe vector arguments TTE_A and TTE_P
show the event rates per year for time-to-event outcomes in the active
and control groups, respectively. The function assumes constant event
rates (uses exponential survival function for simulations). These two
vectors should have the same length and their length shows the number of
time-to-event outcomes, which can be arbitrary.
By default, the event rates are presented per 100 patient-years
(pat = 100), which can be changed using the argument
pat. The function simulates event times in days, hence
yeardays = 360 argument can be used to change the number of
days in a year (for example, 365 or 365.25 can be used).
The function simulates events during a fixed-follow-up time only,
hence argument fixedfy can be used to change the length of
the follow-up (in years).
Rates_A <- c(1.72, 1.74, 0.58, 1.5, 1)
Rates_P <- c(2.47, 2.24, 2.9, 4, 6)
dat1 <- simHCE(n = 2500, n0 = 1500, TTE_A = Rates_A,
TTE_P = Rates_P,
CM_A = -3, CM_P = -6,
CSD_A = 16, CSD_P = 15,
fixedfy = 3)class(dat1)
#> [1] "hce" "data.frame"
head(dat1)
#> ID TRTP GROUP GROUPN AVALT AVAL0 AVAL ord seed TTEfixed
#> 1 1 A C 60000 1080 -28.91 59971.09 10000 1673873651 1080
#> 2 2 A C 60000 1080 7.68 60007.68 10000 1673873651 1080
#> 3 3 A C 60000 1080 -17.64 59982.36 10000 1673873651 1080
#> 4 4 A C 60000 1080 -13.05 59986.95 10000 1673873651 1080
#> 5 5 A C 60000 1080 -18.66 59981.34 10000 1673873651 1080
#> 6 6 A C 60000 1080 -4.00 59996.00 10000 1673873651 1080hce objectsAs we see, it creates an object of type hce which
inherits from the built-in class data.frame. We can check
all implemented methods for this new class as follows:
methods(class = "hce")
#> [1] calcWINS calcWO summaryWO
#> see '?methods' for accessing help and source codeThe function calcWO() calculates the win odds and its
confidence interval, while summaryWO() provides more
detailed calculation of win odds, providing also the number of wins,
losses, and ties by GROUP categories.
HCE <- hce(GROUP = HCE3$GROUP, TRTP = HCE3$TRTP,
ORD = c("TTE1", "TTE2", "TTE3", "TTE4", "C"))
calcWO(HCE)
#> WO LCL UCL SE WOnull alpha Pvalue WP
#> 1 1.333635 1.160574 1.532502 0.07091636 1 0.05 3.852522e-05 0.571484
#> SE_WP SD_WP N
#> 1 0.01736671 0.5491836 1000
summaryWO(HCE)
#> $summary
#> TRTP WIN LOSS TIE TOTAL WR WO
#> 1 A 110655 74913 64432 250000 1.4771135 1.3336352
#> 2 P 74913 110655 64432 250000 0.6769961 0.7498303
#>
#> $summary_by_GROUP
#> TRTP GROUP WIN LOSS TIE TOTAL
#> 1 A C 87780 0 45220 133000
#> 2 P C 39780 0 45220 85000
#> 3 A TTE1 0 36540 5460 42000
#> 4 P TTE1 0 27040 5460 32500
#> 5 A TTE2 3835 18703 6962 29500
#> 6 P TTE2 9912 42126 6962 59000
#> 7 A TTE3 10980 14400 4620 30000
#> 8 P TTE3 11011 22869 4620 38500
#> 9 A TTE4 8060 5270 2170 15500
#> 10 P TTE4 14210 18620 2170 35000
#>
#> $WO
#> WO SE WP SE_WP
#> 1 1.333635 0.07091636 0.571484 0.01736671