ldBands                package:Hmisc                R Documentation

_G_r_o_u_p _S_e_q_u_e_n_t_i_a_l _B_o_u_n_d_a_r_i_e_s _u_s_i_n_g _t_h_e _L_a_n-_D_e_M_e_t_s _A_p_p_r_o_a_c_h

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

     This function computes and plots group sequential stopping
     boundaries from the Lan-DeMets method with a variety of
     alpha-spending functions using the 'ld98' program from the
     Department of Biostatistics, University of Wisconsin written by DM
     Reboussin, DL DeMets, KM Kim, and KKG Lan.  Such stopping
     boundaries are useful for early termination of clinical trials for
     safety problems or for efficacy.  Simple 'plot' and 'print'
     methods are implemented.  Simple sample size and minimally
     detectable effect sizes given sample sizes may be obtained with a
     'summary' method if 'power' was specified to 'ldBands'. 
     Alternatively, 'summary' computes, for each look, the difference
     in means that must be achieved to cross a boundary if 'n' and 'sd'
     are specified, or the minimum difference in proportions and the
     odds ratios that must be achieved to cross a boundary if 'n' and
     'pbar' are specified.

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

     ldBands(n = length(times), times = NULL, alpha = 0.05, sided = 2,
             alphaLower=alpha/2, alphaUpper=alpha/2,
             information = NULL,
             spending=c('OBrien-Fleming','Pocock','alpha*t^phi',
                        'Hwang-Shih-DeCani'),
             phi=1,
             spending2=c('OBrien-Fleming','Pocock','alpha*t^phi',
                         'Hwang-Shih-DeCani'),
             phi2=phi,
             truncate = Inf, power = NULL, pr = TRUE)
     ## S3 method for class 'ldBands':
     print(x, ...)
     ## S3 method for class 'ldBands':
     plot(x, xlab='Time', ylab='Z', actual=NULL,
             type='b', labels=NULL, ...)

     ## S3 method for class 'ldBands':
     summary(object, stdiff=NULL, n=NULL,
             p1=NULL, p2=NULL,  hr=NULL, events=NULL,
             pbar=NULL, sd=NULL, ...)
     ## S3 method for class 'summary.ldBands':
     print(x, ...)

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

       n: number of interim analyses.  If 'times' is given, is
          automatically taken as the length of 'times'. For
          'summary.ldBands', 'n' is the sample size, to obtain
          detectable standardized difference.

   times: times at which interim analyses are done

   alpha: overall alpha level for the multiple tests. Default is
          '0.05'.  If 'sided=3' is the alpha-level for the lower
          bounds, otherwise is the total alpha.

   sided: set to '1' to use a one-sided test, '3' for asymmetric
          two-sided bounds

alphaLower: alpha-level for lower bound if 'sided=3'.  Defaults to
          alpha/2.  When 'sided=3' 'alpha' is recalculated from
          'alphaLower+alphaUpper'.

alphaUpper: alpha-level for upper bound if 'sided=3'.  Defaults to
          alpha/2.

information: a vector of information times if different from 'times'. 
          Used for computing covariances of test statistics.

spending: an alpha spending function.  Default is O'Brien-Fleming
          function.  If 'sided=3' is the spending function for the
          lower bounds.

     phi: parameter for the third and fourth types of spending
          functions (exponent of time for the third, default is '1')

spending2: spending function for the upper bounds if 'sided=3'. 
          Defaults to same spending function for lower bounds.

    phi2: parameter for third and fourth spending functions if
          'sided=3'.  Default is 'phi'.

truncate: a value at which to truncate Z critical values so that early
          looks will have some power without really affecting the
          overall alpha level.  Default is no truncation.

   power: A power for which to compute a drift parameter; useful in
          sample size calculations

      pr: set to 'FALSE' to supress the actual output of the 'ld98'
          program

       x: an object created by 'ldBands' or 'summary.ldBands'

    xlab: x-axis label

    ylab: y-axis label

  actual: an optional list with two components: times and z values to
          add as points to the first plot

    type: default is '"b"' causing both points and lines to be drawn
          for boundaries.  Use 'type="l"' for example to suppress
          drawing circles at points.

  labels: an optional character vector to be used to label time points
          corresponding to those generated by 'ldBands'

  object: an object created by 'ldBands'

  stdiff: standardized difference to detect

      p1: probability of event in group 1

      p2: probability of event in group 2, to compare with 'p1' in
          order to obtain sample size for two-sample binomial

      hr: hazard ratio to detect, to obtain needed number of events at
          end of study for either treatment arm using the logrank test

  events: number of events per treatment arm at end of study, to obtain
          detectable hazard ratio

    pbar: mean of actual probabilities of events in two treatment arms

      sd: standard deviation of an observation

     ...: unused

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

     This function assumes that you have stored the 'ld98' executable
     in a subdirectory that is in your system path.  Obtain 'ld98'
     program from the URL given in the reference below.

     The 'plot' method makes two plots if 'power' is specified, the
     second containing exit and cumulative exit probabilities as a
     function of time.  If 'par(mfrow=c())' is not already set to
     something besides 'c(1,1)', 'par(mfrow=c(2,1))' is set
     temporarily.

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

     A list of class '"ldBands"' with the following components.  When
     'summary' is used and 'n' and either 'pbar' or 'sd' are given,
     'summary' returns the same object returned by 'ldBands' but with
     possible components 'diff.lower,diff.lower' (needed difference
     means or proportions) and 'or.lower,or.upper' (needed odds
     ratios). 

    data: a data frame containing the main calculations

   power: power specified, if any

   drift: drift calculated, if 'power' specified

    type: '"boundaries"' if 'power' not specified, '"power"' otherwise

       n: number of interim analyses, for 'ldBands'.  For 'summary' is
          the number of observations per arm, and it must be a vector
          with length equal to the number of looks if 'pbar' or 'sd'
          are given.

   alpha: input value of 'alpha'

   sided: '1-3'

alphaLower: lower alpha

alphaUpper: upper alpha

spending: name of alpha spending function used

     phi: parameter for spending function

spending2: name of spending function for upper boundary. Defaults to
          'spending'

    phi2: parameter for second spending function.  Defaults to 'phi'
          but is ignored if 'spending2' is the first or second type of
          spending function.

truncate: value at which Z statistics truncated (default is 'Inf')

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

     Frank E Harrell Jr

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

     Reboussin DM, DeMets DL, Kim K-M, Lan KKG (1996): Programs for
     computing group sequential boundaries using the Lan-DeMets method.
      <URL: http://www.medsch.wisc.edu/landemets>

     Reboussin DM, DeMets DL, Kim K, Lan KKG (2000): Computations for
     group sequential boundaries using the Lan-DeMets spending function
     method. Controlled Clinical Trials 21:190-207.

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

     'gbayes'

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

     ## Not run: 
     # Get boundaries for O'Brien-Fleming spending function, 5 looks, alpha=.05
     b <- ldBands(5, pr=FALSE)
     plot(b)
     # Same but times are irregular, and information times are different than
     # test times.  Use Pocock spending function.
     b <- ldBands(times=      c(.4, .6, .8, .9, .95),
                  information=c(.42,.65,.83,.89,.94), spending='Pocock')

     # Get power calculations
     u <- ldBands(times=c(.4, .6, .8, .9, .95),  power=.9)
     u$drift                  # standardize difference * sqrt(n per arm)
                              # needed to provide power=.9
     summary(u, n=50)         # obtain detectable standardized difference
     summary(u, p1=.4, p2=.5) # get sample size per arm, two-sample binomial
     summary(u, hr=1.5)       # get number of events per arm needed
                              # to detect a hazard ratio of 1.5

     # Asymmetric boundaries with different spending functions, truncate
     b <- ldBands(5, sided=3, spending='alpha*t^phi', phi=1, phi2=1.5,
                  alphaLower=.01, alphaUpper=.04, truncate=4)
     b
     plot(b)
     # Compute differences in proportions and odds ratios needed to cross
     # the boundaries, given a mean probability in two treatment arms of 0.1
     # and given a vector of sample sizes per arm corresponding to the looks
     s <- summary(b, n=seq(200,1000,by=200), pbar=.1)
     s
     d <- s$data
     plot(d$n, d$or.lower, xlab='N Per Arm',
          ylab='Critical Odds Ratio', type='b',
          ylim=range(d$or.lower, d$or.upper), log='y')
     lines(d$n, d$or.upper, type='b')
     abline(h=1, lty=2)
     ## End(Not run)

