cumlogitRE              package:glmmAK              R Documentation

_L_o_g_i_t _a_n_d _c_u_m_u_l_a_t_i_v_e _l_o_g_i_t _m_o_d_e_l _w_i_t_h _r_a_n_d_o_m _e_f_f_e_c_t_s

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

     This function implements MCMC sampling for the logit model with
     binary response and the cumulative logit model for multinomial
     ordinal response. Details are given in Kom&#225rek and Lesaffre
     (2007). On as many places as possible, the same notation as in
     this paper is used also in this manual page.

     In general, the following (cumulative) logit model for response Y
     is assumed:

         log[P(Y>=1)/P(Y=0)]   =   eta[1]
        log[P(Y>=2)/P(Y<=1)]   =   eta[2]
                              ...  
       log[P(Y=C)/P(Y<=C-1)]   =   eta[C],

     where the form of the linear predictors eta[1],...,eta[C] depends
     on whether a hierarchical centering is used or not. In the
     following, beta denotes fixed effects and b random effects.

     *No hierarchical centering (DEFAULT)*
      The linear predictor for the cth logit has the following form

 eta[c] = beta[c]'(v', v(b)') + beta[*]'(x', x(b)') + b'(v(b)', x(b)') (c=1,...,C),

     where beta=(beta[1]',...,beta[C]',beta[*])' is the vector or the
     fixed-effects and b is a vector of random effects with zero
     location. 

     *Hierarchical centering*
      The linear predictor for the cth logit has the following form

 eta[c] = beta[c]'v + beta[*]'x + b[c]'v(b) + b[*]x(b) (c=1,...,C),

     where beta=(beta[1]',...,beta[C]',beta[*])' is the vector or the
     fixed-effects and b=(b[1]',...,b[C]',b[*]')' is a vector of random
     effects with location alpha=(alpha[1]',...,alpha[C]',alpha[*])'.  

     *Normal random effects ('drandom="normal"')*
      A vector of random effects is assumed to follow a (multivariate)
     normal distribution.

     That is, if there is *no hierarchical centering* we assume for b:

                           b ~ N(0, D[b]),

     where D[b] is their variance-covariance matrix.

     If the random effects are *hierarchically centered* then we assume
     for b=(b[1]',...,b[C]',b[*]')':

                         b ~ N(alpha, D[b]),

     where  alpha=(alpha[1]',...,alpha[C]',alpha[*])'   is a vector of
     random effect locations (means) and D[b] is their
     variance-covariance matrix.

     Further, in a Bayesian model, it is assumed that D[b]^(-1) has a
     Wishart W(nu[b], S[b]) prior with nu[b]  degrees of freedom and
     scale matrix S[b]. That is, a priori

                     D[b]^(-1) ~ W(nu[b], S[b]),


                      E(D[b]^(-1)) = nu[b]*S[b].

     Note that nu[b] must be higher than the number of random effects
     minus 1.

     Alternatively, when there is only a univariate random effect with
     the variance d[b]^2, it is possible to specify a uniform prior for
     the standard deviation of the random effect. That is, a priori

                          d[b] ~ Unif(0, S).


     *G-spline distributed random effects ('drandom="gspline"')*
      See 'gspline1' and 'gspline2' for description of the G-spline
     (penalized Gaussian mixture) distribution. Further, see
     Kom&#225rek and Lesaffre (2007) for description of the prior
     distribution on the G-spline. Brief description follows here as
     well.

     *Univariate* G-spline 
      If there is only a univariate random effect in the model and its
     distribution is specified as a G-spline that it is assumed that

      b ~ alpha + sum[j=-K]^K w[j] N(tau*mu[j], (tau*sigma)^2),

     where alpha is a location parameter, tau is a scale parameter and
     w=(w[-K],...,w[K])' is a vector of G-spline weights. For
     *hierarchically centered* random effects, the location parameter
     alpha is fixed to zero.

     Further, M=(mu[-K],...,mu[K])' is a vector of fixed equidistant
     knots (component means), where

                     mu[j] = j*delta (j=-K,...,K)

     and sigma is a fixed basis standard deviation.

     The constraints 0<w[j]<1 (j=-K,...,K) and sum[j=-K]^K w[j] = 1 are
     sufficient for G-spline to be a density. To avoid constraint
     estimation we will estimate transformed weights
     a=(a[-K],...,a[K])' instead which relates to the original weights
     by

         w[j] = exp(a[j])/sum[k=-K]^K exp(a[k]) (j=-K,...,K).


                 a[j] = log(w[j]/w[0]) (j=-K,...,K).

     In the estimation procedure a penalty on the a coefficients in the
     form of a Gaussian Markov random field prior is imposed.

     *Bivariate* G-spline 
      If there is a bivariate random effect b=(b[1], b[2])' in the
     model and its distribution is specified as a G-spline that it is
     assumed that

 b ~ (alpha[1], alpha[2])' + sum[j1=-K1]^K1 sum[j2=-K2]^K2 w[j1,j2] N((tau[1]*mu[1,j1], tau[2]*mu[2,j2])', diag((tau[1]*sigma[1])^2, (tau[2]*sigma[2])^2)),

     where alpha[1], alpha[2] are location parameters, tau[1], tau[2]
     are scale parameters and W=(w[-K1,-K2],...,w[K1,K2])' is a matrix
     of G-spline weights. For *hierarchically centered* random effects,
     the location parameters alpha[1], alpha[2] are fixed to zero.

     Further, M[1]=(mu[1,-K1],...,mu[1,K1])' is a vector of fixed
     equidistant knots (component means) in the first margin, where

                mu[1,j1] = j1*delta[1] (j1=-K1,...,K1)

     and sigma_1 is a fixed basis standard deviation in the first
     margin. Similarly for the second margin.

     Similar reparametrization of the G-spline weights as in the
     univariate case is used to avoid constrained estimation.

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

     cumlogitRE(y, v, x, vb, xb, cluster,                       
           intcpt.random=FALSE,
           hierar.center=FALSE,                       
           drandom=c("normal", "gspline"),
           C=1,
           logit.order=c("decreasing", "increasing"),
           prior.fixed,
           prior.random,
           prior.gspline,
           init.fixed,
           init.random,
           init.gspline,                 
           nsimul = list(niter=10, nthin=1, nburn=0, nwrite=10),
           store = list(prob=FALSE, b=FALSE, alloc=FALSE, acoef=FALSE),
           dir=getwd(),
           precision=8)

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

       y: response vector taking values 0,1,...,C.

       v: vector, matrix or data.frame with covarites for *fixed*
          effects whose effect does not necessarily satisfy
          proportional odds assumption.   

          If the argument 'intcpt.random' is set to 'FALSE' then the
          fixed intercept is included by default in the model. The
          intercept column should be included neither in 'x', nor in
          'v'. 

       x: vector, matrix or data.frame with covarites for *fixed*
          effects whose effect is assumed to satisfy proportional odds
          assumption. 

      vb: vector, matrix or data.frame with covarites for *random*
          effects whose effect does not necessarily satisfy
          proportional odds assumption.

          If you want to include *random intercept*, do it by setting
          the argument 'intcpt.random' to 'TRUE'. The intercept column
          should be included neither in 'xb', nor in 'vb'.  

      xb: vector, matrix or data.frame with covarites for *random*
          effects whose effect is assumed to satisfy proportional odds
          assumption. 

 cluster: vector which determines clusters. Needed only when there are
          any random effects in the model. 

intcpt.random: logical indicating whether a *random* intercept should
          be included in the model. 

hierar.center: logical indicating whether a hierarchical centering of
          random effects should be used or not. 

 drandom: character indicating assumed distribution of random effects
          (if there are any). 

       C: number of response categories minus 1.

logit.order: either "decreasing" or "increasing" indicating in which
          direction the logits are formed. See the same argument in
          'cumlogit' for more details.

          Currently, only "decreasing" is implemented for 'cumlogitRE'. 

prior.fixed: list specifying the prior distribution for the fixed
          effects (regression coefficients). 

          _m_e_a_n vector giving the prior mean for each regression
               coefficient. It can be a single number only in which
               case it is recycled.

          _v_a_r vector giving the prior variance for each regression
               coefficient. It can be a single number only in which
               case it is recycled.


          In the case that prior mean and/or variances are different
          for different regression coefficients then they should be
          given in the following order: intercept for the first logit,
          beta('v') for the first logit, ...,  intercept for the last
          logit, beta('v') for the last logit,     beta('x'), 

prior.random: list specifying the prior distribution for the parameters
          of the distribution of random effects. Composition of this
          list depends on the chosen distribution of random effects
          (*normal* or *Gspline*).


          _M_d_i_s_t_r_i_b character specifying the prior distribution of the
               location of random effects. It is ignored if
               'hierar.center'='FALSE', in which case the location of
               the random effects is fixed to zero. It can be one of
               the following.

               cr 'fixed'cr Locations of random effects are assumed
               to be fixed and are not updated.

               cr 'normal'cr Locations of random effects are assumed
               to be apriori normally distributed. Parameters of the
               normal distribution are specified further by items
               'Mmean' and 'Mvar'.

               This is also a default choice when 'Mdistrib' is not
               specified. 

          _M_m_e_a_n vector giving the prior means for the locations of
               random effects. It can be a single number only in which
               case it is recycled.

               It is ignored when 'hierar.center' is 'FALSE' in which
               case all random effects have zero location.

          _M_v_a_r vector giving the prior variances for the locations of
               random effects. It can be a single number only in which
               case it is recycled.

               In the case that prior means and/or variances are
               different for different locations of random effects then
               they should be given in the similar order as specified
               above for argument 'prior.fixed'.

               It is ignored when 'hierar.center' is 'FALSE' in which
               case all random effects have zero location.     

          _D_d_i_s_t_r_i_b character specifying the prior distribution of the
               covariance matrix of random effects. It can be one of
               the following.

               cr 'fixed'cr covariance matrix of random effects is
               assumed to be fixed and is not updated.

               cr 'wishart'cr inverse of the covariance matrix of
               *normally* distributed random effects is assumed to have
               a priori Wishart distribution. Parameters of the Wishart
               distribution are specified further by items 'Ddf' and
               'DinvScale'.

               This is also a default choice when 'Ddistrib' is not
               specified and random effects are normally distributed.

               This option is not allowed when the random effects
               distribution is modelled using *G-splines*.

               cr 'sduniform'cr when random effects are *normally*
               distributed then this option may be used when there is
               only a univariate random effect in the model. Its
               standard deviation is then assumed to follow a uniform
               distribution on the interval (0,S). Value of S is
               specified further by an item 'Dupper'.

               When random effects distribution is modelled using
               *G-splines* then 'sduniform' can be used also for
               multivariate random effects. It is then assumed that the
               overall standard deviation tau[m] in the mth margin
               follows a uniform distribution on the interval (0,S[m]).                      

               cr 'gamma'cr when random effects are *normally*
               distributed then this option may be used when there is
               only a univariate random effect in the model. Its
               inverse variance is then assumed to have a Gamma prior
               with the shape specified further by the item 'Dshape'
               and the rate (inverse scale) specified by the item
               'DinvScale'.

               When random effects distribution is modelled using
               *G-splines* then 'gamma' can be used also for
               multivariate random effects. It is then assumed that the
               overall inverse variance tau[m]^[-2] in the mth margin
               follows a Gamma prior with the shapes specified further
               by the item 'Dshape' and the rates (inverse scales)
               specified by the item 'DinvScale'.

          _D_d_f degrees of freedom nu[b] for the Wishart prior
               distribution of the inverse covariance matrix of
               *normally* distributed random effects. 

          _D_s_h_a_p_e number or vector with shape parameters for the gamma
               priors of the variance components of the random effects.

               If it is a single number and random effects are
               multivariate it may be recycled. 

          _D_i_n_v_S_c_a_l_e number or matrix determining the inverse scale
               matrix S[b]^(-1) for the Wishart prior distribution of
               the inverse covariance matrix of *normally* distributed
               random effects.

               Or number or vector giving the rate (inverse scale)
               parameter(s) for the gamma priors of the variance
               components.

               If it is a single number and 'Ddistrib' is *wishart*
               then it is assumed that S[b]^(-1) is diagonal with that
               single number on a diagonal.

          _D_u_p_p_e_r upper limit for the uniform distribution of the
               standard deviation of the random effect(s) when
               'Ddistrib' is equal to *sduniform*.

               If it is a single number and random effects are
               multivariate it may be recycled. 

prior.gspline: list specifying the G-spline distribution of random
          effects and prior distribution of the G-spline parameters.
          This argument is required only when 'drandom' is equal to
          *gspline*. In the following let q denote the number
          (dimension) of random effects.

          The list 'prior.gspline' can have the following components.

          _K vector of length q or a number (it is recycled) which
               specifies, for each marginal G-spline, the number of
               knots on each side of the zero knot. That is, the m-th
               marginal G-spline has 2K[m]+1 knots.

               It is set to 15 if not explicitely specified.

          _d_e_l_t_a vector of length q or a number (it is recycled) which
               specifies the distance between two consecutive knots for
               each marginal G-spline. That is, the m-th marginal
               G-spline has the following knots

               mu[m,j] = j*delta[m], j=-K[m],...,K[m].

               It is set to 0.3 if not explicitely specified.

          _s_i_g_m_a vector of length q or a number (it is recycled) which
               specifies the basis standard deviation of each marginal
               G-spline.

               sigma[m] is set to (2/3)*delta[m] if not explicitely
               specified.

          _C_A_R_o_r_d_e_r vector of length q or a number (it is recycled)
               giving the order of the intrinsic conditional
               autoregression in the Gaussian Markov random field prior
               for the transformed G-spline weights in each margin.

               It does not need to be specified when 'neighbor.system'
               is different from 'uniCAR'.

               It is set to 3 if not explicitely specified.

          _n_e_i_g_h_b_o_r._s_y_s_t_e_m character specifying the type of the Gaussian
               Markov random field in the prior for the transformed
               G-spline weights a of a *bivariate* G-spline. It does
               not have to be specified for univariate G-splines.   It
               can be one of the following.

               cr 'uniCAR'cr univariate (in each margin) conditional
               autoregression as described in Kom&#225rek and Lesaffre
               (2007). That is a priori

 p(a|lambda) propto exp[ -{ lambda[1]/2 sum[j1]...sum[jq](Delta[1]^d a[j1,...,jq])^2 + ... +  lambda[q]/2 sum[j1]...sum[jq](Delta[q]^d a[j1,...,jq])^2 } ],

               where Delta[m]^d is a difference operator of order d in
               the mth margin, e.g.,

 Delta[1]^3 a[j1,j2,...,jq] = a[j1,j2,...,jq] - 3a[j1-1,j2,...,jq] + 3a[j1-2,j2,...,jq] - a[j1-3,j2,...,jq],

               and lambda = (lambda[1], ..., lambda[q])' are smoothing
               hyperparameters. 

               This is also a default choice when 'neighbor.system' is
               not specified.     

               cr 'eight.neighbors'cr this prior is applicable for
               *bivariate* G-splines only and is based on eight nearest
               neighbors in a spatial meaning.  That is, except on
               edges, each full conditional of a depends only on eight
               nearest neighbors and local quadratic smoothing. The
               prior is then defined as

 p(a|lambda) propto exp(-lambda/2 * sum[j1=-K1][K1-1]sum[j2=-K2][K2-1] (Delta a[j1,j2])^2),

               where

 Delta a[j1,j2] = a[j1,j2] - a[j1+1,j2] - a[j1,j2+1] + a[j1+1,j2+1].

               Parameter lambda is a common smoothing hyperparameter.

               cr 'twelve.neighbors'cr not (yet) implemented         

          _L_d_i_s_t_r_i_b character specifying the prior distribution of the
               smoothing hyperparameters lambda[m], m=1,...,q
               (precision parameters of the Markov random fields in
               each margin) or of a common hyperparameter lambda It can
               be one of the following.

               cr 'fixed'cr smoothing hyperparameters lambda are
               fixed to their initial values and are not updated.

               cr 'gamma'cr each of the smoothing hyperparameters
               lambda[1],...,lambda[q] is assumed to follow a Gamma
               prior with the shapes specified further by the item
               'Lshape' and the rates (inverse scales) specified
               further by the item 'LinvScale'.

               This is also a default choice when 'Ldistrib' is not
               specified.

               cr 'sduniform'cr square root of the inversion of each
               smoothing hyperparameter, i.e.,
               sqrt(lambda[1]^{-1}),...,sqrt(lambda[q]^{-1}) is assumed
               to follow apriori a uniform distribution on the
               intervals (0, S[m,lambda]). Values of
               S[1,lambda],...,S[q,lambda] are specified further by the
               item 'Lupper'.

          _L_e_q_u_a_l logical indicating whether all smoothing
               hyperparameters should be kept equal.

               It is set to 'FALSE' if not explicitely specified and
               'neighbor.system' is 'uniCAR'. It is always 'TRUE' when
               'neighbor.system' is different from 'uniCAR'.

          _L_s_h_a_p_e number or vector with shape parameters for the *gamma*
               priors of the smoothing hyperparameters lambda.

               If it is a single number and there is more than one
               smoothing hyperparameter lambda in the model it  may be
               recycled.

          _L_i_n_v_S_c_a_l_e number or vector with rate (inverse scale)
               parameters for the *gamma* priors of the smoothing
               hyperparameters lambda.

               If it is a single number and there is more than one
               smoothing hyperparameter lambda in the model it  may be
               recycled.

          _L_u_p_p_e_r number or vector with upper limits for the uniform
               distribution on sqrt(lambda^{-1}) parameters when
               'Ldistrib' is *sduniform*.

               If it is a single number and there is more than one
               smoothing hyperparameter lambda in the model it  may be
               recycled.        

          _A_i_d_e_n_t character specifying in which way the transformed
               G-spline weights (a coefficients) are identified. It can
               be one of the following.

               cr 'mean'cr with this option, the a coefficients are
               forced to sum up to zero and have a zero mean.

               *Note* that this option usually causes problems during
               MCMC, especially with bivariate G-splines. The reason is
               that if there are many almost zero weights, they lead to
               many negative a coefficients and to satisfy the zero
               mean constrain, there must be some a's which are highly
               positive. When exponentiating them to get weights w, an
               overflow occur.

               cr 'reference'cr with this option, one of the a
               coefficients in each margin is chosen as the reference
               one and is always equal to zero. Index of the reference
               coefficient is specified by the item 'Areference' (see
               below).

               This is also a default choice when 'Aident' is not
               specified. 

          _A_r_e_f_e_r_e_n_c_e vector or number (it is recycled) which specifies
               the index of the reference a coefficient in each margin
               in the case 'Aident' is equal to *reference*. For the
               m-th margin, it must be an integer between
               -K[m],...,K[m].

               To avoid numerical problems, the index of the reference
               a coefficient may change during the MCMC.

          _A_t_y_p_e_U_p_d_a_t_e character specifying in which way the transformed
               G-spline weights (a coefficients) are updated. It can be
               one of the following.

               cr 'slice'cr slice sampler of Neal (2003).

               cr 'ars.quantile'cr adaptive rejection sampling of
               Gilks and Wild (1992) with starting abscissae being
               quantiles of the envelop at the previous iteration.

               cr 'ars.mode'cr adaptive rejection sampling of Gilks
               and Wild (1992) with starting abscissae being the mode
               plus/minus 3 times estimated standard deviation of the
               full conditional distribution.

               cr 'block'cr       all a coefficients are updated in 1
               block using the Metropolis-Hastings algorithm. This is
               only available for univariate G-splines.

               cr        Default is 'slice'. 

init.fixed: optional vector with initial values for fixed effects,
          supplied in the same order as described above in the argument
          'prior.fixed'.

          If not given, initials are determined from the
          maximum-likelihood fit to the model where random effects are
          replaced by corresponding fixed effects. 

init.random: optional list with initial values for the random effects
          and parameters determining their distribution. It can have
          the following components.

          _b vector or matrix with initial values of cluster specific
               random effects. Number of rows of the matrix or the
               length of the vector must be equal to
               'length(unique(cluster))'. Columns of the matrix
               correspond to the random effects in the same order as
               described above for argument 'prior.random'.

               If not given, initials are taken to be equal over
               clusters and equal to the corresponding fixed effects
               from the maximum-likelihood fit to the model with fixed
               effects only. 

          _m_e_a_n vector giving the initial values of the means of random
               effects.

               If not given, initials are taken to be equal to the
               corresponding fixed effects from the maximum-likelihood
               fit to the model with fixed effects only.

          _v_a_r matrix giving the initial value for the covariance matrix
               of the random effects when 'drandom' is *normal*.

               Vector giving the initial values of marginal overall
               variances of the random effects when 'drandom' is
               *gspline*. 

init.gspline: optional list with initial values related to the G-spline
          distribution of random effects (if 'drandom' is equal to
          *gspline*). It can have the following components.

          _l_a_m_b_d_a vector with initial values of the smoothing
               hyperparameters (precision parameters of the Markov
               random field). If not fixed and not given, the initials
               are sampled from the prior distribution.

          _w_e_i_g_h_t_s for *univariate* G-splines: vector with initial
               weights.

               For *bivariate* G-splines: matrix with initial weights.

               If the initial weights do not sum up to 1 they are
               re-scaled.

          _a_l_l_o_c vector or matrix with initial component allocations for
               the individual random effects. For *univariate* random
               effects this should be a vector with numbers from
               {-K,...,K}. For *bivariate* random effects this should
               be a matrix with two columns where in the first column
               numbers from {-K1,...,K1} appear and in the second
               column numbers from {-K2,...,K2} appear.


  nsimul: list indicating the length of the MCMC. It should have the
          following components.

          _n_i_t_e_r total number of the MCMC iterations after discarding
               the thinned values

          _n_t_h_i_n thinning of the sample

          _n_b_u_r_n length of the burn-in period

          _n_w_r_i_t_e frequency with which the iteration count changes.
               Further, during the burn-in, only every 'nwrite'th
               sampled value is stored on the disk      

   store: list indicating which chains (out of these not stored by
          default) should be compulsory stored. The list has the
          logical components with the following names.

          _p_r_o_b if 'TRUE' values of individual predictive probabilities
               are stored.

          _b if 'TRUE' values of cluster specific random effects are
               stored.

          _a_l_l_o_c if 'TRUE' values of allocation indicators are stored.

          _a_c_o_e_f if 'TRUE' and distribution of random effects is given
               as a *bivariate* G-spline values of log-G-spline weights
               (a coefficients) are stored for all components.


     dir: character string specifying the directory in which the
          sampled values are stored.

precision: precision with which the sampled values are written in
          files.

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

     The function returns a complete list of parameters of the prior
     distribution and initial values.

     The main task of this function is to sample from the posterior
     distribution using MCMC. Sampled values are stored in various
     files which are described below.

_F_i_l_e_s _c_r_e_a_t_e_d:


     _i_t_e_r_a_t_i_o_n._s_i_m one column labeled 'iteration' with indeces of MCMC
          iterations to which the stored sampled values correspond.

     _b_e_t_a_F._s_i_m sampled values of the fixed effects
          beta=(beta[1]',...,beta[C]',beta[*])'.

          *Note* that in models with *G-spline* distributed random
          effects which are not hierarchically centered, the average
          effect of the covariates involved in the random effects
          (needed for inference) is obtained as a sum of the
          corresponding beta coefficient and a scaled mean of the
          G-spline. beta coefficients adjusted in this way are stored
          in the file 'betaRadj.sim' (see below).

     _b_e_t_a_R._s_i_m sampled values of the location parameters
          alpha=(alpha[1]',...,alpha[C]',alpha[*])' of the random
          effects when the *hierarchical centering* was used.

          *Note* that in models with *G-spline* distributed random
          effects which are hierarchically centered, the average effect
          of the covariates involved in the random effects (needed for
          inference) is obtained as a sum of the corresponding alpha
          coefficient and a mean of the G-spline.  alpha coefficients
          adjusted in this way are stored in the file 'betaRadj.sim'
          (see below).      

     _v_a_r_R._s_i_m variance components of the random effects. Format of the
          file depends on the assumed distribution of the random
          effects.

          *_N_o_r_m_a_l _r_a_n_d_o_m _e_f_f_e_c_t_s* Let q be the dimension of the random
               effects. The first 0.5q(q+1) columns of 'varR.sim'
               contain a lower triangle (in column major order) of the
               matrix D[b], the second 0.5q(q+1) columns of 'varR.sim'
               contain a lower triangle of the matrix D[b]^(-1).


          *_U_n_i_v_a_r_i_a_t_e _G-_s_p_l_i_n_e _r_a_n_d_o_m _e_f_f_e_c_t_s* The first column of
               'varR.sim' contains the G-spline variance parameter
               tau^2, the second column its inverse.


          *_B_i_v_a_r_i_a_t_e _G-_s_p_l_i_n_e _r_a_n_d_o_m _e_f_f_e_c_t_s* The first two columns of
               'varR.sim' contain the G-spline variance parameters
               tau[1]^2, tau[2]^2, the second two columns their
               inverse.


     _l_o_g_l_i_k._s_i_m sampled values of the log-likelihood (conditioned by
          the values of random effects). 

     _p_r_o_b_a_b_i_l_i_t_y._s_i_m sampled values of category probabilities for each
          observations.

          Created only if 'store$prob' is 'TRUE'. 

     _b._s_i_m sampled values of individual random effects.

          Stores complete chains only if 'store$b' is 'TRUE'.


_F_i_l_e_s _c_r_e_a_t_e_d _f_o_r _m_o_d_e_l_s _w_i_t_h _G-_s_p_l_i_n_e _d_i_s_t_r_i_b_u_t_e_d
  _r_a_n_d_o_m _e_f_f_e_c_t_s:


     _g_s_p_l_i_n_e._s_i_m information concerning the fixed parameters of the
          G-spline which includes: dimension q of the G-spline, numbers
          of knots on each side of the reference knot for each margin
          (K[1],...,K[q]), basis standard deviations
          sigma[1],...,sigma[q] for each margin and knots
          mu[1,-K[1]],...,mu[1,K[1]], ..., mu[q,-K[q]],...,mu[q,K[q]]
          for each margin.       

     _w_e_i_g_h_t._s_i_m this file is created only for *bivariate* G-splines and
          stores the weights w of the G-spline which are higher than a
          certain threshold value. That is, the weights that are
          numerically equal to zero are not recorded here. The link
          between the weights and G-spline components is provided by
          the file 'knotInd.sim'. 

     _k_n_o_t_I_n_d._s_i_m this file is created only for *bivariate* G-splines.
          In its first column, it stores the number of G-spline
          components for which the weights are recorded on a
          corresponding row of the file 'weight.sim'. Subsequently, it
          stores indeces of the G-spline components for which the
          weights are given in the file 'weight.sim'. The indeces are
          stored as single indeces on the scale
          0,...,(2K[1]+1)*(2K[2]+1)-1 such that index 0 corresponds to
          the component (K[1],K[2]), index 1 corresponds to the
          component (K[1]+1,K[2]), ..., index K[1]-1 corresponds to the
          component (K[1],-K[2]), etc.      

     _l_o_g_w_e_i_g_h_t._s_i_m sampled values of the transformed G-spline weights
          a.

          For *univariate* G-spline, this file stores always complete
          chains, irrespective of the value of 'store$acoef'. For
          *bivariate* G-splines,this file stores complete chains only
          if 'store$acoef' is 'TRUE'.       

     _g_m_o_m_e_n_t._s_i_m first two moments of the unshifted and unscaled
          G-spline at each iteration.

          For *univariate* G-spline the column labeled 'gmean' is equal
          to

                     gmean=sum[j=-K]^K w[j]*mu[j]

          and the column labeled 'gvar' is equal to

          gmean=sum[j=-K]^K w[j]*(mu[j]-gmean)^2 + sigma^2.

          See Kom&#225rek, A. and Lesaffre, E. (2007) for formulas that
          apply in the *bivariate* case.

          Values stored here are the values of beta[1]^*,...,beta[q]^*
          and d[1,1]^*, d[2,1]^*, ..., d[q,q]^* as defined in
          Kom&#225rek and Lesaffre (2007).      

     _b_e_t_a_R_a_d_j._s_i_m sampled values of the average (overall) effects of
          the random effects. See notes under the files 'betaF.sim' and
          'betaR.sim' above.

          Values stored here are the values of gamma[1],...,gamma[q] as
          defined in Kom&#225rek and Lesaffre (2007).       

     _v_a_r_R_a_d_j._s_i_m sampled components of the variance-covariance matrix
          of the random-effects.

          Values stored here are the values of d[1,1], d[2,1], ...,
          d[q,q] as defined in Kom&#225rek and Lesaffre (2007).       

     _a_l_l_o_c._s_i_m sampled values of the component allocations (in
          Kom&#225rek and Lesaffre (2007) denoted by r[i]) for
          individual random effects.

          For *univariate* G-spline, the allocations are stored on the
          scale -K,...,K.

          For *bivariate* G-spline, the allocation are stored as single
          indeces on the scale 0,...,(2K[1]+1)*(2K[2]+1)-1 where the
          link between the single and double indeces is the same as in
          the file 'knotInd.sim'.

          Stores complete chains only if 'store$alloc' is 'TRUE'.      

     _l_a_m_b_d_a._s_i_m sampled values of smoothing hyperparameter(s) lambda. 

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

     Arno&#353t Kom&#225rek arnost.komarek[AT]mff.cuni.cz

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

     Agresti, A. (2002). _Categorical Data Analysis. Second edition_.
     Hoboken: John Wiley & Sons.

     Gelfand, A. E., Sahu, S. K., and Carlin, B. P. (1995). Efficient
     parametrisations for normal linear mixed models. _Biometrika_,
     *82*, 479-488.

     Gilks, W. R. and Wild, P. (1992). Adaptive rejection sampling for
     Gibbs sampling. _Applied Statistics,_ *41*, 337-348.

     Neal, R. M. (2003). Slice sampling (with Discussion). _The Annals
     of Statistics,_ *31*, 705-767.

     Kom&#225rek, A. and Lesaffre, E. (2008). Generalized linear mixed
     model with a penalized Gaussian mixture as a random-effects
     distribution. _Computational Statistics and Data Analysis_, *52*,
     3441-3458.

     Molenberghs, G. and Verbeke, G. (2005). _Models for Discrete
     Longitudinal Data_. New York: Springer Science+Business Media.

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

     'cumlogit', 'logpoissonRE', 'glm', 'polr'.

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

     ### See ex-Toenail.pdf and ex-Toenail.R
     ### available in the documentation
     ### to the package

