dirmultinomial             package:VGAM             R Documentation

_F_i_t_t_i_n_g _a _D_i_r_i_c_h_l_e_t-_M_u_l_t_i_n_o_m_i_a_l _D_i_s_t_r_i_b_u_t_i_o_n

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

     Fits a Dirichlet-multinomial distribution to a matrix response.

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

     dirmultinomial(lphi="logit", iphi = 0.10, parallel= FALSE, zero="M")

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

    lphi: Link function applied to the phi  parameter, which lies in
          the open unit interval (0,1). See 'Links' for more choices.

    iphi: Numeric. Initial value for phi. Must be in the open unit
          interval (0,1). If a failure to converge occurs try assigning
          this argument a different value.

parallel: A logical (formula not allowed here) indicating whether the
          probabilities pi_1,...,pi_{M-1} are to be equal via equal
          coefficients. Note pi_M will generally be different from the
          other probabilities. Setting 'parallel=TRUE' will only work
          if you also set 'zero=NULL' because of interference between
          these arguments (with respect to the intercept term).

    zero: An integer-valued vector specifying which linear/additive
          predictors are modelled as intercepts only. The values must
          be from the set {1,2,...,M}. If the character '"M"' then this
          means the numerical value M, which corresponds to
          linear/additive predictor associated with phi. Setting
          'zero=NULL' means none of the values from the set
          {1,2,...,M}.

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

     The Dirichlet-multinomial distribution arises from a multinomial
     distribution where the probability parameters are not constant but
     are generated from a multivariate distribution called the
     Dirichlet distribution. The Dirichlet-multinomial distribution has
     probability function

 P(Y_1=y_1,...,Y_M=y_M) = C_{y_1,...,y_M}^{N_{*}} prod_{j=1}^{M} prod_{r=1}^{y_{j}} (pi_j (1-phi) + (r-1)phi) / prod_{r=1}^{N_{*}} (1-phi + (r-1)phi)

     where phi is the _over-dispersion_ parameter and N_* =
     y_1+cdots+y_M. Here, C_b^a means ``a choose b'' and refers to
     combinations (see 'choose'). The above formula applies to each row
     of the matrix response. In this 'VGAM' family function the first
     M-1 linear/additive predictors correspond to the first M-1
     probabilities via

            eta_j =  log(P[Y=j]/ P[Y=M]) = log(pi_j/pi_M)

     where eta_j is the jth linear/additive predictor (eta_M=0 by
     definition for P[Y=M] but not for phi) and j=1,...,M-1. The Mth
     linear/additive predictor corresponds to 'lphi' applied to phi.

     Note that E(Y_j) = N_* pi_j but  the probabilities (returned as
     the fitted values) pi_j are bundled together as a M-column matrix.
     The quantities N_* are returned as the prior weights. 

     The beta-binomial distribution is a special case of the
     Dirichlet-multinomial distribution when M=2; see 'betabinomial'. 
     It is easy to show that the first shape parameter of the beta
     distribution is shape1=pi*(1/phi-1) and the second shape parameter
     is shape2=(1-pi)*(1/phi-1). Also, phi=1/(1+shape1+shape2), which
     is known as the _intra-cluster correlation_ coefficient.

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

     An object of class '"vglmff"' (see 'vglmff-class'). The object is
     used by modelling functions such as 'vglm', 'rrvglm' and 'vgam'.

     If the model is an intercept-only model then '@misc' (which is a
     list) has a component called 'shape' which is a vector with the M
     values pi_j * (1/phi-1).

_W_a_r_n_i_n_g:

     This 'VGAM' family function is prone to numerical problems,
     especially when there are covariates.

_N_o_t_e:

     The response can be a matrix of non-negative integers, or else a
     matrix of sample proportions and the total number of counts in
     each row specified using the 'weights' argument. This dual input
     option is similar to 'multinomial'.

     To fit a `parallel' model with the phi parameter being an
     intercept-only you will need to use the 'constraints' argument.

     Currently, Fisher scoring is implemented. To compute the expected
     information matrix a 'for' loop is used; this may be very slow
     when the counts are large. Additionally, convergence may be slower
     than usual due to round-off error when computing the expected
     information matrices.

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

     Thomas W. Yee

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

     Paul, S. R., Balasooriya, U. and Banerjee, T. (2005) Fisher
     information matrix of the Dirichlet-multinomial distribution.
     _Biometrical Journal_, *47*, 230-236.

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

     'dirmul.old', 'betabinomial', 'betabin.ab', 'dirichlet',
     'multinomial'.

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

     n = 10
     M = 5
     y = round(matrix(runif(n*M)*10, n, M))  # Integer counts
     fit = vglm(y ~ 1, dirmultinomial, trace=TRUE)
     fitted(fit)[1:2,]
     fit@y  # Sample proportions
     weights(fit, type="prior", matrix=FALSE) # Total counts per row

     x = runif(n)
     fit = vglm(y ~ x, dirmultinomial, trace=TRUE)
     ## Not run: 
     Coef(fit)   # This does not work
     ## End(Not run)
     coef(fit, matrix=TRUE)
     (sfit = summary(fit))
     vcov(sfit)

