ovP                package:adaptTest                R Documentation

_F_u_n_c_t_i_o_n _t_o _c_o_m_p_u_t_e _a_n_d _v_i_s_u_a_l_i_z_e _o_v_e_r_a_l_l _p-_v_a_l_u_e_s

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

     This function computes and plots overall p-values for adaptive
     two-stage tests.

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

     ovP(typ = NA, fun = NA, dis = NA, p1 = 1:49/50, p2 = p1,
         a1 = 0, a0 = 1, grid = FALSE, plt = FALSE,
         invisible = FALSE, wire = FALSE, round = FALSE)

_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

      p1: the p-value p1 of the test after the first stage, or a vector
          of such p-values

      p2: the p-value p2 of the test after the second stage, or a
          vector of such p-values; defaults to 'p1'

      a1: alpha1, the efficacy stopping bound and local level of the
          test after the first stage (default: no stopping for
          efficacy)

      a0: alpha0, the futility stopping bound (default: no stopping for
          futility)

    grid: logical determining whether a grid should be spanned by 'p1'
          and 'p2' (default: no grid is spanned)

     plt: logical determining whether the overall p-values should be
          plotted or not (default: not)

invisible: logical determining whether the printing of the overall
          p-values should be suppressed or not (default: not)

    wire: logical determining whether the overall p-values should be
          plotted in wireframe-style or in cloud-style (default:
          cloud-style)

   round: rounding specification, logical or integer (see details;
          default: no rounding)

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

     The overall p-value for an adaptive two-stage test is computed as
     p1 if p1 <= alpha1 or p1 > alpha0, and as 

         alpha1 + int_{alpha1}^{alpha0} cef_{(p1,p2)}(x) d x

     otherwise, where cef_{(p1,p2)} is the conditional error function
     (of a specified family) running through the observed pair of
     p-values '(p1,p2)'.

     There are two alternative ways of specifying the family of
     conditional error functions (i.e., the test): through a type
     'typ', or through an initial conditional error function 'fun' and
     a distortion method 'dis'; see 'CEF' for details.

     If p1 and p2 are of length 1, a single overall p-value is computed
     (and not plotted). Otherwise, the behavior of 'ovP' depends on
     'grid':

        *  If 'grid = FALSE', overall p-values are computed (and not
           plotted) for the elementwise pairs of 'p1' and 'p2'. Here,
           'p1' and 'p2' must be of the same length. 

        *  If 'grid = TRUE', a grid is spanned by 'p1' and 'p2', and
           p-values are computed (and possibly plotted) over this grid.
           Here, 'p1' and 'p2' may be of different length. Plotting is
           triggered by 'plt = TRUE', and the style of the plot
           (wireframe or cloud) is determined by 'wire'. 'invisible =
           TRUE' suppresses the printing of the p-values.

     The p-values are rounded to 'round' digits after the comma ('round
     = TRUE' rounds to 1 digit; 'round = FALSE' and 'round = 0' prevent
     rounding). The plot always shows unrounded values.

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

     A p-value, a vector of p-values or a matrix of p-values.

_N_o_t_e:

     Provide either 'typ' or 'fun', not both! If 'fun' is provided,
     then also specify 'dis'.

_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.

     Brannath, W., Posch, M., Bauer, P. (2002). Recursive combination
     tests. _J. Amer. Statist. Assoc._ 97, 236-244.

     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, 'CEF'

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

     ## Visualize a Lehmacher Wassmer (1999) test to the overall level 0.1
     ## and compute and visualize the overall p-value for an observed (p1,p2)=(0.3,0.7)
     alpha  <- .1
     alpha0 <- .5
     alpha1 <- .05
     plotBounds(a1=alpha1, a0=alpha0, add=FALSE)
     plotCEF(typ="l", a2=tsT(typ="l", a=alpha, a0=alpha0, a1=alpha1))
     plotCEF(typ="l", p1=.3, p2=.7)
     ovP(typ="l", p1=.3, p2=.7, a1=alpha1, a0=alpha0)
     # The overall p-value is the area left of alpha1, plus the area below the 
     # conditional error function running though (0.3,0.7) between alpha1 and alpha0.

     ## Investigate the p-values of the Lehmacher Wassmer (1999) test from above
     ovP(typ="l", a1=alpha1, a0=alpha0, grid=TRUE, p1=1:9/10, round=3)
     ovP(typ="l", a1=alpha1, a0=alpha0, grid=TRUE, plt=TRUE, invisible=TRUE, wire=TRUE)

