plotCEF              package:adaptTest              R Documentation

_F_u_n_c_t_i_o_n _t_o _p_l_o_t _a _c_o_n_d_i_t_i_o_n_a_l _e_r_r_o_r _f_u_n_c_t_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     This function plots a conditional error function.

_U_s_a_g_e:

     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, ...)

_A_r_g_u_m_e_n_t_s:

     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: alpha2, the local level of the test after the second stage

       c: the parameter c

      p1: the p-value p1 of the test after the first stage

      p2: the p-value p2 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)

_D_e_t_a_i_l_s:

     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 alpha2 and c.

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

_V_a_l_u_e:

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

_N_o_t_e:

     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').

_A_u_t_h_o_r(_s):

     Marc Vandemeulebroecke

_R_e_f_e_r_e_n_c_e_s:

     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.

_S_e_e _A_l_s_o:

     'adaptTest' package description, 'parconv', 'CEF', 'tsT'

_E_x_a_m_p_l_e_s:

     ## 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")

