betaHPD                 package:pscl                 R Documentation

_C_o_m_p_u_t_e _a_n_d _o_p_t_i_o_n_a_l_l_y _p_l_o_t _b_e_t_a _H_D_R_s

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

     Compute and optionally plot highest density regions for the Beta
     distribution

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

        betaHPD(alpha,beta,p=.95,plot=FALSE)

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

   alpha: scalar, first shape parameter of the Beta density.  Must be
          greater than 1, see details

    beta: scalar, second shape parameter of the Beta density.  Must be
          greater than 1, see details

       p: scalar, content of HPD, must lie between 0 and 1

    plot: logical flag, if 'TRUE' then plot the density and show the
          HDR

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

     The Beta density arises frequently in Bayesian models of binary
     events, rates, and proportions, which take on values in the unit
     interval.  For instance, the Beta density is a conjugate prior for
     the unknown success probability in binomial trials.  With shape
     parameters alpha > 1 and beta > 1, the Beta density is unimodal.

     In general, a highest density region (HDR) of f(theta) with
     content p in [0,1] is a set of regions mathcal{Q} of the parameter
     space with the following properties:

                  int_mathcal{Q} f(theta) dtheta = p

     and

 f(theta) > f(theta^*) , forall theta in mathcal{Q}, theta^* notin mathcal{Q}

     For a continuous, unimodal density defined with respect to a
     single parameter (like the Beta case considered here), a HDR
     region is a unique, contiguous interval in [0,1].

     This function uses numerical methods are used to solve for the
     boundaries of a HDR for the Beta density, via repeated calls the
     functions 'dbeta', 'pbeta' and 'qbeta'. The function 'uniroot' is
     used to find points v and w such that 

                             f(v) = f(w)

     subject to the constraint 

               int_v^w f(theta; alpha, beta) dtheta = p

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

     If the numerical optimization is successful an vector of length 2,
     containing v and w, defined above.    If the optimization fails
     for whatever reason, a vector of 'NAs' is returned.

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

     Simon Jackman <jackman@stanford.edu>

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

     'pbeta', 'qbeta', 'dbeta', 'uniroot'

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

     betaHPD(4,5)
     betaHPD(2,120)

