Ch8-cpd.PwrGSD: Create a skeleton compound PwrGSD object

Description Usage Arguments Value Note Author(s) See Also Examples

Description

Given a user defined indexing dataframe as its only argument, creates a skeleton compound PwrGSD object having a component Elements, a list of PwrGSD objects, of length equal to the number of rows in the indexing dataframe

Usage

1
cpd.PwrGSD(descr)

Arguments

descr

A dataframe of a number of rows equal to the length of the resulting list, Elements, of PwrGSD objects. The user defines the mapping between rows of descr and components of Elements and uses it to set up a loop over scenarios. There are several S3 classes and methods for example plot.cpd.PwrGSD, which exploit this mapping between characteristics of a run and the rows of desr for subsetting and constructing conditioned plots. See the example below.

Value

An object of class cpd.PwrGSD containing elements:

date

the POSIX date that the object was created–its quite useful

Elements

a list of length equal to the number of rows of descr which will later contain objects of class PwrGSD

descr

a copy of the indexing dataframe argument for use in navigating the compound object in subsequent calls to other functions such as the related plot method, and the subset extractor, Elements

Note

A cpd.PwrGSD object essentially a list of PwrGSD objects that a user may set up in order to investigate the space of possible trial scenarios, test statistics, and boundary construction options. One could store a list of results without appealing at all to these internal indexing capabilities. The advantage of setting up a cpd.PwrGSD object is the nice summarization functionality provided, for example the plot method for the cpd.PwrGSD class.

The key ingredient to (i) the construction of the empty object, (ii) and summarizing the results in tabular or plotted form via its manipulation in subsequent function calls, is the indexing dataset, descr (for description). The correspondence between rows of descr and elements in the list of PwrGSD objects is purposely left very loose. In the example outlined below, the user creates a “base case” call to PwrGSD and then decides which quantities in this “base case” call to vary in order to navigate the space of possible trial scenarios, monitoring statistics and boundary construction methods. Next, for each one of these settings being varied, a variable with levels that determine each possible setting is created. The dataset descr is created with one line corresponding to each combination of the selection variables so created. In order to ensure that there is 1-1 correspondence between the order of the rows in descr and the order in the list Elements of PwrGSD objects, the user carries out the computation in a loop over rows of descr in which the values of the selection variables in each given row of descr are used to create the corresponding component of Elements via an update the “base case” call.

Author(s)

Grant Izmirlian <[email protected]>

See Also

Elements, plot.cpd.PwrGSD and Power

Examples

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
## don't worry--these examples are guaranteed to work,
## its just inconvenient for the package checker
## Not run: 
  library(PwrGSD)

## In order to set up a compound object of class `cpd.PwrGSD'
## we first construct a base case: a two arm trial randomized in just
## under eight years with a maximum of 20 years of follow-up.
## We compute power at a specific alternative, `rhaz', under
## an interim analysis plan with roughly one annual analysis, some
## crossover between intervention and control arms, with Efficacy
## and futility boundaries constructed via the Lan-Demets procedure
## with O'Brien-Fleming spending on the hybrid scale. Investigate
## the behavior of three weighted log-rank statistics.

test.example <-
  PwrGSD(EfficacyBoundary = LanDemets(alpha = 0.05, spending = ObrienFleming),
         FutilityBoundary = LanDemets(alpha = 0.1, spending = ObrienFleming),
	 RR.Futility = 0.82, sided="1<",method="A",accru =7.73, accrat =9818.65,
         tlook =c(7.14, 8.14, 9.14, 10.14, 10.64, 11.15, 12.14, 13.14,
                  14.14, 15.14, 16.14, 17.14, 18.14, 19.14, 20.14),
         tcut0 =0:19, h0 =c(rep(3.73e-04, 2), rep(7.45e-04, 3),
                            rep(1.49e-03, 15)),
         tcut1 =0:19, rhaz =c(1, 0.9125, 0.8688, 0.7814, 0.6941,
                              0.6943, 0.6072, 0.5202, 0.4332, 0.6520,
                              0.6524, 0.6527, 0.6530, 0.6534, 0.6537,
                              0.6541, 0.6544, 0.6547, 0.6551, 0.6554),
         tcutc0 =0:19, hc0 =c(rep(1.05e-02, 2), rep(2.09e-02, 3),
                              rep(4.19e-02, 15)),
         tcutc1 =0:19, hc1 =c(rep(1.05e-02, 2), rep(2.09e-02, 3),
                              rep(4.19e-02, 15)),
         tcutd0B =c(0, 13), hd0B =c(0.04777, 0),
         tcutd1B =0:6, hd1B =c(0.1109, 0.1381, 0.1485, 0.1637, 0.2446,
                               0.2497, 0),
         noncompliance =crossover, gradual =TRUE,
         WtFun =c("FH", "SFH", "Ramp"),
         ppar =c(0, 1, 0, 1, 10, 10))

## we will construct a variety of alternate hypotheses relative to the
## base case specified above

  rhaz <- 
    c(1, 0.9125, 0.8688, 0.7814, 0.6941, 0.6943, 0.6072, 0.5202, 0.4332,
    0.652, 0.6524, 0.6527, 0.653, 0.6534, 0.6537, 0.6541, 0.6544,
    0.6547, 0.6551, 0.6554)

  max.effect <- 0.80 + 0.05*(0:8)
  n.me <- length(max.effect)

## we will also vary extent of censoring relative to the base case
## specified above

  hc <- c(rep(0.0105, 2), rep(0.0209, 3), rep(0.0419, 15))

  cens.amt <- 0.75 + 0.25*(0:2)
  n.ca <- length(cens.amt)

## we may also wish to compare the Lan-Demets/O'Brien-Fleming efficacy
## boundary with a Lan-Demets/linear spending boundary

  Eff.bound.choice <- 1:2
  ebc.nms <- c("LanDemets(alpha=0.05, spending=ObrienFleming)",
               "LanDemets(alpha=0.05, spending=Pow(1))")
  n.ec <- length(Eff.bound.choice)

## The following line creates the indexing dataframe, `descr', with one
## line for each possible combination of the selection variables we've
## created. 


  descr <- as.data.frame(
              cbind(Eff.bound.choice=rep(Eff.bound.choice, each=n.ca*n.me),
                    cens.amt=rep(rep(cens.amt, each=n.me), n.ec),
                    max.effect=rep(max.effect, n.ec*n.ca)))

  descr$Eff.bound.choice <- ebc.nms[descr$Eff.bound.choice]

## Now descr contains one row for each combination of the levels of
## the user defined selection variables, `Eff.bound.choice',
## `max.effect' and `cens.amt'. Keep in mind that the names and number
## of these variables is arbitrary. Next we create a skeleton
## `cpd.PwrGSD' object with a call to the function `cpd.PwrGSD' with
## argument `descr' 

  test.example.set <- cpd.PwrGSD(descr)

## Now, the newly created object, of class `cpd.PwrGSD', contains
## an element `descr', a component `date', the date created 
## and a component `Elements', an empty list of length equal
## to the number of rows in `descr'.  Next we do the computation in
## a loop over the rows of `descr'.

  n.descr <- nrow(descr)

  for(k in 1:n.descr){

    ## First, we copy the original call to the current call,
    ## `Elements[[k]]$call'

    test.example.set$Elements[[k]]$call <- test.example$call

    ## Use the efficacy boundary choice in the kth row of `descr'
    ## to set the efficacy boundary choice in the current call

    test.example.set$Elements[[k]]$call$EfficacyBoundary <- 
    parse(text=as.character(descr[k,"Eff.bound.choice"]))[[1]]

    ## Derive the `rhaz' defined by the selection variable "max.effect"
    ## in the kth row of `descr' and use this to set the `rhaz'
    ## components of the current call

    test.example.set$Elements[[k]]$call$rhaz <-
                            exp(descr[k,"max.effect"] * log(rhaz))

    ## Derive the censoring components from the selection variable
    ## "cens.amt" in the kth row of `descr' and place that result
    ## into the current call
    
    test.example.set$Elements[[k]]$call$hc0 <-
    test.example.set$Elements[[k]]$call$hc1 <- descr[k, "cens.amt"] * hc

    ## Now the current call corresponds exactly to the selection
    ## variable values in row `k' of `descr'. The computation is
    ## done by calling `update'

    test.example.set$Elements[[k]] <- update(test.example.set$Elements[[k]])
    cat(k/n.descr, "\r")
  }

  ## We can create a new `cpd.PwrGSD' object by subsetting on
  ## the selection variables in `descr':

  Elements(test.example.set, 
           subset=(substring(Eff.bound.choice, 32, 34)=="Obr" &
                            max.effect >= 1))


  ## or we can plot the results -- see the help under `plot.cpd.PwrGSD'

  plot(test.example.set, formula = ~ max.effect | stat * cens.amt,
       subset=(substring(Eff.bound.choice, 32, 34)=="Obr"))

  plot(test.example.set, formula = ~ max.effect | stat * cens.amt,
       subset=(substring(Eff.bound.choice, 32, 34)=="Pow"))

  ## Notice the appearance of the selection variable `stat' which was
  ## not defined in the dataset `descr'. 

  ## Recall that each single "PwrGSD" object can contain results
  ## for a list of test statistics, as in the example shown here where
  ## we have results on three statistics per component of `Elements'.
  ## For this reason the variable `stat' can be also be referenced in
  ## the `subset' or `formula' arguments of calls to this `plot' method,
  ## and in the `subset' argument of the function `Power' shown below.

  ## The function `Power' is used to convert the `cpd.PwrGSD' object
  ## into  a dataframe, stacked by rows of `descr' and by `stat'
  ## (there are three statistics being profiled per each component of
  ## `Elements'), for generating tables or performing other 
  ## computations.

  Power(test.example.set,
        subset=(substring(Eff.bound.choice, 32, 34)=="Pow" & stat %in% c(1,3)))


## End(Not run)

PwrGSD documentation built on May 31, 2017, 2:32 a.m.