| Title: | The R WINS Package |
|---|---|
| Description: | Calculate the win statistics (win ratio, net benefit and win odds) for prioritized multiple endpoints, plot the win statistics and win proportions over study time if at least one time-to-event endpoint is analyzed, and simulate datasets with dependent endpoints. The package can handle any type of outcomes (continuous, ordinal, binary, time-to-event) and allow users to perform stratified analysis, inverse probability of censoring weighting (IPCW) and inverse probability of treatment weighting (IPTW) analysis. |
| Authors: | Ying Cui [aut, cre], Bo Huang [aut] |
| Maintainer: | Ying Cui <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 1.4.3 |
| Built: | 2025-02-12 06:14:07 UTC |
| Source: | https://github.com/cran/WINS |
This is a simulated data example with three binary endpoints.
data("data_binary")data("data_binary")
A data frame with 250 observations on the following 4 variables.
idA vector for the patient id.
armA vector for the treatment groups.
Y_1A vector for the outcome of the first endpoint.
Y_2A vector for the outcome of the second endpoint.
Y_3A vector for the outcome of the third endpoint.
data(data_binary) str(data_binary)data(data_binary) str(data_binary)
This is a simulated data example with three continuous endpoints.
data("data_continuous")data("data_continuous")
A data frame with 250 observations on the following 4 variables.
idA vector for the patient id.
armA vector for the treatment groups.
Y_1A vector for the outcome of the first endpoint.
Y_2A vector for the outcome of the second endpoint.
Y_3A vector for the outcome of the third endpoint.
data(data_continuous) str(data_continuous)data(data_continuous) str(data_continuous)
This is a simulated data example with a mixture of two continuous and one time-to-event endpoints. The first endpoint is time-to-event and the second and third endpoints are continuous.
data("data_mix")data("data_mix")
A data frame with 400 observations on the following 5 variables.
idA vector for the patient id.
armA vector for the treatment groups.
Delta_1A vector for the event status of the first endpoint (1=event, 0=censored).
Y_1A vector for the outcome of the first endpoint.
Y_2A vector for the outcome of the second endpoint.
Y_3A vector for the outcome of the third endpoint.
data(data_mix) str(data_mix)data(data_mix) str(data_mix)
This is a simulated data example with a mixture of two continuous and one time-to-event endpoints with three strata. The first endpoint is time-to-event and the second and third endpoints are continuous.
data("data_mix_stratum")data("data_mix_stratum")
A data frame with 400 observations on the following 6 variables.
idA vector for the patient id.
armA vector for the treatment groups.
stratumA vector for the stratum.
Delta_1A vector for the event status of the first endpoint (1=event, 0=censored).
Y_1A vector for the outcome of the first endpoint.
Y_2A vector for the outcome of the second endpoint.
Y_3A vector for the outcome of the third endpoint.
data(data_mix_stratum) str(data_mix_stratum)data(data_mix_stratum) str(data_mix_stratum)
This is a simulated data example with three time-to-event endpoints.
data("data_tte")data("data_tte")
A data frame with 400 observations on the following 7 variables.
idA vector for the patient id.
armA vector for the treatment groups.
Delta_1A vector for the event status of the first endpoint (1=event, 0=censored).
Delta_2A vector for the event status of the second endpoint (1=event, 0=censored).
Delta_3A vector for the event status of the third endpoint (1=event, 0=censored).
Y_1A vector for the outcome of the first endpoint.
Y_2A vector for the outcome of the second endpoint.
Y_3A vector for the outcome of the third endpoint.
data(data_tte) str(data_tte)data(data_tte) str(data_tte)
A plot for the win proportions of the treatment/control group over the study time, for time-to-event endpoints only. The function "win.stat" is called to calculate the win proportions at each time in the plot function.
partition_t.plot(data, Ctime = Inf, arm.name = c(1, 2), priority = c(1, 2), censoring_adjust = "No", Z_t_trt = NULL, Z_t_con = NULL, tau = 0, np_direction = "larger",plotTimeUnit = NULL, trt_group = c("both","trt","con"), win.strategy = NULL, ...)partition_t.plot(data, Ctime = Inf, arm.name = c(1, 2), priority = c(1, 2), censoring_adjust = "No", Z_t_trt = NULL, Z_t_con = NULL, tau = 0, np_direction = "larger",plotTimeUnit = NULL, trt_group = c("both","trt","con"), win.strategy = NULL, ...)
data |
The analysis dataset which contains the following variables:
|
Ctime |
A vector of study times, at which the win proportions are to be plotted. Study time for a subject is the time since the subject is accrued, default is Inf. |
arm.name |
A vector for the two treatments, default to be c(1,2). The first value is for the treatment group, and the second value is for the control group. |
priority |
Importance order (from the most to the least important). For example, given three endpoints with the importance order as Endpoint 3, Endpoint 2, and Endpoint 1, input priority = c(3,2,1). |
censoring_adjust |
The method to adjust censoring for the kernal functions. Possible choices are listed below.
|
Z_t_trt |
A matrix of the covariate history in the treatment group, each row is a (p+2) vector: the first two columns are id, time, the other p columns are the covariates (vector of length p). The baseline covariates are provided as the observed covariates corresponding to time 0. |
Z_t_con |
A matrix of the covariate history in the control group, each row is a (p+2) vector: the first two columns are id, time, the other p columns are the covariates (vector of length p). The baseline covariates are provided as the observed covariates corresponding to time 0. |
tau |
A vector of numerical value for the magnitude of difference to determine win/loss/tie for each endpoint. Tau is applicable for TTE endpoints and continuous endpoints; tau is fixed as 0 for binary endpoints. Default is 0 for all endpoints. |
np_direction |
A vector of character for the direction to define a better result for each endpoint.
|
plotTimeUnit |
The time units, e.g., "days", "months", "years", default as NULL. |
trt_group |
An argument to decide the arms for which the win proportions over time are plotted, possible choices include "both", "trt" and "con". Default is "both", i.e., by default the win proportion over time is plotted both for the treatment group and for the control group. |
win.strategy |
The strategy to determine the win status. Default as NULL. If NULL, the default win strategy funtion "win.strategy.default" is called, see win.strategy.default for more details. Users can also define their own "win.strategy" function. |
... |
Argument passed from user defined functions "win.strategy" if there is any. For instructions on this "win.strategy" function, see win.strategy.default for more details. |
A ggplot2 object.
#### An simulated example with two TTE endpoints. data <- sim.data(n_trt = 200, n_con = 200, n_ep = 2, arm.name = c("A","B"), ep_type = "tte", cdist.rate = 0.5, sim_method = "copula", copula_trt=copula::normalCopula(0.9), margins_trt=c("gamma", "beta"), paramMargins_trt=list(list(shape=2, scale=1),list(shape1=2, shape2=2)), copula_con=copula::normalCopula(0.9), margins_con=c("gamma", "beta"), paramMargins_con=list(list(shape=2, scale=1),list(shape1=2, shape2=2)), max_accrual_time = 5) partition_t.plot(data, Ctime = seq(0,8,0.2), arm.name = c("A","B"), priority = c(1,2), tau = 0, plotTimeUnit = "days", trt_group = "both") #### An simulated example with three TTE endpoints. data <- sim.data(n_trt = 200, n_con = 200, n_ep = 3, arm.name = c("A","B"), ep_type = "tte", cdist.rate = 1, sim_method = "copula", copula_trt=copula::normalCopula(param=c(0.9,0.8,0.95), dim = 3, dispstr = "un"), margins_trt=c("gamma", "beta", "gamma"), paramMargins_trt=list(list(shape=2, scale=2),list(shape1=2, shape2=2),list(shape=2, scale=3)), copula_con=copula::normalCopula(param=c(0.9,0.8,0.95), dim = 3, dispstr = "un"), margins_con=c("gamma", "beta", "gamma"), paramMargins_con=list(list(shape=2, scale=1),list(shape1=2, shape2=1),list(shape=2, scale=2)), max_accrual_time = 5) partition_t.plot(data, Ctime = c(seq(0,8,0.5),seq(8.1,10,0.1)), arm.name = c("A","B"), priority = c(3,2,1), tau = 0, plotTimeUnit = "years", trt_group = "trt")#### An simulated example with two TTE endpoints. data <- sim.data(n_trt = 200, n_con = 200, n_ep = 2, arm.name = c("A","B"), ep_type = "tte", cdist.rate = 0.5, sim_method = "copula", copula_trt=copula::normalCopula(0.9), margins_trt=c("gamma", "beta"), paramMargins_trt=list(list(shape=2, scale=1),list(shape1=2, shape2=2)), copula_con=copula::normalCopula(0.9), margins_con=c("gamma", "beta"), paramMargins_con=list(list(shape=2, scale=1),list(shape1=2, shape2=2)), max_accrual_time = 5) partition_t.plot(data, Ctime = seq(0,8,0.2), arm.name = c("A","B"), priority = c(1,2), tau = 0, plotTimeUnit = "days", trt_group = "both") #### An simulated example with three TTE endpoints. data <- sim.data(n_trt = 200, n_con = 200, n_ep = 3, arm.name = c("A","B"), ep_type = "tte", cdist.rate = 1, sim_method = "copula", copula_trt=copula::normalCopula(param=c(0.9,0.8,0.95), dim = 3, dispstr = "un"), margins_trt=c("gamma", "beta", "gamma"), paramMargins_trt=list(list(shape=2, scale=2),list(shape1=2, shape2=2),list(shape=2, scale=3)), copula_con=copula::normalCopula(param=c(0.9,0.8,0.95), dim = 3, dispstr = "un"), margins_con=c("gamma", "beta", "gamma"), paramMargins_con=list(list(shape=2, scale=1),list(shape1=2, shape2=1),list(shape=2, scale=2)), max_accrual_time = 5) partition_t.plot(data, Ctime = c(seq(0,8,0.5),seq(8.1,10,0.1)), arm.name = c("A","B"), priority = c(3,2,1), tau = 0, plotTimeUnit = "years", trt_group = "trt")
A function to simulate a dataset with dependent endpoints. The time-to-event endpoints generated are assumed to have noninformative censoring.
sim.data(randomseed = 12345, n_trt = 200, n_con = 200, n_ep = 2, n_stratum = 1, arm.name = c(1,2), ep_type, cdist.rate, sim_method = "copula", copula_trt = NULL, margins_trt = NULL, paramMargins_trt = NULL, copula_con = NULL, margins_con = NULL, paramMargins_con = NULL, rate_trt = NULL, rate_con = NULL, max_accrual_time = NULL)sim.data(randomseed = 12345, n_trt = 200, n_con = 200, n_ep = 2, n_stratum = 1, arm.name = c(1,2), ep_type, cdist.rate, sim_method = "copula", copula_trt = NULL, margins_trt = NULL, paramMargins_trt = NULL, copula_con = NULL, margins_con = NULL, paramMargins_con = NULL, rate_trt = NULL, rate_con = NULL, max_accrual_time = NULL)
randomseed |
The random seed. |
n_trt |
The number of individuals in the treatment group. |
n_con |
The number of individuals in the control group. |
n_ep |
The number of endpoints. |
n_stratum |
The number of strata. For the simulated dataset, n_stratum is fixed at 1 assuming homogeneous population. |
arm.name |
A vector for the labels of the two experimental arms, default to be c(1,2). The first label is for the treatment group, and the second label is for the control group. |
ep_type |
A vector for the outcome type for each endpoint. If scalar, the function will treat all the endpoints as the same type. The types of outcome include:
|
cdist.rate |
The censoring time is generated from an exponential distribution. This argument is a vector with the rate of the censoring distribution for each time-to-event endpoint. If scalar, the function will treat all the rate for censoring distribution as the same. |
sim_method |
Method used to generate multivariate dependence. Possible choices include "copula" and "tte_exponential" |
copula_trt |
an object of "copula" for the treatment group. |
margins_trt |
a character vector specifying all the parametric marginal distributions for the treatment group. See details in the R documentation for function "copula::Mvd". |
paramMargins_trt |
a list for which each element is a list (or numeric vectors) of named components, giving the parameter values of the marginal distributions for the treatment group. See details in the R documentation for function "copula::Mvd". |
copula_con |
Same argument as "copula_trt" for the control group. |
margins_con |
Same argument as "margins_trt" for the control group. |
paramMargins_con |
Same argument as "paramMargins_trt" for the control group. |
rate_trt |
A vector of the rate in the treatment group for each time-to-event endpoint following an exponential distribution when "sim_method" is set to be the option "tte_exponential". |
rate_con |
A vector of the rate in the control group for each time-to-event endpoint following an exponential distribution when "sim_method" is set to be the option "tte_exponential". |
max_accrual_time |
if specified, simulate the study entry time for each individual from uniform distribution U(0,max_accrual_time). |
To learn more about "copula", please refer to a discussion on modelling dependence with copulas with the link https://datascienceplus.com/modelling-dependence-with-copulas/. It shows on a high level how copula works, how to use a copula in R using the copula package and then provides a simple example. Moreover, when "sim_method" is set to be the option "tte_exponential", we simulate two endpoints based on the exponential distribution. Dependence between the two simulated endpoints is introduced, as the earlier endpoint takes the min of the two simulated exponential variables.
data |
The analysis dataset which contains the following variables:
|
#### Generate with copula: This example is for three endpoints, noted as Y_1, Y_2, and Y_3, #### with endpoint type as TTE, TTE and continuous. #### For both the treatment group and the control group, the correlation coefficients #### cor(Y_1,Y_2), cor(Y_1,Y_3) and cor(Y_2,Y_3) are 0.9, 0.8 and 0.95, respectively. #### For each treatment group, the marginal distribution for Y_1, Y_2, and Y_3 are Gamma, #### Beta and Student t specified as a vector in "margins_trt"/"margins_con". The parameters #### are specified as a list corresponding to the margianl distributions in "paramMargins_trt" #### or "paramMargins_con". sim.data <- sim.data(n_trt = 150, n_con = 100, n_ep = 3, arm.name = c("A","B"), ep_type = c("tte","tte","continuous"), cdist.rate = 0.5, sim_method = "copula", copula_trt=copula::normalCopula(param=c(0.9,0.8,0.95), dim = 3, dispstr = "un"), margins_trt=c("gamma", "beta", "t"), paramMargins_trt=list(list(shape=2, scale=1),list(shape1=2, shape2=2),list(df=5)), copula_con=copula::normalCopula(param=c(0.9,0.8,0.95), dim = 3, dispstr = "un"), margins_con=c("gamma", "beta", "t"), paramMargins_con=list(list(shape=1, scale=1),list(shape1=1, shape2=2),list(df=2)), max_accrual_time = 5) win_stat <- win.stat(data = sim.data, ep_type = c("tte","tte","continuous"), arm.name = c("A","B"), priority = c(1,2,3)) #### Generate two TTE endpoints with the more important TTE endpoint expected to occur later #### with exponential distribution. sim.data2 <- sim.data(n_trt = 150, n_con = 100, n_ep = 2, arm.name = c("A","B"), ep_type = c("tte","tte"), cdist.rate = 0.5, sim_method = "tte_exponential", rate_trt = c(0.2,0.25),rate_con = c(0.4,0.5), max_accrual_time = 5) win_stat2 <- win.stat(data = sim.data2, ep_type = c("tte","tte"), arm.name = c("A","B"), priority = c(1,2))#### Generate with copula: This example is for three endpoints, noted as Y_1, Y_2, and Y_3, #### with endpoint type as TTE, TTE and continuous. #### For both the treatment group and the control group, the correlation coefficients #### cor(Y_1,Y_2), cor(Y_1,Y_3) and cor(Y_2,Y_3) are 0.9, 0.8 and 0.95, respectively. #### For each treatment group, the marginal distribution for Y_1, Y_2, and Y_3 are Gamma, #### Beta and Student t specified as a vector in "margins_trt"/"margins_con". The parameters #### are specified as a list corresponding to the margianl distributions in "paramMargins_trt" #### or "paramMargins_con". sim.data <- sim.data(n_trt = 150, n_con = 100, n_ep = 3, arm.name = c("A","B"), ep_type = c("tte","tte","continuous"), cdist.rate = 0.5, sim_method = "copula", copula_trt=copula::normalCopula(param=c(0.9,0.8,0.95), dim = 3, dispstr = "un"), margins_trt=c("gamma", "beta", "t"), paramMargins_trt=list(list(shape=2, scale=1),list(shape1=2, shape2=2),list(df=5)), copula_con=copula::normalCopula(param=c(0.9,0.8,0.95), dim = 3, dispstr = "un"), margins_con=c("gamma", "beta", "t"), paramMargins_con=list(list(shape=1, scale=1),list(shape1=1, shape2=2),list(df=2)), max_accrual_time = 5) win_stat <- win.stat(data = sim.data, ep_type = c("tte","tte","continuous"), arm.name = c("A","B"), priority = c(1,2,3)) #### Generate two TTE endpoints with the more important TTE endpoint expected to occur later #### with exponential distribution. sim.data2 <- sim.data(n_trt = 150, n_con = 100, n_ep = 2, arm.name = c("A","B"), ep_type = c("tte","tte"), cdist.rate = 0.5, sim_method = "tte_exponential", rate_trt = c(0.2,0.25),rate_con = c(0.4,0.5), max_accrual_time = 5) win_stat2 <- win.stat(data = sim.data2, ep_type = c("tte","tte"), arm.name = c("A","B"), priority = c(1,2))
Plot the win statistics as a function of the study time for time-to-event endpoints only. The function "win.stat" is called to calculate the win statistics at each time in the plot function.
stat_t.plot(data, Ctime = Inf, arm.name = c(1,2), priority = c(1,2), statistic = c("WR","NB","WO"), Z_t_trt = NULL, Z_t_con = NULL, tau = 0,np_direction = "larger", stratum.weight = c("unstratified","MH-type","wt.stratum1","wt.stratum2","equal"), censoring_adjust = c("No","IPCW","CovIPCW"), win.strategy = NULL, plotTimeUnit = NULL, plot_CI = FALSE, alpha = 0.05, ...)stat_t.plot(data, Ctime = Inf, arm.name = c(1,2), priority = c(1,2), statistic = c("WR","NB","WO"), Z_t_trt = NULL, Z_t_con = NULL, tau = 0,np_direction = "larger", stratum.weight = c("unstratified","MH-type","wt.stratum1","wt.stratum2","equal"), censoring_adjust = c("No","IPCW","CovIPCW"), win.strategy = NULL, plotTimeUnit = NULL, plot_CI = FALSE, alpha = 0.05, ...)
data |
The analysis dataset which contains the following variables:
|
Ctime |
A vector of study times, at which the win proportions are to be plotted. Study time for a subject is the time since the subject is accrued, default as Inf. |
arm.name |
A vector for the labels of the two experimental arms, default to be c(1,2). The first label is for the treatment group, and the second label is for the control group. |
priority |
Importance order (from the most to the least important). For example, given three endpoints with the importance order as Endpoint 3, Endpoint 2, and Endpoint 1, input priority = c(3,2,1). |
statistic |
The win statistic to be plotted.
|
Z_t_trt |
A matrix for the covariate history, each row is a (p+2) vector for one record of each subject in the treatment group. The first two columns are subject id, time, the other columns are the covariates (vector of length p). The baseline covariates are provided as the observed covariates corresponding to time 0. |
Z_t_con |
A matrix for the covariate history, each row is a (p+2) vector for one record of each subject in the control group. The first two columns are subject id, time, the other columns are the covariates (vector of length p). The baseline covariates are provided as the observed covariates corresponding to time 0. |
tau |
A vector of numerical value for the magnitude of difference to determine win/loss/tie for each endpoint. If tau is input as scalar, the function treat the taus for TTE endpoints and continuous endpoints to be the same and taus for binary endpoints as 0. Default as 0 for all endpoints. |
np_direction |
A vector of character for the direction to define a better result for each endpoint.
|
stratum.weight |
The weighting method for each stratum. Default is "unstratified" for unstratified analysis. A stratified analysis is performed if other weight option is specified. Other possible choices for this argument are listed below.
|
censoring_adjust |
The method to adjust censoring for the kernal functions. Possible choices are listed below.
|
win.strategy |
The strategy to determine the win status. Default as NULL. If NULL, the default win strategy funtion "win.strategy.default" is called, see win.strategy.default for more details. Users can also define their own "win.strategy" function. |
plotTimeUnit |
The time units, e.g., "days", "months", "years", default as NULL. |
plot_CI |
If TRUE, plot the pointwise confidence interval, default as FALSE. |
alpha |
The significance level, default to be 0.05. |
... |
Argument passed from user defined functions "win.strategy" if there is any. For instructions on this "win.strategy" function, see win.strategy.default for more details. |
A ggplot2 object.
#### An simulated example with two TTE endpoints. data <- sim.data(n_trt = 200, n_con = 200, n_ep = 2, arm.name = c("A","B"), ep_type = "tte", cdist.rate = 0.5, sim_method = "copula", copula_trt=copula::normalCopula(0.9), margins_trt=c("gamma", "beta"), paramMargins_trt=list(list(shape=2, scale=1),list(shape1=2, shape2=2)), copula_con=copula::normalCopula(0.9), margins_con=c("gamma", "beta"), paramMargins_con=list(list(shape=2, scale=1),list(shape1=2, shape2=2)), max_accrual_time = 5) stat_t.plot(data, arm.name = c("A","B"),priority = c(1,2), Ctime = seq(2,12,1),plotTimeUnit = "years",statistic = "WR", tau = 0, stratum.weight = "unstratified", censoring_adjust = "No", plot_CI = TRUE) #### An simulated example with three TTE endpoints. data <- sim.data(n_trt = 200, n_con = 200, n_ep = 3, arm.name = c("A","B"), ep_type = "tte", cdist.rate = 0.5, sim_method = "copula", copula_trt=copula::normalCopula(param=c(0.9,0.8,0.95), dim = 3, dispstr = "un"), margins_trt=c("gamma", "beta", "t"), paramMargins_trt=list(list(shape=2, scale=1),list(shape1=2, shape2=2),list(df=5)), copula_con=copula::normalCopula(param=c(0.9,0.8,0.95), dim = 3, dispstr = "un"), margins_con=c("gamma", "beta", "t"), paramMargins_con=list(list(shape=1, scale=1),list(shape1=2, shape2=3),list(df=5)), max_accrual_time = 5) stat_t.plot(data, arm.name = c("A","B"),priority = c(3,2,1), Ctime = seq(1,8,0.5),plotTimeUnit = "years", statistic = "WR", tau = 0, plot_CI = TRUE)#### An simulated example with two TTE endpoints. data <- sim.data(n_trt = 200, n_con = 200, n_ep = 2, arm.name = c("A","B"), ep_type = "tte", cdist.rate = 0.5, sim_method = "copula", copula_trt=copula::normalCopula(0.9), margins_trt=c("gamma", "beta"), paramMargins_trt=list(list(shape=2, scale=1),list(shape1=2, shape2=2)), copula_con=copula::normalCopula(0.9), margins_con=c("gamma", "beta"), paramMargins_con=list(list(shape=2, scale=1),list(shape1=2, shape2=2)), max_accrual_time = 5) stat_t.plot(data, arm.name = c("A","B"),priority = c(1,2), Ctime = seq(2,12,1),plotTimeUnit = "years",statistic = "WR", tau = 0, stratum.weight = "unstratified", censoring_adjust = "No", plot_CI = TRUE) #### An simulated example with three TTE endpoints. data <- sim.data(n_trt = 200, n_con = 200, n_ep = 3, arm.name = c("A","B"), ep_type = "tte", cdist.rate = 0.5, sim_method = "copula", copula_trt=copula::normalCopula(param=c(0.9,0.8,0.95), dim = 3, dispstr = "un"), margins_trt=c("gamma", "beta", "t"), paramMargins_trt=list(list(shape=2, scale=1),list(shape1=2, shape2=2),list(df=5)), copula_con=copula::normalCopula(param=c(0.9,0.8,0.95), dim = 3, dispstr = "un"), margins_con=c("gamma", "beta", "t"), paramMargins_con=list(list(shape=1, scale=1),list(shape1=2, shape2=3),list(df=5)), max_accrual_time = 5) stat_t.plot(data, arm.name = c("A","B"),priority = c(3,2,1), Ctime = seq(1,8,0.5),plotTimeUnit = "years", statistic = "WR", tau = 0, plot_CI = TRUE)
Calculate the win statistics for a mixture type of outcomes including time-to-event outcome, continuous outcome and binary outcome.
win.stat(data, ep_type, Z_t_trt = NULL, Z_t_con = NULL, iptw.weight = NULL, arm.name = c(1,2),priority = c(1,2), alpha = 0.05, digit = 5, tau = 0, np_direction = "larger", win.strategy = NULL,pvalue = c("one-sided","two-sided"), stratum.weight = c("unstratified","MH-type","wt.stratum1","wt.stratum2","equal"), method = c("unadjusted","ipcw","covipcw","iptw","iptw_ipcw","iptw_covipcw"), summary.print = TRUE, ...)win.stat(data, ep_type, Z_t_trt = NULL, Z_t_con = NULL, iptw.weight = NULL, arm.name = c(1,2),priority = c(1,2), alpha = 0.05, digit = 5, tau = 0, np_direction = "larger", win.strategy = NULL,pvalue = c("one-sided","two-sided"), stratum.weight = c("unstratified","MH-type","wt.stratum1","wt.stratum2","equal"), method = c("unadjusted","ipcw","covipcw","iptw","iptw_ipcw","iptw_covipcw"), summary.print = TRUE, ...)
data |
The analysis dataset which contains the following variables:
|
ep_type |
A vector for the outcome type for each endpoint. If scalar, the function will treat all the endpoints as the same type. The types of outcome include:
|
Z_t_trt |
A matrix of the covariate history in the treatment group, each row is a (p+2) vector: the first two columns are subject id, time, the other p columns are the covariates (vector of length p). The baseline covariates are provided as the observed covariates corresponding to time 0. |
Z_t_con |
A matrix of the covariate history in the control group, each row is a (p+2) vector: the first two columns are subject id, time, the other p columns are the covariates (vector of length p). The baseline covariates are provided as the observed covariates corresponding to time 0. |
iptw.weight |
The weight assigned to each individual if method = "iptw". |
arm.name |
A vector for the labels of the two experimental arms, default to be c(1,2). The first label is for the treatment group, and the second label is for the control group. |
priority |
Importance order (from the most to the least important). For example, given three endpoints with the importance order as Endpoint 3, Endpoint 2, and Endpoint 1, input priority = c(3,2,1). |
alpha |
The significance level, default to be 0.05. |
digit |
The number of digits for the output, default to be 5. |
tau |
A vector of numerical value for the magnitude of difference to determine win/loss/tie for each endpoint. Tau is applicable for TTE endpoints and continuous endpoints; tau is fixed as 0 for binary endpoints. Default is 0 for all endpoints. |
np_direction |
A vector of character for the direction to define a better result for each endpoint.
|
win.strategy |
The strategy to determine the win status. Default as NULL. If NULL, the default win strategy funtion "win.strategy.default" is called, see win.strategy.default for more details. Users can also define their own "win.strategy" function. |
pvalue |
The p-value type: "one-sided" or "two-sided". |
stratum.weight |
The weighting method for each stratum. Default is "unstratified" for unstratified analysis. A stratified analysis is performed if other weight option is specified. Other possible choices for this argument are listed below.
|
method |
The method to adjust the kernal functions. Possible choices are listed below.
Other methods may be added in future versions. |
summary.print |
If TRUE, print out a summary of the estimation and inference result for the win statistics; If FALSE, return a list that summarizes the results. Default as TRUE. |
... |
Argument passed from user defined functions "win.strategy" if there is any. For instructions on this "win.strategy" function, see win.strategy.default for more details. |
The arguments of user defined "win.strategy" function must at least include the argument "trt_con" and "priority". "priority" is defined the same as stated in the main function "win.stat". The intermediate analysis dataset "trt_con" for the patient pairs (i.e., unmatched pairs, see Pocock et al., 2012) contains the following variables. Each row represents a pair.
A vector for the stratum number of the unmatched pairs.
A vector for the subject id of the individuals from the treatment group within each unmatched pair.
A vector for the subject id of the individuals from the control group within each unmatched pair.
A vector for the event status of the j-th endpoint (1=event, 0=censored) for the individuals from the treatment group in each unmatched pair. If the outcome type for the endpoint is continuous/binary, then the event status is 1 for all.
A vector for the event status of the j-th endpoint (1=event, 0=censored) for the individuals from the control group in each unmatched pair. If the outcome type for the endpoint is continuous/binary, then the event status is 1 for all.
A vector for the outcome of the j-th endpoint for the individuals from the treatment group in each unmatched pair. For a time-to-event outcome, it would be a vector of observed time-to-event observations.
A vector for the outcome of the j-th endpoint for the individuals from the control group in each unmatched pair. For a time-to-event outcome, it would be a vector of observed time-to-event observations.
Win_prop |
The win proportion of the treatment and the control group. |
Win_statistic |
The win statistics including:
|
z_statistic |
The z-scores including:
|
pvalue |
The p-value for the test statistics including:
|
summary_ep |
The win count and win proportion of the treatment and the control group for each endpoint |
Bebu, I. and Lachin, J.M., 2016. Large sample inference for a win ratio analysis of a composite outcome based on prioritized components. Biostatistics.
Buyse, M., 2010. Generalized pairwise comparisons of prioritized outcomes in the two-sample problem. Statistics in medicine.
Cui, Y., Dong, G., Kuan, P.F. and Huang, B., 2022. Evidence synthesis analysis with prioritized benefit outcomes in oncology clinical trials. Journal of Biopharmaceutical Statistics.
Dong, G., Li, D., Ballerstedt, S. and Vandemeulebroecke, M., 2016. A generalized analytic solution to the win ratio to analyze a composite endpoint considering the clinical importance order among components. Pharmaceutical statistics.
Dong, G., Qiu, J., Wang, D. and Vandemeulebroecke, M., 2018. The stratified win ratio. Journal of biopharmaceutical statistics.
Dong, G., Huang, B., Chang, Y.W., Seifu, Y., Song, J. and Hoaglin, D.C., 2020. The win ratio: Impact of censoring and follow-up time and use with nonproportional hazards. Pharmaceutical statistics.
Dong, G., Mao, L., Huang, B., Gamalo-Siebers, M., Wang, J., Yu, G. and Hoaglin, D.C., 2020. The inverse-probability-of-censoring weighting (IPCW) adjusted win ratio statistic: an unbiased estimator in the presence of independent censoring. Journal of biopharmaceutical statistics.
Dong, G., Hoaglin, DC., Qiu, J., Matsouaka, RA., Chang, Y., Wang, J., Vandemeulebroecke, M., 2020. The win ratio: on interpretation and handling of ties. Statistics in Biopharmaceutical Research.
Dong, G., Huang, B., Wang, D., Verbeeck, J., Wang, J. and Hoaglin, D.C., 2021. Adjusting win statistics for dependent censoring. Pharmaceutical Statistics.
Dong, G., Huang, B., Verbeeck, J., Cui, Y., Song, J., Gamalo-Siebers, M., Wang, D., Hoaglin, D.C., Seifu, Y., Mutze, T. and Kolassa, J., 2022. Win statistics (win ratio, win odds, and net benefit) can complement one another to show the strength of the treatment effect on time-to-event outcomes. Pharmaceutical Statistics.
Dong, G., Hoaglin, D.C., Huang, B., Cui, Y., Wang, D., Cheng, Y. and Gamalo-Siebers, M., 2023. The stratified win statistics (win ratio, win odds, and net benefit). Pharmaceutical Statistics.
Finkelstein, D.M. and Schoenfeld, D.A., 1999. Combining mortality and longitudinal measures in clinical trials. Statistics in medicine.
Finkelstein, D.M. and Schoenfeld, D.A., 2019. Graphing the Win Ratio and its components over time. Statistics in medicine.
Luo, X., Tian, H., Mohanty, S. and Tsai, W.Y., 2015. An alternative approach to confidence interval estimation for the win ratio statistic. Biometrics.
Pocock, S.J., Ariti, C.A., Collier, T.J. and Wang, D., 2012. The win ratio: a new approach to the analysis of composite endpoints in clinical trials based on clinical priorities. European heart journal.
Wang D, Pocock S., 2016. A win ratio approach to comparing continuous non-normal outcomes in clinical trials. Pharmaceutical Statistics.
Wang, D., Zheng S., Cui, Y., He, N., Chen, T., Huang, B., 2023. Adjusted win ratio using inverse probability treatment weighting (IPTW) propensity score analysis. Journal of Biopharmaceutical Statistics.
Zheng S, Wang D, Qiu J, Chen T, Gamalo M., 2023. A win ratio approach for comparing crossing survival curves in clinical trials. Journal of Biopharmaceutical Statistics.
#### An example with time-to-event outcome. head(data_tte) head(Z_t_trt) ### CovIPCW adjustment for dependent censoring res_tte_covipcw <- win.stat(data = data_tte, ep_type = "tte", arm.name = c("A","B"), tau = 0.1, Z_t_trt = Z_t_trt, Z_t_con = Z_t_con, priority = c(1:3), alpha = 0.05, digit = 3, method = "covipcw", stratum.weight = "unstratified", pvalue = "two-sided") #### An example with continuous outcome. head(data_continuous) res_continuous <- win.stat(data = data_continuous, ep_type = "continuous", arm.name = c("A","B"), tau = 0, priority = c(1:3), alpha=0.05, digit = 3, stratum.weight = "unstratified", pvalue = "two-sided") #### An example with binary outcome. head(data_binary) res_binary <- win.stat(data = data_binary, ep_type = "binary", arm.name = c("A","B"), priority = c(1:3), alpha=0.05, digit = 3, stratum.weight = "unstratified", pvalue = "two-sided")#### An example with time-to-event outcome. head(data_tte) head(Z_t_trt) ### CovIPCW adjustment for dependent censoring res_tte_covipcw <- win.stat(data = data_tte, ep_type = "tte", arm.name = c("A","B"), tau = 0.1, Z_t_trt = Z_t_trt, Z_t_con = Z_t_con, priority = c(1:3), alpha = 0.05, digit = 3, method = "covipcw", stratum.weight = "unstratified", pvalue = "two-sided") #### An example with continuous outcome. head(data_continuous) res_continuous <- win.stat(data = data_continuous, ep_type = "continuous", arm.name = c("A","B"), tau = 0, priority = c(1:3), alpha=0.05, digit = 3, stratum.weight = "unstratified", pvalue = "two-sided") #### An example with binary outcome. head(data_binary) res_binary <- win.stat(data = data_binary, ep_type = "binary", arm.name = c("A","B"), priority = c(1:3), alpha=0.05, digit = 3, stratum.weight = "unstratified", pvalue = "two-sided")
An intermediate function to determine the win status for each pair based on the default win strategy. Specifically, one compares each subject in the treatment group with every subject in the control group to determine the win status.
win.strategy.default(trt_con, priority, tau, np_direction)win.strategy.default(trt_con, priority, tau, np_direction)
trt_con |
Given N_t subjects in the treatment group and N_c subjects in the control group, there are N_t*N_c pairs, each row represents a pair. The analysis dataset trt_con contains the following variables:
|
priority |
Importance order (from the most to the least important). For example, given three endpoints with the importance order as Endpoint 3, Endpoint 2, and Endpoint 1, input priority = c(3,2,1). |
tau |
A vector of numerical value for the magnitude of difference to determine win/loss/tie for each endpoint. Tau is applicable for TTE endpoints and continuous endpoints; tau is fixed as 0 for binary endpoints. Default is 0 for all endpoints. |
np_direction |
A vector of character for the direction to define a better result for each endpoint.
|
Users can define their own win strategy function and input the function with the argument "win.strategy" in the "win.stat" function.
win_status |
A data frame for the win status of each pair for each endpoint. |
This is a simulated data example for the covariate history in the control group.
data("data_tte")data("data_tte")
A data frame with 796 observations on the following 4 variables.
idA vector for the patient id.
timeA vector for the observed time of the covariate.
Z1A vector for the observed value of the first covariate.
Z2A vector for the observed value of the second covariate.
data(data_tte) str(Z_t_con)data(data_tte) str(Z_t_con)
This is a simulated data example for the covariate history in the treatment group.
data("data_tte")data("data_tte")
A data frame with 796 observations on the following 4 variables.
idA vector for the patient id.
timeA vector for the observed time of the covariate.
Z1A vector for the observed value of the first covariate.
Z2A vector for the observed value of the second covariate.
data(data_tte) str(Z_t_trt)data(data_tte) str(Z_t_trt)