getPairScore {BuyseTest} | R Documentation

## Extract the Score of Each Pair

### Description

Extract the score of each pair.

### Usage

    getPairScore(object, endpoint = NULL, strata = NULL,
      rm.withinStrata = TRUE, rm.weight = FALSE, unlist = TRUE,
      trace = 1)

    ## S4 method for signature 'BuyseRes'
    getPairScore(object, endpoint = NULL,
      strata = NULL, rm.withinStrata = TRUE, rm.weight = FALSE,
      unlist = TRUE, trace = 1)

### Arguments

`object` | an R object of class `BuyseRes`, i.e., output of `BuyseTest`
`endpoint` | [integer/character vector] the endpoint for which the scores should be output.
`strata` | [integer/character vector] the strata for which the scores should be output.
`rm.withinStrata` | [logical] should the columns indicating the position of each member of the pair within each treatment group be removed?
`rm.weight` | [logical] should the column weight be remove from the output?
`unlist` | [logical] should the structure of the output be simplified when possible?
`trace` | [logical] should a message be printed to explain what happened when the function returned `NULL`?
`...` | not used. For compatibility with the generic method.

### Details

The maximal output (i.e. with all columns) contains for each endpoint, a data.table with:

- `"strata"`: the name of the strata to which the pair belongs.

- `"index.T"`: the index of the treatment observation in the pair relative to the original dataset.

- `"index.C"`: the index of the control observation in the pair relative to the original dataset.

- `"indexWithinStrata.T"`: the index of the treatment observation in the pair relative to the treatment group and the strata.

- `"indexWithinStrata.C"`: the index of the control observation in the pair relative to the control group and the strata.

- `"favorable"`: the probability that the endpoint is better in the treatment arm vs. in the control arm.

- `"unfavorable"`: the probability that the endpoint is worse in the treatment arm vs. in the control arm.

- `"neutral"`: the probability that the endpoint is no different in the treatment arm vs. in the control arm.

- `"uninformative"`: the weight of the pair that cannot be attributed to favorable/unfavorable/neutral.

- `"weight"`: the residual weight of the pair to be analyzed at the current outcome. Each pair starts with a weight of 1.

- `"favorable.corrected"`: same as `"favorable"` after weighting.

- `"unfavorable.corrected"`: same as `"favorable"` after weighting.

- `"neutral.corrected"`: same as `"favorable"` after weighting.

- `"uninformative.corrected"`: same as `"favorable"` after weighting.

Note that the `.T` and `.C` may change since they correspond of the label of the treatment and control arms. The first weighting consists in multiplying the probability by the residual weight of the pair (i.e. the weight of the pair that was not informative at the previous endpoint). This is always performed. For time to event endpoint an additional weighting may be performed to avoid a possible bias in presence of censoring.

### Examples

    ## run BuyseTest
    data(veteran,package="survival")

    BT.keep <- BuyseTest(trt ~ tte(time, threshold = 20, censoring = "status") + cont(karno),
                         data = veteran, keep.pairScore = TRUE,
                         trace = 0, method.inference = "none")

    ## Extract scores
    pScore <- getPairScore(BT.keep, endpoint = 1)

    ## look at one pair
    pScore[91]

    ## retrive pair in the original dataset
    pVeteran <- veteran[pScore[91,c(index.1,index.2)],]
    pVeteran

    ## the observation from the control group is censored at 97
    ## the observation from the treatment group has an event at 112
    ## since the threshold is 20, and (112-20)<97
    ## we know that the pair is not in favor of the treatment

    ## the formula for probability in favor of the control is
    ## Sc(97)/Sc(112+20)
    ## where Sc(t) is the survival at time t in the control arm.

    ## we first estimate the survival in each arm
    e.KM <- prodlim(Hist(time,status)~trt, data = veteran)

    ## and compute the survival
    iSurv <- predict(e.KM, times =  c(97,112+20), newdata = data.frame(trt = 1))[[1]]

    ## the probability in favor of the control is then
    pUF <- iSurv[2]/iSurv[1]
    pUF
    ## and the complement to one of that is the probability of being neutral
    pN <- 1 - pUF
    pN

    if(require(testthat)){
       testthat::expect_equal(pUF, pScore[91, unfavorable])
       testthat::expect_equal(pN, pScore[91, neutral])
    }

[Package BuyseTest version 1.7 Index]