BuyseTest (version 1.6)

BuyseTest: Generalized Pairwise Comparisons (GPC)

Description

Performs Generalized Pairwise Comparisons for binary, continuous and time-to-event endpoints.

Usage

BuyseTest(formula, data, method.tte = NULL, correction.uninf = NULL,
  model.tte = NULL, method.inference = NULL, n.resampling = NULL,
  neutral.as.uninf = NULL, keep.pairScore = NULL, treatment = NULL,
  endpoint = NULL, type = NULL, threshold = NULL, censoring = NULL,
  operator = NULL, strata = NULL, alternative = NULL, seed = 10,
  cpus = NULL, trace = NULL, keep.comparison)

Arguments

formula

[formula] a symbolic description of the model to be fitted. The response variable should be a binary variable defining the treatment arms. The rest of the formula should indicate the strata variables (if any) and the endpoints by order of priority.

data

[data.frame] dataset.

method.tte

[character] defines the method used to compare the observations of a pair in presence of right censoring (i.e. "timeToEvent" endpoints). Can be "Gehan" or "Peron". "Gehan" only scores pairs that can be decidedly classified as favorable, unfavorable, or neutral. "Peron" uses the empirical survival curves of each group to also score the pairs that cannot be decidedly classified (see Peron et al. for more details). Default value read from BuyseTest.options().

correction.uninf

[integer] should a correction be applied to remove the bias due to the presence of uninformative pairs? 0 indicates no correction, 1 impute the average score of the informative pair, and 2 performs inverse probability of censoring weights. Default value read from BuyseTest.options().

model.tte

[list] optional survival models relative to each time to each time to event endpoint. Models must prodlim objects and stratified on the treatment and strata variable.

method.inference

[character] should the asymptotic theory ("asymptotic"), or a permutation test ("permutation" or "stratified permutation"), or bootstrap resampling ("bootstrap" or "stratified boostrap") be used to compute p-values and confidence intervals.

n.resampling

[integer] the number of simulations used for computing the confidence interval and the p.values. See details. Default value read from BuyseTest.options().

neutral.as.uninf

[logical] should paired classified as neutral be re-analyzed using endpoints of lower priority. Default value read from BuyseTest.options().

keep.pairScore

[logical] should the result of each pairwise comparison be kept?

treatment

[character] the name of the treatment variable identifying the control and the experimental group. Disregarded if the argument formula is defined.

endpoint

[character vector] the name of the endpoint variable(s). Disregarded if the argument formula is defined.

type

[character vector] the type of each endpoint: "binary", "continuous" or "timeToEvent".

threshold

[numeric vector] critical values used to compare the pairs (threshold of minimal important difference). There must be one threshold for each endpoint variable. Disregarded if the argument formula is defined.

censoring

[character vector] the name of the binary variable(s) indicating whether the endpoint was observed or censored. There must be one threshold for each endpoint variable. Must value NA when the endpoint is not a time to event. Disregarded if the argument formula is defined.

operator

[character vector] the sign defining a favorable endpoint: ">0" indicates that higher values are favorable while "<0" indicates the opposite. Disregarded if the argument formula is defined.

strata

[numeric vector] if not NULL, the GPC will be applied within each group of patient defined by the strata variable(s). Disregarded if the argument formula is defined.

alternative

[character] the alternative hypothesis. Must be one of "two.sided", "greater" or "less". Default value read from BuyseTest.options().

seed

[integer, >0] the seed to consider for the permutation test. If NULL no seed is set.

cpus

[integer, >0] the number of CPU to use. Only the permutation test can use parallel computation. Default value read from BuyseTest.options().

trace

[integer] should the execution of the function be traced ? 0 remains silent and 1-3 correspond to a more and more verbose output in the console. Default value read from BuyseTest.options().

keep.comparison

Obsolete. Alias for 'keep.pairScore'.

Value

An R object of class '>BuyseRes.

Details

treatment: The variable corresponding to treatment in data must have only two levels (e.g. 0 and 1). endpoint, threshold, censoring, operator, and type: they must have the same length. threshold must be NA for binary endpoints and positive for continuous or time to event endpoints. censoring must be NA for binary or continuous endpoints and indicate a variable in data for time to event endpoints. Short forms for endpoint type are "bin" (binary endpoint), "cont" (continuous endpoint), \ code"TTE" (time-to-event endpoint). operator: when the operator is set to "<0" the corresponding column in the dataset is multiplied by -1.

n.resampling: The number of permutation replications must be specified to enable the computation of the confidence intervals and the p.value. A large number of permutations (e.g. n.resampling=10000) are needed to obtain accurate CI and p.value. See (Buyse et al., 2010) for more details.

cpus parallelization: Argument cpus can be set to "all" to use all available cpus. The detection of the number of cpus relies on the detectCores function from the parallel package .

Dealing with neutral or uninformative pairs: Neutral pairs correspond to pairs for which the difference between the endpoint of the control observation and the endpoint of the treatment observation is (in absolute value) below the threshold. When threshold=0, neutral pairs correspond to pairs with equal endpoint. Uninformative pairs correspond to pairs for which the censoring prevent from classifying them into favorable, unfavorable or neutral. Neutral or uninformative pairs for an endpoint with priority l are, when available, analyzed on the endpoint with priority l-1.

method.tte: the method.tte="Peron" is recommended in presence of right censored observations since it gives a more efficient estimator than method.tte="Gehan".

method.inference: the method.inference="asymptotic" estimate the distribution of the net benefit or win ratio statistics based on the asymptotic theory of the U-statistics (see formula 2.2 in Bebu et al. 2016). Its current implementation is not valid in small sample or when using method.tte="Peron", or correction.uninf=1, or correction.uninf=2.

correction.uninf: in presence of uninformative pairs, the proportion of favorable, unfavorable, or neutral pairs is underestimated. Inverse probability of censoring weights (correction.uninf=2) is only recommanded when the analysis is stopped after the first endpoint with uninformative pairs. Imputing the average score of the informative pairs (correction.uninf=1) gives equivalent results at the first endpoint but better behaves at latter endpoints. Note that both corrections will convert the whole proportion of uninformative pairs of a given endpoint into favorable, unfavorable, or neutral pairs.

References

J. Peron, M. Buyse, B. Ozenne, L. Roche and P. Roy (2018). An extension of generalized pairwise comparisons for prioritized outcomes in the presence of censoring. Statistical Methods in Medical Research 27: 1230-1239 D. Wang, S. Pocock (2016). A win ratio approach to comparing continuous non-normal outcomes in clinical trials. Pharmaceutical Statistics 15:238-245 I. Bebu, J. M. Lachin. Large sample inference for a win ratio analysis of a composite outcome based on prioritized components. Biostatistics 17(1):178-187 Marc Buyse (2010). Generalized pairwise comparisons of prioritized endpoints in the two-sample problem. Statistics in Medicine 29:3245-3257 Efron B (1967). The two sample problem with censored data. Proceedings of the Fifth Berkeley Symposium on Mathematical Statistics and Probability 4:831-583 Gehan EA (1965). A generalized two-sample Wilcoxon test for doubly censored data. Biometrika 52(3):650-653

See Also

BuyseRes-summary for a summary of the results of generalized pairwise comparison. BuyseRes-class for a presentation of the BuyseRes object. constStrata to create a strata variable from several clinical variables.

Examples

# NOT RUN {
# reset the default value of the number of permuation sample
BuyseTest.options(method.inference = "none") # no permutation test

#### simulate some data ####
set.seed(10)
df.data <- simBuyseTest(1e2, n.strata = 2)

                                       # display 
if(require(prodlim)){
   resKM_tempo <- prodlim(Hist(eventtime,status)~Treatment, data = df.data)
   plot(resKM_tempo)
}

#### one time to event endpoint ####
BT <- BuyseTest(Treatment ~ TTE(eventtime, censoring = status), data= df.data)

summary(BT) # net benefit
summary(BT, percentage = FALSE)  
summary(BT, statistic = "winRatio") # win Ratio

## bootstrap to compute the CI
# }
# NOT RUN {
    BT <- BuyseTest(Treatment ~ TTE(eventtime, censoring = status), data=df.data,
                    method.inference = "permutation", n.resampling = 1e3)
# }
# NOT RUN {
summary(BT, statistic = "netBenefit") ## default
summary(BT, statistic = "winRatio") 

## parallel boostrap
# }
# NOT RUN {
    BT <- BuyseTest(Treatment ~ TTE(eventtime, censoring = status), data=df.data,
                    method.inference = "permutation", n.resampling = 1e3, cpus = 2)
    summary(BT)
# }
# NOT RUN {
## method Gehan is much faster but does not optimally handle censored observations
BT <- BuyseTest(Treatment ~ TTE(eventtime, censoring = status), data=df.data,
                method.tte = "Gehan", trace = 0)
summary(BT)

#### one time to event endpoint: only differences in survival over 1 unit ####
BT <- BuyseTest(Treatment ~ TTE(eventtime, threshold = 1, censoring = status), data=df.data)
summary(BT)

#### one time to event endpoint with a strata variable
BT <- BuyseTest(Treatment ~ strata + TTE(eventtime, censoring = status), data=df.data)
summary(BT)

#### several endpoints with a strata variable
f <- Treatment ~ strata + T(eventtime, 1, status) + B(toxicity) 
f <- update(f, 
            ~. + T(eventtime, 0.5, status) + C(score, 1) + T(eventtime, 0.25, status))

BT <- BuyseTest(f, data=df.data)
summary(BT)

#### real example : Veteran dataset of the survival package ####
#### Only one endpoint. Type = Time-to-event. Thresold = 0. Stratfication by histological subtype
#### method.tte = "Gehan"

if(require(survival)){
# }
# NOT RUN {
  data(veteran,package="survival")
 
  ## method.tte = "Gehan"
  BT_Gehan <- BuyseTest(trt ~ celltype + TTE(time,threshold=0,censoring=status), 
                        data=veteran, method.tte="Gehan",
                        method.inference = "permutation", n.resampling = 1e3)
  
  summary_Gehan <- summary(BT_Gehan)
  summary_Gehan <- summary(BT_Gehan, statistic = "winRatio")
  
  ## method.tte = "Peron"
  BT_Peron <- BuyseTest(trt ~ celltype + TTE(time,threshold=0,censoring=status), 
                        data=veteran, method.tte="Peron",
                        method.inference = "permutation", n.resampling = 1e3)

  class(BT_Peron)
  summary(BT_Peron)
# }
# NOT RUN {
}
# }