plot.gsDesign: Plots for group sequential designs

Description

The plot() function has been extended to work with objects returned by gsDesign() and gsProbability(). For objects of type gsDesign, seven types of plots are provided: z-values at boundaries (default), power, approximate treatment effects at boundaries, conditional power at boundaries, spending functions, expected sample size, and B-values at boundaries. For objects of type gsProbability plots are available for z-values at boundaries, power (default), approximate treatment effects at boundaries, conditional power, expected sample size and B-values at boundaries.

The intent is that many standard plot() parameters will function as expected; exceptions to this rule exist. In particular, main, xlab, ylab, lty, col, lwd, type, pch, cex have been tested and work for most values of plottype; one exception is that type="l" cannot be overridden when plottype=2. Default values for labels depend on plottype and the class of x.

Note that there is some special behavior for values plotted and returned for power and expected sample size (ASN) plots for a gsDesign object. A call to x<-gsDesign() produces power and expected sample size for only two theta values: 0 and x$delta. The call plot(x, plottype="Power") (or plot(x,plottype="ASN") for a gsDesign object produces power (expected sample size) curves and returns a gsDesign object with theta values determined as follows. If theta is non-null on input, the input value(s) are used. Otherwise, for a gsProbability object, the theta values from that object are used. For a gsDesign object where theta is input as NULL (the default), theta=seq(0,2,.05)*x$delta) is used. For a gsDesign object, the x-axis values are rescaled to theta/x$delta and the label for the x-axis $theta / delta$. For a gsProbability object, the values of theta are plotted and are labeled as $theta$. See examples below.

Approximate treatment effects at boundaries are computed dividing the Z-values at the boundaries by the square root of n.I at that analysis.

Spending functions are plotted for a continuous set of values from 0 to 1. This option should not be used if a boundary is used or a pointwise spending function is used (sfu or sfl="WT", "OF", "Pocock" or sfPoints).

Conditional power is computed using the function gsBoundCP(). The default input for this routine is theta="thetahat" which will compute the conditional power at each bound using the approximate treatment effect at that bound. Otherwise, if the input is gsDesign object conditional power is computed assuming theta=x$delta, the original effect size for which the trial was planned.

Average sample number/expected sample size is computed using n.I at each analysis times the probability of crossing a boundary at that analysis. If no boundary is crossed at any analysis, this is counted as stopping at the final analysis.

B-values are Z-values multiplied by sqrt(t)=sqrt(x$n.I/x$n.I[x$k]). Thus, the expected value of a B-value at an analysis is the true value of $theta$ multiplied by the proportion of total planned observations at that time. See Proschan, Lan and Wittes (2006).

Usage

# S3 method for gsDesign
plot(x, plottype = 1, base = FALSE, ...)
# S3 method for gsProbability
plot(x, plottype = 2, base = FALSE, ...)

Arguments

Object of class gsDesign for plot.gsDesign() or gsProbability for

plot.gsProbability().

plottype

1=boundary plot (default for gsDesign),

2=power plot (default for gsProbability),

3=approximate treatment effect at boundaries,

4=conditional power at boundaries,

5=spending function plot (only available if class(x)=="gsDesign"),

6=expected sample size plot, and

7=B-values at boundaries.

Character values for plottype may also be entered: "Z" for plot type 1, "power" for plot type 2, "thetahat" for plot type 3, "CP" for plot type 4, "sf" for plot type 5, "ASN", "N" or "n" for plot type 6, and "B", "B-val" or "B-value" for plot type 7.

base

Default is FALSE, which means ggplot2 graphics are used. If true, base graphics are used for plotting.

...

This allows many optional arguments that are standard when calling plot.

Other arguments include:

theta which is used for plottype=2, 4, 6; normally defaults will be adequate; see details.

ses=TRUE which applies only when plottype=3 and

class(x)=="gsDesign"; indicates that approximate standardized effect size at the boundary is to be plotted rather than the approximate natural parameter.

xval="Default" which is only effective when plottype=2 or 6. Appropriately scaled (reparameterized) values for x-axis for power and expected sample size graphs; see details.

Value

An object of class(x); in many cases this is the input value of x, while in others x$theta is replaced and corresponding characteristics computed; see details.

References

Jennison C and Turnbull BW (2000), Group Sequential Methods with Applications to Clinical Trials. Boca Raton: Chapman and Hall.

Proschan, MA, Lan, KKG, Wittes, JT (2006), Statistical Monitoring of Clinical Trials. A Unified Approach. New York: Springer.

Examples

Run this code

# NOT RUN {
library(ggplot2)
#  symmetric, 2-sided design with O'Brien-Fleming-like boundaries
#  lower bound is non-binding (ignored in Type I error computation)
#  sample size is computed based on a fixed design requiring n=100
x <- gsDesign(k = 5, test.type = 2, n.fix = 100)
x

# the following translate to calls to plot.gsDesign since x was
# returned by gsDesign; run these commands one at a time
plot(x)
plot(x, plottype = 2)
plot(x, plottype = 3)
plot(x, plottype = 4)
plot(x, plottype = 5)
plot(x, plottype = 6)
plot(x, plottype = 7)

#  choose different parameter values for power plot
#  start with design in x from above
y <- gsProbability(
  k = 5, theta = seq(0, .5, .025), x$n.I,
  x$lower$bound, x$upper$bound
)

# the following translates to a call to plot.gsProbability since
# y has that type
plot(y)
# }