BuyseTest {BuyseTest}R Documentation

Generalized Pairwise Comparisons (GPC)

Description

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

Usage

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

Arguments

formula

[formula] a symbolic description of the GPC model, typically treatment ~ type1(endpoint1) + type2(endpoint2, threshold2) + strata. See Details, section "Specification of the GPC model".

data

[data.frame] dataset.

scoring.rule

[character] method used to compare the observations of a pair in presence of right censoring (i.e. "timeToEvent" endpoints). Can be "Gehan" or "Peron". See Details, section "Handling missing values".

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 pairs, and 2 performs IPCW. See Details, section "Handling missing values".

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. When used, the uncertainty from the estimates of these survival models is ignored.

method.inference

[character] method used to compute confidence intervals and p-values. Can be "none", "u-statistic", "permutation", "studentized permutation", "bootstrap", "studentized bootstrap". See Details, section "Statistical inference".

n.resampling

[integer] the number of permutations/samples used for computing the confidence intervals and the p.values. See Details, section "Statistical inference".

strata.resampling

[character] the variable on which the permutation/sampling should be stratified. See Details, section "Statistical inference".

hierarchical

[logical] should only the uninformative pairs be analyzed at the lower priority endpoints (hierarchical GPC)? Otherwise all pairs will be compaired for all endpoint (full GPC).

weight

[numeric vector] weights used to cumulating the pairwise scores over the endpoints. Only used when hierarchical=FALSE. Disregarded if the argument formula is defined.

neutral.as.uninf

[logical vector] should paired classified as neutral be re-analyzed using endpoints of lower priority (as it is done for uninformative pairs). See Details, section "Handling missing values".

keep.pairScore

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

seed

[integer, >0] the seed to consider when performing resampling. If NULL no seed is set.

cpus

[integer, >0] the number of CPU to use. Only the permutation test can use parallel computation. See Details, section "Statistical inference".

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.

treatment, endpoint, type, threshold, status, operator, censoring, strata

Alternative to formula for describing the GPC model. See Details, section "Specification of the GPC model".

keep.comparison

Obsolete. Alias for 'keep.pairScore'.

method.tte

Obsolete. Alias for 'scoring.rule'.

Details

Specification of the GPC model:
There are two way to specify the GPC model in BuyseTest. A Formula interface via the argument formula where the response variable should be a binary variable defining the treatment arms. The rest of the formula should indicate the endpoints by order of priority and the strata variables (if any). A Vector interface using the following arguments

The formula interface can be more concise, especially when considering few outcomes, but may be more difficult to apprehend for new users. Note that arguments endpoint, threshold, status, operator, type, and censoring must have the same length.


GPC procedure
The GPC procedure form all pairs of observations, one belonging to the experimental group and the other to the control group, and class them in 4 categories:

With complete data, pairs can be decidely classified as favorable/unfavorable/neutral. In presence of missing values, the GPC procedure uses the scoring rule (argument scoring.rule) and the correction for uninformative pairs (argument correction.uninf) to classify the pairs. The classification may not be 0,1, e.g. the probability that the pair is favorable/unfavorable/neutral with the Peron's scoring rule. To export the classification of each pair set the argument codekeep.pairScore to TRUE and call the function getPairScore on the result of the BuyseTest function.


Handling missing values

Statistical inference
The argument method.inference defines how to approximate the distribution of the GPC estimators and so how standard errors, confidence intervals, and p-values are computed. Available methods are:

Additional arguments for permutation and bootstrap resampling:

Default values
The default of the arguments scoring.rule, correction.uninf, method.inference, n.resampling, hierarchical, neutral.as.uninf, keep.pairScore, strata.resampling, cpus, trace is read from BuyseTest.options().
Additional (hidden) arguments are

Value

An R object of class S4BuyseTest.

Author(s)

Brice Ozenne

References

On the GPC procedure: Marc Buyse (2010). Generalized pairwise comparisons of prioritized endpoints in the two-sample problem. Statistics in Medicine 29:3245-3257
On the win ratio: D. Wang, S. Pocock (2016). A win ratio approach to comparing continuous non-normal outcomes in clinical trials. Pharmaceutical Statistics 15:238-245
On the Peron's scoring rule: 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
On the Gehan's scoring rule: Gehan EA (1965). A generalized two-sample Wilcoxon test for doubly censored data. Biometrika 52(3):650-653
On inference in GPC using the U-statistic theory: I. Bebu, J. M. Lachin (2015). Large sample inference for a win ratio analysis of a composite outcome based on prioritized components. Biostatistics 17(1):178-187

See Also

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

Examples

library(data.table)

#### 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, status = status), data= df.data)

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

## permutation instead of asymptotics to compute the p-value
## Not run: 
    BT <- BuyseTest(treatment ~ TTE(eventtime, status = status), data=df.data,
                    method.inference = "permutation", n.resampling = 1e3)

## End(Not run)

summary(BT, statistic = "netBenefit") ## default
summary(BT, statistic = "winRatio") 

## parallel permutation
## Not run: 
    BT <- BuyseTest(treatment ~ TTE(eventtime, status = status), data=df.data,
                    method.inference = "permutation", n.resampling = 1e3, cpus = 2)
    summary(BT)

## End(Not run)

## method Gehan is much faster but does not optimally handle censored observations
BT <- BuyseTest(treatment ~ TTE(eventtime, status = status), data=df.data,
                scoring.rule = "Gehan", trace = 0)
summary(BT)

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

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

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

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
## scoring.rule = "Gehan"

if(require(survival)){
## Not run: 
  library(survival) ## import veteran
 
  ## scoring.rule = "Gehan"
  BT_Gehan <- BuyseTest(trt ~ celltype + TTE(time,threshold=0,status=status), 
                        data=veteran, scoring.rule="Gehan")
  
  summary_Gehan <- summary(BT_Gehan)
  summary_Gehan <- summary(BT_Gehan, statistic = "winRatio")
  
  ## scoring.rule = "Peron"
  BT_Peron <- BuyseTest(trt ~ celltype + TTE(time,threshold=0,status=status), 
                        data=veteran, scoring.rule="Peron")

  class(BT_Peron)
  summary(BT_Peron)

## End(Not run)
}

[Package BuyseTest version 2.3.0 Index]