plotCEF {adaptTest}

Function to plot a conditional error function

Description

This function plots a conditional error function.

Usage

plotCEF(typ = NA, fun = NA, dis = NA, a2 = NA, c = NA, p1 = NA, p2 = p1,
        x = 0:200/200, add = TRUE, xlim = c(0, 1), ylim = c(0, 1),
        plt.pt = TRUE, plt.ptann = TRUE, xlab = NA, ylab = NA, ...)

Arguments

typ

type of test: "b" for Bauer and Koehne (1994), "l" for Lehmacher and Wassmer (1999), "v" for Vandemeulebroecke (2006) and "h" for the horizontal conditional error function

fun

a conditional error function

dis

a distortion method for a supplied conditional error function (see details): "pl" for power lines, "vt" for vertical translation

a2

\alpha_2, the local level of the test after the second stage

c

the parameter c

p1

the p-value p_1 of the test after the first stage

p2

the p-value p_2 of the test after the second stage, defaults to p1

x

vector on which the conditional error function is plotted (should be relatively dense in [0,1])

add

logical determining whether the bounds should be added to an existing plot (default) or a new plot should be opened

xlim

the x limits of the plot (default: c(0, 1); other choices can be used to "zoom in")

ylim

the y limits of the plot (default: c(0, 1); other choices can be used to "zoom in")

plt.pt

logical determining whether the point that the conditional error function is made to run through should be plotted or not (default: yes)

plt.ptann

logical determining whether the point that the conditional error function is made to run through should be annotated or not (default: yes)

xlab

a label for the x axis (default: no label)

ylab

a label for the y axis (default: no label)

...

arguments to be passed on to the underlying plot and points functions (e.g., graphical parameters)

Details

There are two alternative ways of specifying the desired conditional error function:

• through a type typ, and either a parameter (either a2 or c) or a point (p1,p2), OR

• through an initial conditional error function fun, and possibly a distortion method dis together with either the parameter a2 or a point (p1,p2)

Most people will only need the first of these two ways; the second leads to user-defined non-standard tests.

If typ is specified, a parameter a2 or c or the point (p1,p2) must be provided. In this case, plotCEF plots the conditional error function of the chosen type with the given parameter or running through the given point.

If typ is not specified, a conditional error function (i.e., a nonincreasing function defined on [0,1] with values in [0,1]) fun must be provided. If no distortion method is selected (dis = NA), fun is plotted unchanged. Otherwise, the function is distorted using the chosen distortion method, either to match a desired second stage level a2 or to run through a specified point (p1,p2) (one of which must be provided). Currently, two distortion methods are implemented:

• dis = "pl", Power lines: For an initial function fun, define f[r](x) = (f(x^r))^(1/r), r>0. Note that if fun is a conditional error function of type "b" (Bauer and Koehne, 1994), so is f[r].

• dis = "pl", Vertical translation: The initial function fun is shifted vertically.

See parconv for more information on the two alternative parameterizations by \alpha_2 and c.

Internally, plotCEF uses CEF to compute the conditional error function that is to be plotted.

Value

The function plotCEF is invoked for its plotting effect; it returns no meaningful value.

Note

Provide either typ or fun, not both! If typ is provided, then also specify a2, c, or p1 (and possibly p2). If fun is provided, then also specify dis and a2, or dis and p1 (and possibly p2), or none of these.

Warning: Values of a2 close to 0 or 1 may not work for dis = "pl".

plt.pt and plt.ptann are not considered if p1 = NA. plt.ptann is not considered if plt.pt = FALSE.

Note that in this implementation of adaptive two-stage tests, early stopping bounds are not part of the conditional error function. Rather, they are specified separately (see also tsT).

Author(s)

Marc Vandemeulebroecke

References

Bauer, P., Koehne, K. (1994). Evaluation of experiments with adaptive interim analyses. Biometrics 50, 1029-1041.

Lehmacher, W., Wassmer, G. (1999). Adaptive sample size calculations in group sequential trials. Biometrics 55, 1286-1290.

Vandemeulebroecke, M. (2006). An investigation of two-stage tests. Statistica Sinica 16, 933-951.

See Also

adaptTest package description, parconv, CEF, tsT

Examples

## Plot two conditional error functions of the Lehmacher-Wassmer (1999) type:
## one to the local level alpha2=0.1, and one that runs through (p1,p2)=(0.3,0.7)
plotCEF(typ="l", a2=0.1, add=FALSE)
plotCEF(typ="l", p1=0.3, p2=0.7)

## Plot an explicitly defined conditional error function, and distort it
plotCEF(fun=function(x) ifelse(x<.5,(1-x)^2, (1-x)/2), add=FALSE)
plotCEF(fun=function(x) ifelse(x<.5,(1-x)^2, (1-x)/2), dis="pl", a2=.5)
foo <- CEF(fun=function(x) ifelse(x<.5,(1-x)^2, (1-x)/2), dis="pl", a2=.5)
plotCEF(fun=foo, col="red")