\documentclass[nojss]{jss}
%% need no \usepackage{Sweave.sty}
\usepackage{graphicx}
\usepackage{natbib}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{amsthm}
\usepackage{bm}
\usepackage{lscape}
\usepackage{rotating}
\usepackage{longtable}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% declarations for jss.cls %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%\SweaveOpts{width=60}
% \VignetteIndexEntry{MCMCglmm Overview}


%% almost as usual
\author{Jarrod Hadfield\\University of Edinburgh}
\title{MCMC Methods for Multi-response Generalized Linear Mixed Models: The \pkg{MCMCglmm}   \proglang{R} Package}

%% for pretty printing and a nice hypersummary also set:
\Plainauthor{Jarrod Hadfield} %% comma-separated
\Plaintitle{MCMC Methods for Multivariate Generalized Linear Mixed Models: The MCMCglmm R Package} %% without formatting
\Shorttitle{MCMCglmm} %% a short title (if necessary)

%% an abstract and keywords
\Abstract{
  Generalized linear mixed models provide a flexible framework for modeling a range of data, although with non-Gaussian response variables the likelihood cannot be obtained in closed form.  Markov chain Monte Carlo methods solve this problem by sampling from a series of simpler conditional distributions that can be evaluated. The  \proglang{R} package \pkg{MCMCglmm},  implements such an algorithm for a range of model fitting problems.  More than one response variable can be analysed simultaneously, and these variables are allowed to follow Gaussian, Poisson, multi(bi)nominal, exponential, zero-inflated and censored distributions. A range of variance structures are permitted for the random effects, including interactions with categorical or continuous variables (i.e., random regression), and more complicated variance structures that arise through shared ancestry, either through a pedigree or through a phylogeny. Missing values are permitted in the response variable(s) and data can be known up to some level of measurement error as in meta-analysis.  All simulation is done in  \proglang{C}/ \proglang{C++} using the \pkg{CSparse} library for sparse linear systems.  If you use the software please cite this article, as published in the Journal of Statistic Software \citep{Hadfield.2010c}

}
\Keywords{MCMC, linear mixed model, pedigree, phylogeny, animal model,  multivariate, sparse, \proglang{R}}
\Plainkeywords{MCMC, linear mixed model, pedigree, phylogeny, animal model, multivariate, sparse, R} %% without formatting
%% at least one keyword must be supplied

%% publication information
%% NOTE: Typically, this can be left commented and will be filled out by the technical editor
%% \Volume{13}
%% \Issue{9}
%% \Month{September}
%% \Year{2004}
%% \Submitdate{2004-09-29}
%% \Acceptdate{2004-09-29}

%% The address of (at least) one author should be given
%% in the following format:
\Address{
  Jarrod Hadfield\\
  The EGI\\
  Department of Zoology\\
  University of Oxford\\
  Oxford, OX1 3PS, UK\\
  E-mail: \email{jarrod.hadfield@zoo.ox.ac.uk}\\
  URL: \url{http://www.zoo.ox.ac.uk/egi/people/researchfellows/jarrod_harrod.htm}
}
%% It is also possible to add a telephone and fax number
%% before the e-mail in the following format:
%% Telephone: +43/1/31336-5053
%% Fax: +43/1/31336-734

%% for those who use Sweave please include the following line (with % symbols):
%% need no \usepackage{Sweave.sty}

%% end of declarations %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\begin{document}

Due to their flexibility, linear mixed models are now widely used across the sciences \citep{Brown.1999, Pinheiro.2000, Demidenko.2004}. However, generalizing these models to non-Gaussian data has proved difficult because integrating over the random effects is intractable \citep{McCulloch.2001}.  Although techniques that approximate these integrals \citep{Breslow.1993} are now popular, Markov chain Monte Carlo (MCMC) methods provide an alternative strategy for marginalizing the random effects that may be more robust \citep{Zhao.2006, Browne.2006}. Developing MCMC methods for generalized linear mixed models (GLMM) is an active area of research \citep[e.g.,][]{Zeger.1991, Damien.1999, Sorensen.2002, Zhao.2006}, and several software packages are now available that implement these techniques (e.g., \pkg{WinBUGS} \citep{Spiegelhalter.2003}, \pkg{MLwiN} \citep{Rasbash.2005}, \pkg{glmmBUGS} \citep{Brown.2009}, \pkg{JAGS} \citep{Plummer.2003}). However, these methods often require a certain level of expertise on behalf of the user and may take a great deal of computing time.  The \pkg{MCMCglmm} package for  \proglang{R} \citep{R.2008} implements Markov chain Monte Carlo routines for fitting multi-response generalized linear mixed models. A range of distributions are supported and several types of variance structure for the random effects and the residuals can be fitted. The aim is to provide routines that require little expertise on behalf of the user while reducing the amount of computing time required to adequately sample the posterior distribution.\\ 

 In this paper we explain the underlying structure of GLMM's and then briefly describe a general strategy for estimating the parameters. Few new results are presented, and we would like to acknowledge that many of the statistical results can be found in \citet{Sorensen.2002} and many of the algorithm details that allow the models to be fitted efficiently can be found in \citet{Davis.2006}. The main body of the paper introduces the software, using a worked example taken from a quantitative genetic experiment. We end by comparing the routines with WinBUGS \citep{Spiegelhalter.2003}, and find \pkg{MCMCglmm} to be nearly 40 times faster per iteration, and to have an effective sample size per iteration more than 3 times greater.  

\section{Model form}

The model has three components: a) probability density functions that relate the data $y$ to latent variables $l$, on the link scale b) a standard linear mixed model with fixed and random predictors applied to $l$ and c) variance structures that describe the expected (co)variances between the location effects (fixed and random effects). Although we develop these models in a Bayesian context where the distinction between fixed and random effects does not technically exist, we make the distinction throughout the manuscript as the terminology is well entrenched and understood.

\subsection{Probability of the data $y$ given the latent variable $l$}

The probability of the $i^{th}$ data point is represented by:

\begin{equation}
f_{i}(y_{i} | l_{i})
\label{pyl-Eq}
\end{equation}

where $f_{i}$ is the probability density function associated with $y_{i}$. For example, if $y_{i}$ was assumed to be Poisson distributed and we used the canonical log link function, then Equation \ref{pyl-Eq} would have the form:

\begin{equation}
f_{P}\left(y_{i} | \lambda = \textrm{exp}(l_{i})\right)
\label{pyl2-Eq}
\end{equation}

where $\lambda$ is the canonical parameter of the Poisson density function $f_{P}$.

\subsection{Linear model for the latent variables $l$}

The vector of latent variables are predicted by the linear model

\begin{equation}
{\bf l}  = {\bf X}{\bm \beta}+{\bf Z}{\bf u}+{\bf e}
\label{l-Eq}
\end{equation}
 
where ${\bf X}$ is a design matrix relating fixed predictors to the data, and ${\bf Z}$ is a design matrix relating random predictors to the data.  These predictors have associated parameter vectors ${\bm \beta}$ and ${\bf u}$, and ${\bf e}$ is a vector of residuals.  In the Poisson case these residuals deal with any over-dispersion in the data after accounting for fixed and random sources of variation.\\

\subsection{Variance structures for the model parameters}

The location effects (${\bm \beta}$ and ${\bf u}$), and the residuals (${\bf e}$) are assumed to come from a multivariate normal distribution:


\begin{equation}
\left[
\begin{array}{c}
{\bm \beta}\\
{\bf u}\\
{\bf e}
\end{array}
\right]
 \sim N\left(
\left[
\begin{array}{c}
{\bm \beta_{0}}\\
{\bf 0}\\
{\bf 0}\\
\end{array}
\right]
, 
\left[
\begin{array}{ccc}
{\bf B}&{\bf 0}&{\bf 0}\\
{\bf 0}&{\bf G}&{\bf 0}\\
{\bf 0}&{\bf 0}&{\bf R}\\
\end{array}
\right]
\right)
\label{V-Eq}
\end{equation}

where ${\bm \beta_{0}}$ are the prior means for the fixed effects with prior covariance matrix ${\bf B}$, and ${\bf G}$ and ${\bf R}$ are the expected (co)variances of the random effects and residuals respectively.  The zero off-diagonal matrices imply \emph{a priori} independence between fixed effects, random effects, and residuals.  Generally, ${\bf G}$ and ${\bf R}$ are large square matrices with dimensions equal to the number of random effects and residuals. Typically they are unknown, and must be estimated from the data, usually by assuming they are structured in a way that they can be parametrized by few parameters. Below we will focus on the structure of ${\bf G}$, but the same logic can be applied to ${\bf R}$.\\ 

At its most general, \pkg{MCMCglmm} allows variance structures of the form:

\begin{equation}
{\bf G}= \left({\bf V}_{1}\otimes{\bf A}_{1}\right) \oplus \left({\bf V}_{2}\otimes{\bf A}_{2}\right) \oplus \ldots
\label{G3-Eq}
\end{equation}

where the parameter (co)variance matrices (${\bf V}$) are usually low-dimensional and are to be estimated, and the structured matrices (${\bf A}$) are usually high dimensional and treated as known. We will refer to terms separated by a direct sum ($\oplus$) as component terms, and the use of a direct sum explicitly assumes random effects associated with different component terms are independent.  Each component term, however, is formed through the Kronecker product ($\otimes$) which allows for possible dependence between random effects \emph{within} a component term. Equation \ref{G3-Eq} can be expanded to give:

\begin{equation}
{\bf G}=\left[
\begin{array}{cc}
{\bf V}_{1}\otimes{\bf A}_{1}&{\bf 0}\\
{\bf 0}&{\bf V}_{2}\otimes{\bf A}_{2}\\
\end{array}
\right]
\label{G-Eq}
\end{equation}

where the zero off-diagonals represent the independence between component terms.\\

In the simplest models the structured matrices of each component term are often assumed to be identity matrices and the parameter (co)variance matrices scalar variances:

\begin{equation}
{\bf V}_{1}\otimes{\bf A}_{1} = \sigma^{2}_{1}{\bf I}
\label{G-Eq}
\end{equation}

which assumes that random effects within a component term are independent but have a common variance.  However, independence between different levels is often too strong an assumption. For example, if we had made two visits to a sample of schools and recorded test scores for the children, we may expect dependence between measurements made in the same school although they were sampled at different times. If the random effects are ordered schools within ages (${\bf u}^{\top} = \left[{\bf u}_{1} \ {\bf u}_{2}\right]$) where ${\bf u}_{1}$ are the random effects for the schools at time period one, and ${\bf u}_{2}$ for the same set of schools at time period 2, then an appropriate ${\bf G}$ component may have the form:

\begin{equation}
{\bf V}_{1}\otimes{\bf A}_{1}= \left[
\begin{array}{cc}
\sigma^{2}_{u_{1}}&\sigma_{u_{1},u_{2}}\\
\sigma_{u_{2},u_{1}}&\sigma^{2}_{u_{2}}\\
\end{array}
\right]
\otimes{\bf I}
\label{G4-Eq}
\end{equation}

Here the diagonal elements model different variances for the two sampling periods, and the covariance captures any persistent differences between schools.  The identity matrix in the Kronecker product implies the schools are independent.  Although the assumption of independence may be adequate in many applications, there are situations where it is not tenable. For example, when data have been collected on related individuals, or related species, then complicated patterns of dependence can arise if the characteristics are heritable. In these cases ${\bf A}$ is not an identity matrix but a matrix whose elements are equal to the proportion of genes the two individuals have in common.

\section{Parameter estimation and DIC}

For most types of model (non-Gaussian data) the distribution of $l$ is not in a recognizable form and is updated using either Metropolis-Hastings updates or the slice sampling method of \citep{Damien.1999}. Latent variables whose residuals are non-independent are sampled in blocks using Metropolis-Hastings updates and an efficient proposal distribution is determined during the burn-in phase using adaptive methods \citep{Haario.2001, Ovaskainen.2008}.  The parameters of the mixed model (${\bm \beta}$ and ${\bf u}$) follow a multivariate normal distribution and can be Gibbs sampled in a single block using the method of \citet{Garcia-Cortes.2001}.  This method requires solving a large, but often sparse set of linear equations which can be done efficiently using methods provided in the \pkg{CSparse} library \citep{Davis.2006}.  With conjugate priors the variance structures (${\bf R}$ and ${\bf G}$) follow an inverse-Wishart distribution which can also be Gibbs sampled in a single block in many instances. By fitting non-identified multiplicative working parameters for the random effects non-central $F$-distributed priors for the variance components can be fitted \citep{Gelman.2006}. This involves updating the working parameters each iteration which again can be achieved using the method of \citet{Garcia-Cortes.2001}.\\

The deviance and hence the deviance information criterion  (DIC) can be calculated in different ways depending on what is in `focus' \citep{Spiegelhalter.2002}.  For non-Gaussian response variables (including censored Gaussian) \pkg{MCMCglmm} calculates the deviance using the probability of the data given the latent variables.  For Gaussian data, however, the deviance is calculated using the probability of the data given the location parameters ${\bm \theta}^{\top} = \left[{\bm \beta}\ {\bf u}\right]$.\\

 In the appendix the conditional distributions, and computational strategies for sampling from them, are described in more detail, together with a more in depth explanation on the computation of deviance and DIC.

\section{Software}

 To illustrate the software we reanalyze experimental data collected on the Eurasian passerine bird, the Blue tit (\emph{Cyanistes caeruleus}) \citep{Hadfield.2007}. The data consist of measurements taken on 828 chicks distributed across 106 broods:

\begin{Schunk}
\begin{Sinput}
R> library("MCMCglmm")
R> data("BTdata")
R> BTdata[1,]
     tarsus     back  animal     dam fosternest  hatchdate sex
1 -1.892297 1.146421 R187142 R187557      F2102 -0.6874021 Fem
\end{Sinput}
\end{Schunk}

 The day after the chicks hatch, approximately half of the brood are reciprocally swapped with chicks from another nest. This results in an unbalanced cross-classified data structure where chicks share a \code{fosternest} with both relatives and non-relatives.  Using molecular methods \citep{Griffiths.1998} the \code{sex} of the chicks were determined in  94\% of cases, and the response variables, \code{tarsus} length and \code{back} color, were measured in all birds. The response variables are approximately normal and were mean centered and scaled to unit variance. The date on which the chicks hatched was recorded for all nests.   The parental generation is assumed to consist of unrelated individuals and all chicks from the same family are assumed to share the same mother and father.  Although in this example, family structure can be modeled more efficiently by fitting genetic mother (\code{dam}) as a random effect, we will use the more general animal model \citet{Henderson.1976} which is parametrized in terms of the relationship matrix, ${\bf A}$.  The relationship matrix is defined by the pedigree;

\begin{Schunk}
\begin{Sinput}
R> data("BTped") 
R> BTped[1,]
   animal  dam sire
1 R187557 <NAR> <NAR>
\end{Sinput}
\end{Schunk}

 a 3 column data frame with an individual's identifier (\code{animal}) in the first column and its parental identifiers in the second and third columns.  The pedigree often contains more individuals than are present in the data frame (in this example the pedigree also includes the parental generation) but all \code{animal}'s in the data frame must have a row in the pedigree.

\subsection[MCMCglmm]{\code{MCMCglmm} arguments}

The function \code{MCMCglmm} within the \proglang{R} library of the same name is used for model fitting. \citet{Hadfield.2007} were interested in estimating the covariance between \code{tarsus} and \code{back} for different sources of variation and to achieve this we fitted the model:

\begin{Schunk}
\begin{Sinput}
R> m1<-MCMCglmm(cbind(tarsus, back) ~ trait:sex + trait:hatchdate - 1, 
R>   random = ~ us(trait):animal + us(trait):fosternest, rcov = ~ us(trait):units, 
R>   prior = prior, family = rep("gaussian", 2), nitt = 60000, burnin = 10000, 
R>   thin=25, data = BTdata, pedigree=BTped)
\end{Sinput}
\end{Schunk}

In the following sections we work through the four main arguments taken by \code{MCMCglmm}: those that specify the response variables and fixed effects (\code{fixed}), the distribution of the response variables (\code{family}), the random effects and associated ${\bf G}$-structure (\code{random}), and the ${\bf R}$-structure (\code{rcov}). The syntax used to specify the model closely follows that used by \pkg{asreml} \citep{Butler.2007}, an \proglang{R} interface to \pkg{ASReml} \citep{Asreml.2002} - a program for fitting GLMM using restricted maximum likelihood (REML).\\ 

\subsection[fixed]{\code{fixed}: Response variables and fixed effects}

 The \code{fixed} argument follows the standard R formula language, and although multiple responses can be passed as a single vector, it is perhaps easier in many cases to pass them as a matrix using \code{cbind}. For example,  

\begin{Schunk}
\begin{Sinput}
fixed = cbind(tarsus, back) ~ trait:sex + trait:hatchdate - 1
\end{Sinput}
\end{Schunk}

defines a bivariate model with the responses \code{tarsus} and \code{back}. For multi-response models it is usual to make use of the reserved variables  \code{trait}  and \code{units} which index columns and rows of the response matrix, respectively. To understand the use of these variables it can be easier to think of the response as stacked column-wise: 


\begin{displaymath}
\begin{array}{cc}
\begin{array}{ccc}
&{\color{blue} \texttt{tarsus}}&{\color{blue} \texttt{back}}\\
{\color{red} 1}&\texttt{-1.89229718}&\texttt{1.1464212}\\
{\color{red} 2}&\texttt{1.13610981}&\texttt{-0.7596521}\\
\vdots&\vdots&\vdots\\
{\color{red} 828}&\texttt{0.833269}&\texttt{-1.438743}\\
\end{array}&
\Longrightarrow
\begin{array}{ccc}
\texttt{y}&{\color{blue} \texttt{trait}}&{\color{red} \texttt{units}}\\
\texttt{-1.89229718}&{\color{blue} \texttt{tarsus}}&{\color{red} 1}\\
\texttt{1.13610981}&{\color{blue} \texttt{tarsus}}&{\color{red} 2}\\
\vdots&\vdots&\vdots\\
\texttt{0.833269}&{\color{blue} \texttt{tarsus}}&{\color{red} 828}\\
\texttt{1.1464212}&{\color{blue} \texttt{back}}&{\color{red} 1}\\
\texttt{-0.7596521}&{\color{blue} \texttt{back}}&{\color{red} 2}\\
\vdots&\vdots&\vdots\\
\texttt{-1.438743}&{\color{blue} \texttt{back}}&{\color{red} 828}\\
\end{array}
\end{array}
\end{displaymath}


By fitting \code{trait} as a fixed effect we allow the two responses to have different means, and by fitting interactions such as \code{trait:hatchdate} we allow different regression slopes of the traits on \code{hatchdate}. Multi-response models models are generally easier to interpret when an overall intercept is suppressed (\code{-1}) otherwise the parameter estimates associated with \code{back} are interpreted as contrasts with \code{tarsus}.\\

\subsection[family]{\code{family}: Response variable distributions}

For the above model, two distributions must be specified in the \code{family} argument, and we assume Gaussian distributions with identity link functions for both:

\begin{Schunk}
\begin{Sinput}
family = c("gaussian", "gaussian")
\end{Sinput}
\end{Schunk}

 Other distributions and link functions can be specified (See Table \ref{Dist-tab}). Some distributions require more data columns than linear predictors. For example, censored data are passed as two columns, the first specifying the lowest value the data could take, and the second column specifying the highest value the data could take. However, only a single linear predictor (associated with the uncensored but unobserved data) is fitted for that distribution and it should be remembered that in this case \code{trait} is really indexing linear predictors, not data.  Another example of this is the binomial distribution (specified as \code{"multinomial2"} in the family argument) which is generally specified as a two column response of successes and failures, but is parametrized by a single linear predictor of the log odds ratio. In addition, some distributions actually have more linear predictors than data columns. For example, the zero-inflated Poisson has two linear predictors; one for predicting zero-inflation and one for predicting the Poisson counts. Similarly, categorical data although passed as a single response are treated as a multinomial response with $J-1$ linear predictors (where $J$ are the number of categories). Again, it should be remembered that in this case several levels of \code{trait} may be associated with different aspects of the same data column.    


\subsection[random]{\code{random}: Random effects and {\bf G}}


Simple variance structures, as represented in Equation \ref{G-Eq}, can also be specified as a standard R formula:

\begin{Schunk}
\begin{Sinput}
random = ~ fosternest + ...
\end{Sinput}
\end{Schunk}

although this is often inappropriate, especially for multi-response models where the implicit assumption has been made that \code{fosternest} effects are identical for both traits. Table \ref{rspec} summarizes covariance matrix specifications for the general $3\time3$ case, but to illustrate,  we will focus on a $2\times2$ (co)variance matrix (${\bf V}_{\texttt{f}}$) associated with \code{fosternest} effects:


 The diagonal elements are the \code{fosternest} variance components for tarsus length and back color, and the off-diagonal elements are the covariance between \code{fosternest} effects on the two traits. The specification above, without an interaction, forces the structure:

\begin{equation}
{\bf V}_{\texttt{f}}= 
\left[
\begin{array}{cc}
\sigma^{2}_{\texttt{f}}&\sigma^{2}_{\texttt{f}}\\
\sigma^{2}_{\texttt{f}}&\sigma^{2}_{\texttt{f}}\\
\end{array}
\right]
\end{equation}

where all components are forced to be the same.  It is natural to form interactions with \code{trait} as we did with the fixed effects, although there are three possible ways this could be done.  The straight forward interaction \code{trait:fosternest} although still fitting a single variance component across both traits, assumes that individual effects are independent between traits:

\begin{equation}
{\bf V}_{\texttt{f}}= 
\left[
\begin{array}{cc}
\sigma^{2}_{\texttt{f}}&0\\
0&\sigma^{2}_{\texttt{f}}\\
\end{array}
\right]
\end{equation}

More useful interactions can be formed using the \code{idh()} and \code{us()} functions. For example, \code{idh(trait):fosternest} fits heterogeneous variances across traits:

\begin{equation}
{\bf V}_{\texttt{f}}= 
\left[
\begin{array}{cc}
\sigma^{2}_{\texttt{f}:\texttt{tarsus}}&0\\
0&\sigma^{2}_{\texttt{f}:\texttt{back}}\\
\end{array}
\right]
\end{equation}

although still assumes that the two traits are independent at the \code{fosternest} level. The specification \code{us(trait):fosternest} fits the completely parametrized matrix that allows for covariance across traits:

\begin{equation}
{\bf V}_{\texttt{f}}= 
\left[
\begin{array}{cc}
\sigma^{2}_{\texttt{f}:\texttt{tarsus}}&\sigma_{\texttt{f}:\texttt{tarsus},\texttt{back}}\\
\sigma_{\texttt{f}:\texttt{back},\texttt{tarsus}}&\sigma^{2}_{\texttt{f}:\texttt{back}}\\
\end{array}
\right]
\end{equation}

Since the experiment was designed to measure the covariances between the two response variables, completely parametrized (co)variance matrices are specified: 

\begin{Schunk}
\begin{Sinput}
random = ~ us(trait):fosternest + us(trait):animal
\end{Sinput}
\end{Schunk}

For models that have pedigree or phylogenetic effects the vector of random effects needs to be associated with the inverse relationship matrix ${\bf A}^{-1}$. This matrix is formed by passing a pedigree or phylogeny to the \code{pedigree} argument of \code{MCMCglmm}.  The individuals (or taxa) need to be associated with a column in the data frame, and this column must be called \code{animal}.\\

It is also possible to fit random interactions between categorical and continuous variables as in random regression models.  For example, a random intercept-slope model with a covariance term  fitted could be specified:

\begin{Schunk}
\begin{Sinput}
random = ~ us(1+age):individual
\end{Sinput}
\end{Schunk}

or for higher order polynomials the \code{poly} function could be used:

\begin{Schunk}
\begin{Sinput}
random = ~ us(1+poly(age, 2)):individual
\end{Sinput}
\end{Schunk}

Another form of random effect structure that does not arise in the worked example is that arising in meta analysis. In meta-analysis each data point is measured with some error. If the sampling error around the true value is approximately normal, and the variance of the sampling errors known, then random effect meta-analyses can be fitted by passing the sampling variances to the \code{mev} argument of \code{MCMCglmm}.  In the simplest case, without additional random effects and i.i.d ${\bf R}$-structure, the latent variables  are assumed to have the multivariate normal distribution:

\begin{equation}
{\bf l} \sim N\left({\bf X}{\bm \beta}, {\bf D}+\sigma_{e}^{2}{\bf I}\right)
\end{equation}

where ${\bf D}$ is a diagonal matrix with \code{mev} along the diagonal.
 
\subsection[rcov]{\code{rcov}: Residual variance structure {\bf R}}

The ${\bf R}$-structure can be parametrized in the same way as the ${\bf G}$-structure although currently direct sums are not possible. However, unlike the ${\bf G}$-structure it is important that the residual model is specified in away that allows each linear predictor to have a unique residual.   For multi-response models forming an interaction between \code{trait} and \code{units} satisfies this condition and as with the ${\bf G}$-structure various types of interaction could be considered.  Again, we will use a fully parametrized covariance matrix:  \\

\begin{Schunk}
\begin{Sinput}
rcov = ~ us(trait):units
\end{Sinput}
\end{Schunk}

\subsection[prior]{\code{prior}: Response variables and fixed effects}

If not defined,  default priors are used which are not proper and this can lead to both inferential and numerical problems. The prior specification is passed to \code{MCMCglmm} via the argument \code{prior} which takes a list of three elements specifying the priors for the fixed effects (\code{B}), the ${\bf G}$-structure  (\code{G}) and the ${\bf R}$-structure  (\code{R}).\\

For the fixed effects, a multivariate normal prior distribution can be specified through the mean vector \code{mu} (${\bm \beta_{0}}$) and a (co)variance matrix \code{V} (${\bm B}$) passed as list elements of \code{B}.  The default has a zero mean vector and a diagonal variance matrix with large variances (1e+10).\\ 

For non-parameter expanded models, the parameter (co)variance matrices are assumed to have (conditional) inverse-Wishart prior distributions and individual elements for each component of the variance structure take the arguments \code{V}, \code{n} and \code{fix} which specify the expected (co)variance matrix at the limit, the degree of freedom parameter, and the partition to condition on.  The variance structure prior specification for the above models was

\begin{Schunk}
\begin{Sinput}
R> prior = list(R = list(V = diag(2)/3, n = 2),
R>            G = list(G1 = list(V = diag(2)/3, n = 2),
R>                     G2 = list(V = diag(2)/3, n = 2)))                 
\end{Sinput}
\end{Schunk}

where the expected covariance matrices for all three components of the variance structure are diagonal matrices implying  \emph{a priori} independence between \code{tarsus} and \code{back}.  The traits were scaled to have unit variance prior to analysis and so the specification implies the prior belief that the total variance is evenly split across all three terms.   The term \code{fix} has been left unspecified and so all variance parameters are estimated.  However, for certain types of model it is advantageous to be able to fix sub-matrices at certain values and not estimate them.  The \code{fix}  argument partitions \code{V} into (potentially) 4 sub-matrices where the partition occurs on the \code{fix}$^{th}$ diagonal element. For example, if \code{V} is an $n \times n$ matrix then \code{V} is partitioned:


\begin{equation}
\texttt{V} = \left[
\begin{array}{cc}
\texttt{V}_{\texttt{1:(fix-1)},  \texttt{1:(fix-1)}}&\texttt{V}_{\texttt{1:(fix-1)}, \texttt{fix:}n}\\
\texttt{V}_{\texttt{fix:}n,  \texttt{1:(fix-1)}}&\texttt{V}_{\texttt{fix:}n,  \texttt{fix:}n}\\
\end{array}
\right]
\end{equation}

and the lower right sub-matrix ($\texttt{V}_{\texttt{fix}:n,  \texttt{fix}:n}$) is fixed and not estimated. When \code{fix = 1} the whole matrix is fixed.\\

Two further arguments that can passed are \code{alpha.mu} and \code{alpha.V} which specify the prior distribution for the non-identified working parameters. When the matrix \code{alpha.V} is non-null parameter expanded models are fitted. When the variance-structure defines a single variance, the prior distribution is a scaled non-central $F$-distribution \citep{Gelman.2006}. Without loss of generality we can have \code{V = 1} in the prior to give:

\begin{displaymath}
Pr(\sigma^{2}) = f_{F}(\sigma^{2}/\texttt{alpha.V} | 1, \texttt{nu}, (\texttt{alpha.mu}^2)/\texttt{alpha.V}) 
\end{displaymath}

where $f_{F}$ is the density function of the $F$-distribution defined by three parameters: the numerator and denominator degrees of freedom and the non-centrality parameter, respectively.

\subsection[MCMC output]{MCMC output}

The model was ran for 60,000 iterations with a burn-in phase of 10,000 and a thinning interval of 25.  \code{MCMCglmm} returns  a list with elements:

\begin{itemize}
\item{\code{Sol}}: Posterior distribution of location effects (and cutpoints for ordinal models)

\item{\code{VCV}}: Posterior distribution of (co)variance matrices

\item{\code{Liab}}: Posterior Distribution of latent variables

\item{\code{Deviance}}: Deviance

\item{\code{DIC}}: Deviance Information Criterion

\end{itemize}


The samples from the posterior distribution are stored as \code{mcmc} objects, which can be summarized and visualized using the {\bf coda} package \citep{Plummer.2008}.  The element \code{Sol} contains the fixed effects (${\bm \beta}$), and if \code{pr=TRUE} then also the random effects  (${\bf u}$).  The element \code{VCV} contains the parameter (co)variance matrices stacked column-wise, and if \code{pl=TRUE} then  \code{Liab} contains the posterior distribution of latent variables ${\bf l}$.  The element \code{Deviance} contains the deviance at each stored iteration and \code{DIC} contains the deviance information criterion \citep{Spiegelhalter.2002} calculated over all iterations after burn-in.  Traces of the sampled output and density estimates are shown for the effects of gender on trait expression (Figure 1) and the genetic covariance matrix associated with \code{animal}  (See Figure 2).\\

\begin{figure}
%\begin{minipage}[b]{0.5\linewidth} % A minipage that covers half the page
%\centering
%\includegraphics[width=7cm]{Sol}
\includegraphics[]{Overview-Sol}
\label{Sol-Fig}
\caption{Trace of the sampled output and density estimates for male and female tarsus length and back color.}
\end{figure}
%\end{minipage}
%\hspace{0.5cm} % To get a little bit of space between the figures
%\begin{minipage}[b]{0.5\linewidth}
%\centering
\begin{figure}
%\includegraphics[width=7cm]{VCV}
\includegraphics[]{Overview-VCV}

\label{VCV-Fig}
\caption{Trace of the sampled output and density estimates for the genetic covariance matrix of tarsus length and back color.}
%\end{minipage}
\end{figure}

We also fitted alternative variance structures where some or all covariances were set to zero, and Table \ref{DIC-tab} shows the DIC for each model. The priors on the reduced models were set up so that the marginal prior for the variances was the same as that in the full model. The sampling error of DIC can be large and so we ran all models for an additional 500,000 iterations.

 \begin{table}
\begin{center}
\begin{tabular}{cccc}
\hline
      \code{animal}   &     \code{fosternest}       &        \code{units}        &  DIC \\
 variance function        &      variance function   &           variance function     &           \\   
us&us&us&4043.8/4041.9\\
idh&us&us&4050.5/4050.7\\
idh&idh&us&4063.0/4062.8\\
idh&idh&idh&4077.9/4076.7\\
us&idh&us&4056.2/4059.2\\
us&idh&idh&4091.1/4089.5\\
idh&us&idh&4069.8/4069.9\\
us&us&idh&4081.8/4082.4\\
\hline\\
\end{tabular}
\caption{Deviance Information Criteria for several models where the covariance between the response variable for a designated source of variation was either estimated (us) or set to zero (idh). Each model was ran twice in order to asses the level of Monte Carlo error in calculating DIC.\label{DIC-tab}}
\end{center}
\end{table}


\subsection[WinBUGS]{Comparison with \pkg{WinBUGS}}

We also fitted an identical model in \pkg{WinBUGS} (code available from the author) using a multivariate extension to the method proposed by \citet{Waldmann.2009}. On a 2.5Ghz dual core MacBook Pro with 2GB RAM, \pkg{MCMCglmm} took 7.6 minutes and \pkg{WinBUGS} took 4.8 hours to fit the model. Moreover, the number of effective samples was 3.2 times higher in \pkg{MCMCglmm} (averaged over all parameters) indicating that the chain has better mixing properties.  Because \pkg{MCMCglmm} samples all location parameters in a single block the gains in efficiency are expected to be even higher when the parameters show stronger posterior correlation.

\newpage

\section[Concluding remarks]{Concluding remarks}

This paper introduces an \proglang{R} package for fitting multi-response generalized linear mixed models using Markov chain Monte Carlo techniques developed in quantitative genetics \citep{Sorensen.2002}. A key aspect of these techniques is that they update all location effects (fixed and random) as a single block which results in better mixing properties and shorter chain lengths than alternative strategies.  This can involve repeatedly solving a very large but sparse set of mixed model equations, and the computational cost of doing this is minimized by using the \pkg{CSparse} \proglang{C} libraries for solving sparse linear systems \citep{Davis.2006}.  For the example data set analysed, \pkg{MCMCglmm} collected 120 times more effective samples per unit time than the same model fitted in \pkg{WinBUGS}.  A range of distributions for the response variables are permitted, and flexible variance structures for the random effects and residuals included.  It is hoped that this package makes the flexibility and simplicity of generalized linear mixed modeling available to a wider range of researchers.\\

\begin{center} 
{\bf \Large Acknowledgements}
\end{center}
This work would not have been possible without the \pkg{CSparse} written by Tim Davis and the comprehensive book on MCMC and mixed models by Sorensen \& Gianola. This work was funded by NERC and a Leverhulme trust award to Loeske Kruuk, who together with Shinichi Nakagawa and two anonymous reviewers made helpful comments on this manuscript. I also thank Dylan Childs for help with fitting the example in \pkg{WinBUGS}.

\bibliography{Overview}

\begin{appendix}
\section{Appendix}
\subsection[Updating the latent variables]{Updating the latent variables ${\bf l}$}

The conditional density of $l$ is given by:

\begin{equation}
Pr(l_{i}| {\bf y}, {\bm \theta}, {\bf R}, {\bf G}) \propto  f_{i}(y_{i} | l_{i})f_{N}(e_{i}|{\bf r}_{i}{\bf R}_{/i}^{-1}{\bf e}_{/i}, r_{i}-{\bf r}_{i}{\bf R}_{/i}^{-1}{\bf r}^{\top}_{i})
\label{pcl-Eq}
\end{equation}

where $f_{N}$ indicates a Multivariate normal density with specified mean vector and covariance matrix.  Equation \ref{pcl-Eq} is the probability of the data point $y_{i}$ with linear predictor $l_{i}$ on the link scale for distribution $f_{i}$, multiplied by the probability of the linear predictor residual. The linear predictor residual follows a conditional normal distribution where the conditioning is on the residuals associated with data points other than $i$. Vectors and matrices with the row and/or column associated with $i$ removed are denoted $/i$.  In practice, this conditional distribution only involves other residuals which are expected to show some form of residual covariation, as defined by the ${\bf R}$ structure.  Because of this we actually update latent variables in blocks, where the block is defined as groups of residuals which are expected to be correlated:

\begin{equation}
Pr({\bf l}_{j}|{\bf y}, {\bm \theta}, {\bf R}, {\bf G}) \propto   \prod_{i \in j}{p}_{i}({y}_{i} | l_{i})f_{N}({\bf e}_{j}|{\bf 0}, {\bf R}_{j})
\label{pcl2-Eq}
\end{equation}

where $j$ indexes blocks of latent variables that have non-zero residual covariances.  A special case arises for multi-parameter distributions in which each parameter is  associated with a linear predictor. For example, in the zero-inflated Poisson two linear predictors are used to model the same data point, one to predict zero-inflation, and one to predict the Poisson variable. In this case the two linear predictors are updated in a single block even when the residual covariance between them is set to zero, because the first probability in Equation \ref{pcl2-Eq} cannot be factored:

\begin{equation}
Pr({\bf l}_{j}|{\bf y}, {\bm \theta}, {\bf R}, {\bf G}) \propto    {p}_{i}({y}_{i} | {\bf l}_{j})f_{N}({\bf e}_{j}|{\bf 0}, {\bf R}_{j})
\label{pcl3-Eq}
\end{equation}

We use adaptive methods during the burn-in phase to determine an efficient multivariate normal proposal distribution entered at the previous value of ${\bf l}_{j}$ with covariance matrix $m{\bf M}$. For computational efficiency we use the same ${\bf M}$ for each block $j$, where ${\bf M}$ is the average posterior (co)variance of ${\bf l}_{j}$ within blocks and is updated each iteration of the burn-in period  \citet{Haario.2001}. The scalar $m$ is chosen using the method of \citet{Ovaskainen.2008} so that the proportion of successful jumps is optimal, with a rate of 0.44 when ${\bf l}_{j}$ is a scalar declining to 0.23 when ${\bf l}_{j}$ is high dimensional \citep{Gelman.2004}.\\

For the standard linear mixed model with a Gaussian response and identity link, $Pr({l}_{i}={y}_{i}|{\bf y}, {\bm \theta}, {\bf R}, {\bf G})$ is always unity and so the Metropolis-Hastings steps are always omitted.  When the latent variables within a block $j$ are associated with missing data then their conditional distribution is multivariate normal and can be  Gibbs sampled directly:

\begin{equation}
Pr({\bf l}_{j}|{\bf y}, {\bm \theta}, {\bf R}, {\bf G}) \sim  N({\bf X}_{j}{\bm \beta}+{\bf Z}_{j}{\bf u}, {\bf R}_{j})
\label{pcl4-Eq}
\end{equation}

where design matrices subscripted by $j$ are the rows of the original design matrices associated with the latent variables in block $j$.   
  
\subsection[Updating the location vector]{Updating the location vector ${\bm \theta} =  \left[{\bm \beta}^{\top}\; {\bf u}^{\top}\right]^{\top}$}

\citet{Garcia-Cortes.2001} provide a method for sampling ${\bm \theta}$ as a complete block that involves solving the sparse linear system:

\begin{equation}
\tilde{\bm \theta} = {\bf C}^{-1}{\bf W}^{\top}{\bf R}^{-1}({\bf l} - {\bf W}{\bm \theta}_{\star}-{\bf e}_{\star})
\label{sMME-Eq}
\end{equation}

where ${\bf C}$ is the mixed model coefficient matrix:

\begin{equation}
{\bf C} = {\bf W}^{\top}{\bf R}^{-1}{\bf W}+
\left[
\begin{array}{c c}
{\bf B}^{-1}&{\bf 0}\\
{\bf 0}&{\bf G}^{-1}\\
\end{array}
\right]
\end{equation}

and ${\bf W} = \left[{\bf X}\; {\bf Z}\right]$, and ${\bf B}$ is the prior (co)variance matrix for the fixed effects.\\

${\bm \theta}_{\star}$ and ${\bf e}_{\star}$ are random draws from the multivariate normal distributions:

\begin{equation}
{\bm \theta}_{\star} \sim N\left(
\left[
\begin{array}{c}
{\bm \beta_{0}}\\
{\bf 0}\\
\end{array}
\right]
,
\left[
\begin{array}{c c}
{\bf B}&{\bf 0}\\
{\bf 0}&{\bf G}\\
\end{array}
\right]
\right)
\end{equation}

and 

\begin{equation}
{\bf e}_{\star} \sim N\left({\bf W}{\bm \theta}_{\star},{\bf R}\right)
\end{equation}

$\tilde{\bm  \theta} + {\bm \theta}_{\star}$ gives a realization from the required probability distribution:

\begin{equation}
Pr({\bm \theta} | {\bf l}, {\bf W}, {\bf R}, {\bf G})
\end{equation}

Equation \ref{sMME-Eq} is solved using Cholesky factorization. Because ${\bf C}$ is sparse and the pattern of non-zero elements fixed, an initial symbolic Cholesky factorization of ${\bf P}{\bf C}{\bf P}^{\top}$ is preformed where ${\bf P}$ is a fill-reducing permutation matrix  \citep{Davis.2006}. Numerical factorization must be performed each iteration but the fill-reducing permutation (found via a minimum degree ordering of ${\bf C}+{\bf C}^{\top}$) reduces the computational burden dramatically compared to a direct factorization of ${\bf C}$  \citep{Davis.2006}.\\

Forming the inverse of the variance structures is usually simpler because they can be expressed as a series of direct sums and Kronecker products:

\begin{equation}
{\bf G}= \left({\bf V}_{1}\otimes{\bf A}_{1}\right) \oplus \left({\bf V}_{2}\otimes{\bf A}_{2}\right) \oplus \ldots
\label{G3-Eq}
\end{equation}

and the inverse of such a structure has the form 

\begin{equation}
{\bf G}^{-1} = \left({\bf V}^{-1}_{1}\otimes{\bf A}^{-1}_{1}\right) \oplus \left({\bf V}^{-1}_{2}\otimes{\bf A}^{-1}_{2}\right) \oplus \ldots\\
\end{equation}

which involves inverting the parameter (co)variance matrices (${\bf V}$), which are usually of low dimension, and inverting ${\bf A}$. For many problems ${\bf A}$ is actually an identity matrix and so inversion is not required.  When ${\bf A}$ is a relationship matrix associated with a pedigree, \citet{Henderson.1976, Meuwissen.1992} give efficient recursive algorithms for obtaining the inverse, and \citet{Hadfield.2010b} derive a similar procedure for phylogenies.
 
\subsection[Updating the variance structures]{Updating the variance structures ${\bf G}$ and ${\bf R}$}

Components of the direct sum used to construct the desired variance structures are conditionally independent.  The sum of squares matrix associated with each component term has the form:

\begin{equation}
{\bf S} = {\bf U}^{\top}{\bf A}^{-1}{\bf U}
\end{equation}

where ${\bf U}$ is a matrix of random effects where each column is associated with the relevant row/column of ${\bf V}$ and each row associated with the relevant row/column of ${\bf A}$. The parameter (co)variance matrix can then be sampled from the inverse Wishart distribution:


\begin{equation}
{\bf V} \sim IW(({\bf S}_{p}+{\bf S})^{-1},\ n_{p}+n_{u})
\label{pIW-Eq}
\end{equation}

where $n_{u}$ is the number of rows in ${\bf U}$, and ${\bf S}_{p}$ and $n_{p}$ are the prior sum of squares and prior degrees of freedom, respectively.\\

In some models, some elements of a parameter (co)variance matrix cannot be estimated from the data and all the information comes from the prior. In these cases it can be advantageous to fix these elements at some value and \citet{Korsgaard.1999} provide a strategy for sampling from a conditional inverse-Wishart distribution which is appropriate when the rows/columns of the parameter matrix can be permuted so that the conditioning occurs on some diagonal sub-matrix. When this is not possible Metropolis-Hastings updates can be made. 

\subsection{Ordinal models}

For ordinal models it is necessary to update the cutpoints which define the bin boundaries for latent variables associated with each category of the outcome.  To achieve good mixing we used the method developed by \citep{Cowles.1996} that allows the latent variables and cutpoints to be updated simultaneously using a Hastings-with-Gibbs update.

\subsection{Parameter expansion}

As the covariance matrix approaches a singularity the mixing of the chain becomes notoriously slow. This problem is often encountered in single-response models when a variance component is small and the chain becomes stuck at values close to zero.  Similar problems occur for the EM algorithm and \citep{Liu.1998} introduced parameter expansion to speed up the rate of convergence. The idea was quickly applied to Gibbs sampling problems \citet{Liu.1999} and has now been extensively used to develop more efficient mixed-model samplers \citep[e.g.,][]{vanDyk.2001, Gelman.2008b, Browne.2009}.\\

The columns of the design matrix (${\bf W}$) can be multiplied by the non-identified working parameters ${\bm \alpha} = \left[1,\ \alpha_{1},\ \alpha_{2},\ \dots \alpha_{k}\right]^{\top}$:

\begin{equation} 
{\bf W}_{\alpha} = \left[{\bf X}\ {\bf Z}_{1}\alpha_{1}\ {\bf Z}_{2}\alpha_{2}\ \dots\ {\bf Z}_{k}\alpha_{k}\right]
\label{wstar}
\end{equation}

where the indices denote sub-matrices of ${\bf Z}$ which pertain to effects associated with the same variance component. Replacing  ${\bf W}$ with ${\bf W}_{\alpha}$ we can sample the new location effects  ${\bm \theta}_{\alpha}$ as described above, and rescale them to obtain ${\bm \theta}$:

\begin{equation} 
{\bm \theta} = ({\bf I}_{n_{\bf \beta}}\oplus_{i=1}^{k}{\bf I}_{n_{{\bf u}_{i}}}\ \alpha_{i}){\bm \theta}_{\alpha}
\end{equation}

where the identity matrices are equal in dimension to $n_{x}$ the number of elements in the subscripted parameter vector $x$.\\ 

Likewise, the (co)variance matrices can be rescaled by the set of $\alpha$'s associated with the variances of a particular variance structure component (${\bm \alpha}_{\mathcal{V}}$):

\begin{equation} 
{\bf V} = Diag({\bm \alpha}_{\mathcal{V}}){\bf V}_{\alpha}Diag({\bm \alpha}_{\mathcal{V}})
\end{equation} 

The working parameters are not identifiable in the likelihood, but do have a proper conditional distribution.  Defining ${\bf X}_{\alpha}$ as an $n\times( k+1)$ design matrix,  with each column equal to the sub-matrices in Equation \ref{wstar} post-multiplied by the relevant sub-vectors of ${\bm \theta}_{\alpha}$, we can see that ${\bm \alpha}$ is a vector of regression coefficients: 

\begin{equation}
\begin{array}{rl}
\bf{l} =& {\bf X}_{\alpha}{\bm \alpha}+\bf{e}\\
\end{array}
\end{equation}

and so the methods described above can be used to update them. 

\subsection{Deviance and DIC}

The deviance $D$ is defined as:

\begin{equation}
D = -2\textrm{log}(\Pr({\bf y} | {\bm \Omega}))
\end{equation}

where ${\bm \Omega}$ is some parameter set of the model.  The deviance can be calculated in different ways depending on what is in `focus', and \code{MCMCglmm} calculates this probability for the lowest level of the hierarchy \citep{Spiegelhalter.2002}. For Gaussian response variables the likelihood is the density:

\begin{equation}
f_{N}({\bf y} | {\bf X}{\bm \beta}+{\bf Z}{\bf u},\ {\bf R}) 
\end{equation}

where ${\bm \Omega} = \left\{{\bm \theta},\ {\bf R}\right\}$ but for other response variables variables it is the product:

\begin{equation}
\prod_{i}f_{i}(y_{i} | l_{i})
\label{LLikL}
\end{equation}

with ${\bm \Omega} = {\bf l}$.\\

For multivariate models with mixtures of Gaussian and non-Gaussian data (including missing values) the likelihood of the Gaussian data is the density of ${\bf y}_{g}$ in the conditional density:

\begin{equation}
f_{N}\left({\bf y}_{g} | {\bf X}_{g}{\bm \beta}+{\bf Z}_{g}{\bf u}+{\bf R}_{g,l}{\bf R}^{-1}_{l,l}({\bf l}-{\bf X}_{l}{\bm \beta}-{\bf Z}_{l}{\bf u}),\ {\bf R}_{g,g}-{\bf R}_{g,l}{\bf R}^{-1}_{l,l}{\bf R}_{l,g}\right) 
\end{equation}

where the subscripts $g$ and $l$ denote rows of the data vector/design matrices that pertain to Gaussian data, and non-Gaussian data respectively. Subscripts on the ${\bf R}$-structure index both rows and columns. The likelihood of the non-Gaussian data are identical to Equation \ref{LLikL} giving the complete parameter set ${\bm \Omega} = \left\{{\bm \theta}_{g}, {\bf R}, {\bf l} \right\}$.\\

The deviance is calculated at each iteration if \code{DIC=TRUE} and stored each \code{thin}$^{th}$ iteration after burn-in.  The mean deviance ($\bar{D}$) is calculated over all iterations, as is the mean of the latent variables (${\bf l}$) the ${\bf R}$-structure and the vector of predictors (${\bf X}{\bm \beta}+{\bf Z}{\bf u}$).  The deviance is calculated at the mean estimate of the parameters ($D(\bar{\bm \Omega})$) and the deviance information criterion calculated as:

\begin{equation}
\textrm{DIC} = 2\bar{D}-D(\bar{\bm \Omega})
\end{equation}

\begin{landscape}
\LTcapwidth=6.2in
\begin{longtable}{cccrl}
%\begin{center}
%\small
%\begin{tabular}{cccrl}
\hline
Distribution   &    No. Data       &         No. latent        &  Density & function \\
   type        &      columns      &           columns            &          &           \\   
\hline\\
   \texttt{"gaussian"}        &  1  &   1  &         $Pr(y) =$&$f_{N}({\bf w}{\bm \theta},\sigma^{2}_{e})$\\   
&&&&\\
   \texttt{"poisson"}        &  1  &   1 &               $Pr(y) =$&$ f_{P}(\textrm{exp}(l))$\\   
&&&&\\
   \texttt{"categorical"}        &  1  &   $J$-1  &     $Pr(y=k | k\neq1) =$&$ \frac{\textrm{exp}(l_{k})}{1+\sum^{J-1}_{j=1}\textrm{exp}(l_{j})}$ \\   
           &   &     &                                  $Pr(y=1) =$&$ \frac{1}{1+\sum^{J-1}_{j=1}\textrm{exp}(l_{j})}$ \\   
&&&&\\
   \texttt{"multinomial$J$"}  &  $J$    &  $J$-1  &     $Pr(y_{k}=n_{k}| k\neq J) =$&$ \left(\frac{\textrm{exp}(l_{k})}{1+\sum^{J-1}_{j=1}\textrm{exp}(l_{j})}\right)^{n_{k}}$ \\   
    &      &   &     $Pr(y_{k}=n_{k} | k=J) =$&$ \left(\frac{1}{1+\sum^{J-1}_{j=1}\textrm{exp}(l_{j})}\right)^{n_{k}}$ \\   
&&&&\\ 
   \texttt{"ordinal"}  &  1    &  1     &              $Pr(y=k) =$&$ F_{N}(\gamma_{k} | l,1)-F_{N}(\gamma_{k-1} | l,1)$ \\   
&&&&\\
   \texttt{"exponential"}         &  1  &   1  &         $Pr(y)=$&$ f_{E}(\textrm{exp}(-l))$\\      
&&&&\\
   \texttt{"geometric"}         &  1  &   1  &         $Pr(y)=$&$ f_{G}(\frac{\textrm{exp}(l)}{1+\textrm{exp}(l)})$\\      
&&&&\\
   \texttt{"cengaussian"}        &  2 &   1  &        $Pr(y_{1}>y>y_{2}) =$&$ F_{N}(y_{2} | {\bf w}{\bm \theta},\sigma^{2}_{e})-F_{N}( y_{1} | {\bf w}{\bm \theta},\sigma^{2}_{e})$\\
&&&&\\
   \texttt{"cenpoisson"}        &  2  &   1  &        $Pr(y_{1}>y>y_{2}) =$&$ F_{P}(y_{2} | l)-F_{P}(y_{1} | l)$\\
&&&&\\
   \texttt{"cenexponential"}     &2    &  1  &          $Pr(y_{1}>y>y_{2}) =$&$ F_{E}(y_{2} | l)-F_{E}(y_{1} | l)$\\  
&&&&\\  
   \texttt{"zipoisson"}        &  1  &   2  &     $Pr(y=0) =$&$ \frac{\textrm{exp}(l_{2})}{1+\textrm{exp}(l_{2})}+\left(1-\frac{\textrm{exp}(l_{2})}{1+\textrm{exp}(l_{2})}\right)f_{P}(y|\textrm{exp}(l_{1}))$\\     
                                              &    &       & $Pr(y | y>0) =$&$ \left(1-\frac{\textrm{exp}(l_{2})}{1+\textrm{exp}(l_{2})}\right)f_{P}(y |\textrm{exp}(l_{1}))$\\      
&&&&\\
   \texttt{"ztpoisson"}         &  1  &   1  &         $Pr(y)=$&$ \frac{f_{P}(y |\textrm{exp}(l))}{1-f_{P}(0 |\textrm{exp}(l))}$\\      
&&&&\\
   \texttt{"hupoisson"}        &  1  &   2  &     $Pr(y=0) =$&$ \frac{\textrm{exp}(l_{2})}{1+\textrm{exp}(l_{2})}$\\     
                               &    &       & $Pr(y | y>0) =$&$\left(1-\frac{\textrm{exp}(l_{2})}{1+\textrm{exp}(l_{2})}\right)\frac{f_{P}(y |\textrm{exp}(l_{1}))}{1-f_{P}(0 |\textrm{exp}(l_{1}))}$\\      
&&&&\\
   \texttt{"zapoisson"}        &  1  &   2  &     $Pr(y=0) =$&$1-\textrm{exp}(\textrm{exp}(l_{2}))$\\     
                               &    &       & $Pr(y | y>0) =$&$ \textrm{exp}(\textrm{exp}(l_{2}))\frac{f_{P}(y |\textrm{exp}(l_{1}))}{1-f_{P}(0 |\textrm{exp}(l_{1}))}$\\      
&&&&\\
   \texttt{"zibinomial"}        &  2  &   2  &     $Pr(y_{1}=0) =$&$ \frac{\textrm{exp}(l_{2})}{1+\textrm{exp}(l_{2})}+\left(1-\frac{\textrm{exp}(l_{2})}{1+\textrm{exp}(l_{2})}\right)f_{B}(0, n=y_{1}+y_{2}|\frac{\textrm{exp}(l_{1})}{1+\textrm{exp}(l_{1})})$\\     
                               &    &       & $Pr(y_{1} | y_{1}>0) =$&$ \left(1-\frac{\textrm{exp}(l_{2})}{1+\textrm{exp}(l_{2})}\right)f_{B}(y_{1}, n=y_{1}+y_{2}|\frac{\textrm{exp}(l_{1})}{1+\textrm{exp}(l_{1})})$\\      
&&&&\\
\hline\\
%\end{tabular}
\caption{Distribution types that can fitted using \texttt{MCMCglmm}.  The prefixes \texttt{"zi"}, \texttt{"zt"}, \texttt{"hu"} and \texttt{"za"} stand for zero-inflated, zero-truncated, hurdle and zero-altered respectively. The prefix \texttt{"cen"} standards for censored where $y_{1}$  and $y_{2}$ are the upper and lower bounds for the unobserved datum $y$. $J$ stands for the number of categories in the multinomial/categorical distributions and this must be specified in the family argument for the multinomial distribution. The density function is for a single datum in a univariate model with ${\bf w}$ being a row vector of ${\bf W}$.  $f$ and $F$ are the density and distribution functions for the subscripted distribution ($N$=Normal, $P$=Poisson, $E$=Exponential, $G$=Geometric, $B$=Binomial). The $J-1$ $\gamma$'s in the ordinal models are the cutpoints, with $\gamma_{1}$ set to zero.\label{dist-tab}}
%\end{center}
\end{longtable}
\end{landscape}


\begin{sidewaystable}
\begin{center}
\begin{tabular}{cccc}
\hline
\code{Syntax}&n& Covariance&Correlation\\
\hline
\\
\code{rfactor}&1&
$\left[
\begin{array}{ccc}
V&V&V\\
V&V&V\\
V&V&V\\
\end{array}
\right]$
&
$\left[
\begin{array}{ccc}
1&1&1\\
1&1&1\\
1&1&1\\
\end{array}
\right]$\\
\\
\code{us(ffactor):rfactor}&6&
$\left[
\begin{array}{ccc}
V_{1,1}&V_{1,2}&V_{1,3}\\
V_{1,2}&V_{2,2}&V_{2,3}\\
V_{1,3}&C_{2,3}&V_{3,3}\\
\end{array}
\right]$
&
$\left[
\begin{array}{ccc}
1&r_{1,2}&r_{1,3}\\
r_{1,2}&1&r_{2,3}\\
r_{1,3}&r_{2,3}&1\\
\end{array}
\right]$\\
\\
\code{ffactor:rfactor}&1&
$\left[
\begin{array}{ccc}
V&0&0\\
0&V&0\\
0&0&V\\
\end{array}
\right]$
&
$\left[
\begin{array}{ccc}
1&0&0\\
0&1&0\\
0&0&1\\
\end{array}
\right]$\\
\\
\code{rfactor}+\code{ffactor:rfactor}&2&
$\left[
\begin{array}{ccc}
V_{1}+V_{2}&V_{1}&V_{1}\\
V_{1}&V_{1}+V_{2}&V_{1}\\
V_{1}&V_{1}&V_{1}+V_{2}\\
\end{array}
\right]$
&
$\left[
\begin{array}{ccc}
1&r&r\\
r&1&r\\
r&r&1\\
\end{array}
\right]^{\dagger}$\\
\\
\code{idh(ffactor):rfactor}&3&
$\left[
\begin{array}{ccc}
V_{1,1}&0&0\\
0&V_{2,2}&0\\
0&0&V_{3,3}\\
\end{array}
\right]$
&
$\left[
\begin{array}{ccc}
1&0&0\\
0&1&0\\
0&0&1\\
\end{array}
\right]$\\
\hline
\end{tabular}
\end{center}
\caption{Different random effect specifications where \code{ffactor} is a factor with three levels and \code{rfactor} is a factor with (usually) many levels. The resulting  $3\times3$ covariance and correlation matrices of \code{rfactor} effects within and across \code{ffactor} factor levels are given, together with the number of parameters to be estimated ($n$). Continuous variables can also go within the variance structure functions (e.g., \code{us},\code{idh}). In this case the associated parameters are regression coefficients for which (co)variances are estimated. $^{\dagger}: rR>0$  \label{rspec}}
\end{sidewaystable}

\end{appendix}
\end{document}
