Ch8-cpd.PwrGSD: Create a skeleton compound PwrGSD object
In PwrGSD: Power in a Group Sequential Design
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 <izmirlian@nih.gov>
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 2, 2019, 4:54 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
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, |
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 |
a copy of the indexing dataframe argument for use in
navigating the compound object in subsequent calls to other
functions such as the related |
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 <izmirlian@nih.gov>
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)
|
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.