% \VignetteIndexEntry{How to use QGglmm}

\documentclass[a4paper, 12pt]{article}

%Chargement des paquets
\usepackage[utf8]{inputenc}	%Encodage unicode UTF8 (Linux)
\usepackage[pdftex]{graphicx}	%Gestion des figure pour PDF
\usepackage{microtype}
\usepackage[sectionbib]{natbib}	%Gestion des citations auteur-année
\usepackage[T1]{fontenc}	%Encodage Police T1
\usepackage{amsmath}		%Environnements mathématiques
\usepackage{amssymb}		%Symboles mathématiques
\usepackage{libertine}
\usepackage[libertine]{newtxmath}
\usepackage[a4paper, tmargin = 2.5cm, bmargin = 3cm, rmargin = 2cm, lmargin = 2cm]{geometry} %Gestion de la mise en page
\usepackage{sectsty}		%Style des section (voir \sectionfont)
\usepackage{fancyhdr}		%En-tête personnalisés (voir \fancyhead)
\usepackage{textcomp}		%Symboles pour le texte
\usepackage{setspace}		%Gestion de l'interligne
\usepackage{tabularx}		%Gestion améliorée des tableaux (permet tabularx ou p{20ex})
\usepackage{multirow}		%Permet la fusion de cellules
\usepackage{ae, aecompl}		%Police CM T1 pour PDF
\usepackage{color}		%Pour les couleurs
\usepackage[font={small, sf}, labelfont=bf]{caption}
\usepackage[font={small, sf}]{floatrow}
\floatsetup[table]{capposition = top}
% \usepackage[left]{lineno}	%Numéro de ligne (package deb texlive-humanities)
%\usepackage[position = bottom]{subfig}		%Sous-figures
\usepackage{icomma}		%Pour les virgules en français
% \usepackage{fancybox}		%Fancy framebox
\usepackage[svgnames, table]{xcolor}
\usepackage{Sweave}		%Permet l'utilisation de Sweave pour le code R
\definecolor{Liens_intra}{rgb}{0.4, 0.35, 0}

\usepackage[pdftex, bookmarks = true, breaklinks = true, backref = page, colorlinks = true, linkcolor = blue, urlcolor = blue, citecolor = Liens_intra, linktocpage = true, plainpages = false]{hyperref} %Paquet pour éditer proprement le PDF avec les hyperliens
\urlstyle{sf}
\usepackage{doi}
\usepackage{wrapfig}
\usepackage{bm}
\usepackage{pifont}
\newcommand{\cmark}{\ding{51}}%
\newcommand{\xmark}{\ding{55}}%
\usepackage{bigcenter}
\usepackage{booktabs}
\colorlet{tableheadcolor}{gray!35} % Table header colour = 25% gray
\newcommand{\headcol}{\rowcolor{tableheadcolor}} %
\usepackage{tikz}
\usetikzlibrary{fadings}
\usetikzlibrary{calc}
\usetikzlibrary{arrows}
\usetikzlibrary{shapes}
\usetikzlibrary{automata, positioning}

\usepackage{titling}
\usepackage{titlesec}
\titleformat*{\section}{\LARGE\sffamily\bfseries\raggedright}
\titleformat*{\subsection}{\Large\sffamily\bfseries\raggedright}
\titleformat*{\subsubsection}{\large\sffamily\bfseries\raggedright}
\titleformat*{\paragraph}{\sffamily\bfseries}
\setlength{\droptitle}{-5em}
\renewcommand{\maketitlehooka}{\sffamily\scshape\bfseries}
\usepackage{authblk} % for authors and affiliations
\renewcommand\Authfont{\normalfont\sffamily}
\renewcommand\Affilfont{\normalfont\sffamily\slshape\small}

%Style des numérotations
\renewcommand{\thesection}{\arabic{section}}
\renewcommand{\thesubsection}{\thesection.\arabic{subsection}}
\renewcommand{\thesubsubsection}{\thesubsection.\arabic{subsubsection}}
\renewcommand{\thefigure}{\arabic{figure}}
\setcounter{secnumdepth}{3}

%Interligne
% \renewcommand{\baselinestretch}{1.5}
\onehalfspacing

%Taille des en-tête et pieds de pages
\renewcommand{\headrulewidth}{0.4pt}
\renewcommand{\footrulewidth}{0pt}

%Fonction pour mettre en valeur les commentaires
\newcommand{\comment}[1]{\textit{\textcolor{red}{#1}}}

%Police des sections
\sectionfont{\Large\sc}
\subsectionfont{\large}

%Quelques couleurs
\definecolor{Grisclair}{rgb}{0.85, 0.85, 0.85}

%Environnements de code R
\definecolor{comments}{rgb}{0.4, 0.4, 0.4}
\DefineVerbatimEnvironment{Sinput}{Verbatim}{formatcom = {\color[rgb]{0.8, 0.2, 0.2}}, frame = leftline, framesep = 5pt, rulecolor = \color{black}, baselinestretch = 1, commandchars = \\\{\}}
\DefineVerbatimEnvironment{Soutput}{Verbatim}{formatcom = {\color[rgb]{0.1, 0.4, 0.1}}, frame = leftline, framesep = 5pt, rulecolor = \color{black}, baselinestretch = 1, commandchars = \\\{\}}


%Ophelins et veuves
\raggedbottom
\widowpenalty = 10000
\clubpenalty = 10000

%À écrire devant les ``backrefs''
\renewcommand*{\backref}{Cited page(s): }

%PDF Méta-informations
\hypersetup{%
pdfauthor = {Pierre de Villemereuil},
pdftitle = {How to use the QGglmm package?},
pdfsubject = {Tutorial about the QGglmm package},
pdfcreator = {LaTeX with hyperref package},
pdfproducer = {pdflatex}}

\author{\href{mailto:bonamy@horus.ens.fr}{Pierre de Villemereuil}}
\title{How to use the QGglmm package?}

\begin{document}

\maketitle

\tableofcontents

\newpage

\section{Summary and aim of the package}

\paragraph{}
The QGglmm package is an R implementation of the framework developed by \citet{de_villemereuil_general_2016} to compute quantitative genetics parameters on the observed data scale after a Generalised Linear Mixed Model (GLMM) analysis. It allows for the computation of the mean, variances and heritability on the observed data scale, as well as for evolutionary predictions if measures of fitness gradient are provided. For a comprehensive description of the framework, please read \citet{de_villemereuil_general_2016}.

\paragraph{}
The package is meant to be used \textit{after} an inference from a GLMM. As a consequence, \textit{the package does not perform any inference}. To infer genetic additive variances from your experimental design, please refer to packages or software such as \href{https://cran.r-project.org/web/packages/MCMCglmm/index.html}{MCMCglmm} or \href{http://www.vsni.co.uk/software/asreml/}{ASreml}.

\paragraph{}
This ``How-to'' is destined for people having performed a quantitative analysis through a GLMM and wanting to use QGglmm to obtain quantitative genetic parameters (e.g. additive genetic variance, heritability or G matrix) on the observed data scale rather than the latent scale (see below for a definition of the scales). It also explain how to use the package to perform evolutionary predictions if fitness information is available.

\section{Overview of the theory}

\subsection{Quantitative genetics and linear mixed models}

\paragraph{}
Nowadays, the reference kind of model for performing quantitative genetics analysis is the linear mixed model (LMM), and especially a particular form of called the animal model \citep{henderson_estimation_1950, henderson_simple_1976, kruuk_estimating_2004}, whereby the additive genetic variance of the trait is estimated using relatedness information between individuals.
Mathematically, a linear mixed model of a phenotypic trait $\mathbf{z}$\footnote{$\mathbf{z}$ is a vector containing the trait value for each individual, hence its length is equal to the number of individuals in the study.} is of the following shape:
\begin{equation}\label{eq_LMM}
\mathbf{z}= \mu + \mathbf{X}\mathbf{b} + \mathbf{Z_a}\mathbf{a} + \mathbf{Z_1}\mathbf{u_{1}} + ... + \mathbf{Z}_k\mathbf{u_{k}} + \mathbf{e},
\end{equation}
where $\mu$ is the intercept of the model, $\mathbf{X}$ is called the design matrix and contains the fixed effect co-variates and $\mathbf{b}$ contains the estimated parameters for the fixed effects. 
The random effects are separated between the additive genetic component $\mathbf{Z_a}\mathbf{a}$ and other possible random effects $\mathbf{Z_1}\mathbf{u_{1}} + ... + \mathbf{Z}_k\mathbf{u_{k}}$. Finally, $\mathbf{e}$ is the residual component (i.e. the ``error'' term).

\paragraph{}
There are several key assumptions in a LMM, among which are:
\begin{itemize}
 \item The residual $\mathbf{e}$ follows a Normal distribution with independent effects between individuals:
 \begin{equation}
  \mathbf{e} \sim \mathcal{N}(\mathbf{0}, \mathbf{I}V_{\text{R}})
 \end{equation}
where $\mathbf{I}$ is the identity matrix and $V_{\text{R}}$ is the residual variance.

\item The additive genetic component (the ``breeding values'') are normally distributed with a variance-covariance matrix $\mathbf{A}$ being composed of the relatedness between individuals:
 \begin{equation}
\mathbf{a} \sim N\left(\mathbf{0}, \mathbf{A}V_{\text{A}, \ell} \right),
\label{eq_animalTerm}
\end{equation}
where $V_{\text{A}, \ell}$ is the additive genetic variance.

\item All random effects are independent from each other and from the fixed effects.
\end{itemize}

This model is very well supported by quantitative genetics. According to \citet{fisher_correlation_1918}'s infinitesimal model, breeding values do indeed follows Eq.~\ref{eq_animalTerm}. Also, that the combined result of genetical and environmental effects follows a Normal distribution is a classical assumptions in quantitative genetics. Because of that, most tools and theory in quantitative genetics assume this kind of distribution.

\subsection{Generalised linear mixed model}

\paragraph{}
It happens often that phenotypic traits cannot be modelled by a normally distributed random error. 
This is especially the case for count, categorical or binary data. In such cases, one has to rely on Generalised Linear Mixed Models (GLMM) rather than LMM.
GLMM allows for the use of many different kind of distributions by using a hierarchical structure going from a normally distributed (hypothetical) latent trait to the observed data.

\paragraph{}
This structure consists of three ``scales'' depicted in Fig. \ref{fig_3scale} and which can be written using the following equations:
\begin{subequations}\label{eq_GLMM}
\begin{equation}\label{eq_GLMM1}
\bm{\ell} = \mu+\mathbf{X}\mathbf{b}+ \mathbf{Z_a}\mathbf{a} + \mathbf{Z_1}\mathbf{u_{1}} + ... + \mathbf{Z}_k\mathbf{u_{k}} + \mathbf{o},
\end{equation}
\begin{equation}\label{eq_GLMM2}
\bm{\eta} = g^{-1}(\bm{\ell}),
\end{equation}
\begin{equation}\label{eq_GLMM3}
\mathbf{z} \sim \mathcal{D}(\bm{\eta}, \bm{\theta}),
\end{equation}
\end{subequations}
Eq.~\ref{eq_GLMM1} refers to the latent trait $\bm{\ell}$.

\paragraph{}
By comparing it to Eq.~\ref{eq_LMM}, we can see that the same assumptions are made for $\bm{\ell}$ as in any LMM. 
To reflect the fact that the ``error'' on the latent trait is not the residual error of the model, we changed the notation of the residual $\mathbf{e}$ to $\mathbf{o}$. 
The term $\mathbf{o}$ is still normally distributed and stands for the additive over-dispersion of the model \citep{nakagawa_repeatability_2010}. Accordingly, we will note the variance associated to $\mathbf{o}$ as $V_{\text{O}}$.\\


\begin{wrapfigure}[25]{l}{0.3\textwidth}
  \centering
  \includegraphics[width = \textwidth]{Figs/3scales.pdf}
  \caption{The three scales of the Generalised Linear Mixed Model (here using Poisson with a log link function as an example). The error terms are normally distributed on the latent scale, but follows a Poisson distribution on the observed data scale (conditionnally on the latent scale).}
  \label{fig_3scale}
\end{wrapfigure}


In \citet{de_villemereuil_general_2016}, Eq.~\ref{eq_GLMM2} is said to refer to the ``expected data scale''. 
This is because the term $\bm{\eta}$ is the individual expectation around which the observed data are realised (see example below). The transition from the latent scale to the expected data scale is preformed by the inverse of the link-function $g$. 
The link function is ``mapping'' the variations on the latent scale to variations compatible for the distribution used. For example, whereas the latent trait varies between $-\infty$ to $\infty$, a binomial distribution can only use values between 0 and 1, hence the use of logit or probit link-function which match these input and output realms.\\
Finally, Eq.~\ref{eq_GLMM3} models the ``observed data scale'' by adding, to the expectation $\bm{\eta}$, an error term from a 
given non-Normal distribution (here noted $\mathcal{D}$), which can accept additional parameters $\bm{\theta}$.

\paragraph{}
It is very important to realise that most (and very often, all) parameters are inferred on the latent scale, and \textit{not} on the observed data scale. All parameters commonly interpreted in quantitative genetics (population mean $\mu$, additive genetic variance $V_{\text{A}, \ell}$ and all other variance components) are thus related to a hypothetical latent trait, and hence not directly to the phenotypic trait of interest (see more about this in section \ref{subsec_QGandGLMM}).

\subsection{An illustrative example}

\paragraph{}
All the statistical soup above might seem difficult to digest to some readers. In order to best explain some of these technical facts, we will use an illustrative example directly simulated in R. This example will use a Poisson with a log link-function GLMM.

\paragraph{}
Let's consider a very simple model for now, with no fixed effects and no random effects except for the additive genetic one. Following Eqs.~\ref{eq_GLMM}, we can write the model as:
\begin{subequations}\label{eq_Poisson}
\begin{equation}\label{eq_Poisson1}
\bm{\ell} = \mu + \mathbf{Z_a}\mathbf{a} + \mathbf{o},
\end{equation}
\begin{equation}\label{eq_Poisson2}
\bm{\eta} = \exp(\bm{\ell}),
\end{equation}
\begin{equation}\label{eq_Poisson3}
\mathbf{z} \sim \mathcal{P}(\bm{\eta}),
\end{equation}
\end{subequations}
Note that, because we use the inverse of the log link-function, we use, well, the inverse of the logarithm, which is an exponential. Note that a Poisson can only use positive real number as input and that exponential only yields positive real numbers, so the ``matching'' performed by the link-function is quite obvious here.

\begin{wrapfigure}[4]{l}{0.4\textwidth}
 \centering
 \vspace{-0.8cm}
 \includegraphics[width = \textwidth]{Figs/latent.pdf}
 \caption{Distribution of the simulated latent trait.}
 \label{fig_latent}
\end{wrapfigure}

\paragraph{}
So, our model has three parameters: the intercept $\mu$, the additive genetic variance $V_{\text{A}, \ell}$ and the over-dispersion variance $V_{\text{O}}$. Let's define some values for them:
\begin{Schunk}
 \begin{Sinput}
# Value for the intercept mu
mu <- 0
# Additive genetic variance
Va <- 0.3
# Over-dispersion variance
Vo <- 0.3
# Number of individuals
N  <- 1000
 \end{Sinput}
\end{Schunk}
~\\[1cm]
Using these parameters, we can simulate the latent trait:
\begin{Schunk}
 \begin{Sinput}
l <- mu + rnorm(N, 0, sqrt(Va)) + rnorm(N, 0, sqrt(Vo))
 \end{Sinput}
\end{Schunk}
The distribution of the simulated latent trait is illustrated in Fig.~\ref{fig_latent}\footnote{Note that because we do not have fixed effects, the distribution is clearly Gaussian, but when fixed effects are included, there is no expectation for the distribution of $\bm{\ell}$ to be Gaussian (only the residual is, i.e. when all effects have been ``removed'').}. 

\paragraph{}
Now that we have constructed our latent trait, we can use the inverse of the link-function to compute the values on the expected data scale (a.k.a. $\bm{\eta}$):
\begin{Schunk}
 \begin{Sinput}
eta <- exp(l)
 \end{Sinput}
\end{Schunk}
Yes, it's that simple. The distribution of $\bm{\eta}$ is illustrated in Fig.~\ref{fig_expected}. 
From this graph and the fact that we are simply taking the exponential of the latent trait, we can see that two things are going to happen: much of the values are going to be low (say between 0 and 1), whereas a few (corresponding to the upper tail of the Normal distribution) are going to yield large values (in Fig.~\ref{fig_expected}, we see the extreme is just above 20).
This is all good and well, but doesn't quite really illustrate what $\bm{\eta}$ is biologically. The best way to see this is to compute the observed phenotypic trait from it.

\begin{wrapfigure}[9]{r}{0.4\textwidth}
 \centering 
 \vspace{-0.8cm}
 \includegraphics[width = \textwidth]{Figs/expected.pdf}
 \caption{Distribution of the simulated $\bm{\eta}$ values.}
 \label{fig_expected}
\end{wrapfigure}

\paragraph{}
The observed phenotypic trait $\mathbf{z}$ is the realisation around the individual expectation $\bm{\eta}$ according to the chosen distribution $\mathcal{D}$. In our case, what this means is that for individual $i$, its phenotype $z_{i}$ is drawn from a Poisson distribution with a mean (i.e. the famous $\lambda$ parameter of the Poisson distribution) $\eta_{i}$:
\begin{Schunk}
 \begin{Sinput}
z <- rpois(N, lambda = eta)
 \end{Sinput}
\end{Schunk}
Now, the distribution of our simulated phenotypic trait is illustrated in Fig.~\ref{fig_observed}. We can see that this distribution is heavily non-Gaussian\footnote{At this point, we need to remind the reader that we are authorised to look at the overall shape of the different scales directly because our simulations did not have any fixed effects. A variable can totally have a weird distribution, but a normally distributed error term if the correct covariate is used as a fixed effect.}, with a lot of 0 and a few large values (again up to slightly above 20). 

\begin{wrapfigure}[6]{r}{0.4\textwidth}
 \centering
 \vspace{-1cm}
 \includegraphics[width = \textwidth]{Figs/observed.pdf}
 \caption{Distribution of the simulated $\mathbf{z}$ values.}
 \label{fig_observed}
\end{wrapfigure}

\paragraph{}
To fully realise the meaning of the different scales, it can be interesting to ``follow'' the values for a particular individual, say the 101th. First, we can have a look at its latent value:
\begin{Schunk}
 \begin{Sinput}
l[101]
eta[101]
z[101]
 \end{Sinput}
 \begin{Soutput}
1.225813
3.406933
4
 \end{Soutput}
\end{Schunk}
So, this individual have a latent trait value of 1.23. This value can be directly compared to our value of the population latent mean $\mu$, which was 0. This individual's latent component tends thus toward bigger values than the average. As a result, its expected value is of 3.4. Let's say that our trait is the mating success of a population of male. This means that this individual is expected, according to its latent (i.e. in part, according to its genetics), to mate with 3.4. Now, we all know that it's impossible to mate with 3.4 females: we can only observe integer values of mating success. This is the observed value, which, in our case was 4, but could have been anything e.g. between 1 and 7:
\begin{Schunk}
 \begin{Sinput}
qpois(0.05, lambda = 3.4)
qpois(0.95, lambda = 3.4)
 \end{Sinput}
 \begin{Soutput}
1
7
 \end{Soutput}
\end{Schunk}
It is thus important to realise that the observed values can be quite different from the expected ones and, more importantly, that the noise assumed on this latter part of the model can be very large. We will come to this latter, when mentioning the different values of the heritability.

\paragraph{}
This whole simulation is basically the process assumed by a GLMM. Latent values are assigned, according to all predictors (here only an additive genetic one), to all individuals, or observations if they are repeated measurements. These latent values are transformed, using the inverse-link-function into expected values, around which observed values are drawn. The main difference when performing a statistical inference with a GLMM is that only observed values are known, the rest is entirely inferred by the model.

\paragraph{}
It would be advisable, for anyone using a GLMM, to toy around with these kind of simulations (changing the parameters and distribution to fit the case at hand), in order to get familiar with the implications of some parameters values. Most of the time, indeed, change in a parameter value will have quite different consequences on the data scale compared to what one can expect in a LMM.
This is illustrated from the simulation above. Note that the latent mean is 0, yet all simulated data have a positive value. Note also the low values for the latent variances, whereas the simulated data have a much larger variance.


\subsection{Quantitative genetics and GLMM}
\label{subsec_QGandGLMM}

\paragraph{}
How is the use of GLMM justified for quantitative genetics analysis? What should we do differently than what we are doing when using plain LMM? Many people think that GLMM are just ``LMM with a different distribution'', but we just saw that the reality is more complex than that, especially because the model has now three different scales, each with a particular behaviour. Much of what will be mentioned here comes from \citet{de_villemereuil_general_2016}, so we will just summarise some issues and try to keep it simple.

\paragraph{}
The first thing to mention is why we need the latent trait to be Gaussian (or a latent trait at all...). 
This stems from models underlying quantitative genetics, especially \citet{fisher_correlation_1918}'s infinitesimal model: the results of a large number of additive effects, each with a small effect, will result in a normally distributed genetic component. A same line of reasoning (e.g. using the central-limit theorem) allows us to assume the same kind of distribution for the environmental effects. 
Hence, more than justified, it is \textit{needed}\footnote{Well, obviously, this is assuming that the infinitesimal model is a good approximation of the reality.} that at some point, \textit{something} is normally distributed. We simply call this something ``latent trait''.

\paragraph{}
A second thing to mention is that GLMM are in essence \textit{very noisy} models. There are three main sources of noise. A first source is the latter part of the model where observed values are drawn around the expected values following the distribution $\mathcal{D}$. This is the actual ``error process'' of the model. 
One thing is very important to note with this source of noise: contrary to the normally-distributed noise of a LMM, the level of noise almost always depends on the actual expected value. Indeed, the variance of a Poisson is equal to the mean, the variance of a binomial distribution depends only on the mean, etc... This means that we assume that a part of the phenotypic variance is \textit{irreducible}: there's always be some variance, depending on the value of the trait.\\
The second source is the inverse-link-function. It is not \textit{creating} noise (it's a function, not a statistical distribution after all), but it can \textit{amplify} the noise from the latent scale to a great extent. Think about the Poisson-log model above: we take the exponential of the latent scale. This means that values that are close on the latent scale, say 1, 2 and 3, will give respectively 2.7, 7.4 and 20 on the expected data scale: large values become even larger!\\
Finally, the last source of noise is the over-dispersion variance present in the latent scale. Despite GLMMs being somewhat noisy already, it is frequent that this variance is required for a good model fit\footnote{Sometimes, the over-dispersion variance is also required for the method to work: it is the case for e.g. MCMCglmm}.\\
Why is it important that GLMM are noisy in the context of quantitative genetics? Well, this means that phenotypic variance on the observed data scale tends to be large, especially when compared to the original variance on the latent scale. The direct consequence of this is that heritabilities inferred on the observed data scale are expected to be \textit{rather small}! For example, because GLMMs always assume environmental noise from the distribution $\mathcal{D}$, heritability on the observed data scale can never reach a maximum of 1.

\paragraph{}
A third and last thing to mention is something quite important from a quantitative genetics perspective: the link-function is almost never linear! Why is that important? Because it breaks the additivity of the genetic effects to some degree. 
Even if only additive effects are assumed on the latent scale, the result on the observed data scale is a mix of additive and non-additive effects (simply because it went through the inverse-link-function!). When computing the heritability, we want to extract only the additive part, which is all what QGglmm is about. 
But this has further consequences. Narrow-sense heritability is nothing like repeatability\footnote{Heritability is sometimes considered as an ``additive genetic repeatability'' and they share most of their features when assuming a LMM. Especially, they are both some kind of statistics called intra-class correlation coefficients.} when they are computed on the observed data scale. 
This means that some of the computations and advice available in \citet{nakagawa_repeatability_2010} are not applicable to narrow-sense heritability on the observed scale.
However, broad-sense heritability (i.e. including the non-additive effects) can be computed as a repeatability-like estimate (a.k.a. intra-class correlation coefficients, ICC). QGglmm also provides a way to compute ICCs, even for non-genetic components, see section \ref{subsec_ICC}.

\section{The framework behind QGglmm}

Most of the content of this section is explained in more details in the article introducing the framework \citep{de_villemereuil_general_2016}. We will here just have an overview of the computations involved, as they are needed to understand what the package is doing. 

Exactly knowing how to compute the parameters is, of course, QGglmm's business. It will start computation with the correct functions given the distribution name it has been given (see the practice in the following section). Interpreting the output of QGglmm however is up to the user, and having an idea of what happens behind the scene of a package is always the best strategy for a correct interpretation. 

\subsection{Computing the phenotypic mean and variance}

The first parameters to compute are the population phenotypic mean and variance on the observed data scales. 

\paragraph{Population mean}
The last layer, going from Eq.~\ref{eq_GLMM2} to Eq.~\ref{eq_GLMM3} just adds noise around some expected values (computed as $g^{-1}(\ell)$). Hence, the population mean is the average of these expected values:
\begin{equation}\label{eq_mean}
\bar{z} = \int  g^{-1}(\ell)f_{\mathcal{N}}(\ell, \mu, V_{\text{P}, \ell})\text{d}\ell,
\end{equation}
where $f_{\mathcal{N}}(\ell, \mu, V_{\text{P}, \ell})$ is the probability density of a Normal distribution with mean $\mu$ and variance $V_{\text{P}, \ell}$ evaluated at $\ell$. Note that $V_{\text{P}, \ell}$ is the sum of all variance components (i.e. $V_{\text{A}, \ell}$, $V_{\text{O}, \ell}$ and random effect variances) on the latent scale. In other words, it is the ``phenotypic variance'' of the latent trait.

\paragraph{Variance on the expected data scale}
The variance on the expected data scale is simply the variance of the above-mentioned expected values around the population mean:
\begin{equation}\label{eq_phenvar_eds}
V_{\text{P}, \text{exp}} = \int  \left( g^{-1}(\ell) - \bar{z} \right)^2 f_{\mathcal{N}}(\ell, \mu, V_{\text{P}, \ell}) \text{d}\ell.
\end{equation}

\paragraph{Variance on the observed data scale}
To compute the variance of the observed data scale, we need to the noise arising when going from  Eq.~\ref{eq_GLMM2} to Eq.~\ref{eq_GLMM3}. We call this variance the ``distribution variance'' and it depends on a variance function $v(\ell, \bm{\theta})$ that describe the variance of the distribution $\mathcal{D}$ used\footnote{For a Binomial distribution, for example, it is equal to $g^{-1}(\ell) \left(1-g^{-1}(\ell)\right)$, similar to the classical $p (1-p)$.}:
\begin{equation}\label{eq_vardist}
V_{\text{dist}} = \int v(\ell, \bm{\theta})f_{\mathcal{N}}(\ell, \mu, V_{\text{P}, \ell})\text{d}\ell.
\end{equation}
To compute the phenotypic variance on the observed data scale, we simply need to add Eqs.~\ref{eq_phenvar_eds} and \ref{eq_vardist}:
\begin{equation}\label{eq_phenvar_obs}
V_{\text{P}, \text{obs}} = V_{\text{P}, \text{exp}} + V_{\text{dist}}.
\end{equation}
We mentioned earlier that GLMM were quite noisy models. We can see here why: on the observed data scale, we have variance arising from the latent scale that went through the link function ($V_{\text{P}, \text{exp}}$) to which we further add the distribution variance ($V_{\text{dist}}$).

\subsection{Computing the additive genetic variance and related parameters}

\paragraph{}
To compute the additive genetic variance on the observed data scale $V_{\text{A}, \text{obs}}$  from the latent scale, two things are needed: the latent additive genetic variance $V_{\text{A}, \ell}$ and a parameter called $\Psi$\footnote{This parameter can be considered as the slope of the linear regression from the latent breeding values to the breeding values on the observed data scale. For more details, see \citet{de_villemereuil_general_2016}}.
The details of $\Psi$ computation can be omitted here, but what is important to note is that, as all computations above, it depends on the whole distribution of the latent trait $\ell$.
$V_{\text{A}, \text{obs}}$ can then be computed as:
\begin{equation}\label{eq_va_obs}
 V_{\text{A}, \text{obs}} = \Psi^2 V_{\text{A}, \ell}
\end{equation}
Simple enough (if you have $\Psi$!).

\paragraph{}
Once the value for $V_{\text{A}, \text{obs}}$ and all the other parameters have been obtained, it is pretty straightforward to compute other related parameters on the observed data scale, such as the heritability:
\begin{equation}\label{eq_herit_glmm_obs}
 h^{2}_{\text{obs}} = \dfrac{V_{\text{A}, \text{obs}}}{V_{\text{P}, \text{obs}}},
\end{equation}
or the coefficient of variation:
\begin{equation}
 \text{CV}_{\text{A}, \text{obs}} = 100\dfrac{\sqrt{V_{\text{A}, \text{obs}}}}{\bar{z}},
\end{equation}
or even the closely-related evolvability:
\begin{equation}
 \text{I}_{\text{A}, \text{obs}} =\dfrac{V_{\text{A}, \text{obs}}}{\bar{z}^{2}}.
\end{equation}


\subsection{The issue of fixed effects}

\paragraph{}
Fixed-effects can be messy in GLMMs because of the non-linearity introduced by the link function. 
Indeed, when fixed-effects are introduced in the model\footnote{Others than the bare intercept $\mu$, which, for the sake of simplicity, we do not include in what we call ``fixed-effects'' here.}, they tend to have a strong effect on the shape of the latent trait distribution.
Yet, you might remember that all computations describe in Eqs.~\ref{eq_mean}--\ref{eq_va_obs} depends ultimately on the whole distribution of the latent trait.

\paragraph{}
The immediate consequence of this is that include fixed effects will have a noticeable and possibly large impact on the estimates on the observed data scale. 
To account for that, it is necessary to average over fixed-effects \citep[see][for more details]{de_villemereuil_general_2016}. QGglmm is able to do that and we will see how in the practice. 
However, it should be noted that averaging over fixed-effects can be computationally demanding, especially for large datasets, because the computation time grows roughly linearly with the sample size (i.e. computations needs to be done for \textit{each} data point). See section \ref{subsec_fixedeffects} for more information about this.

\section{Using QGglmm}

\subsection{Extracting information from the models}

\paragraph{}
As explained at the beginning of this document, QGglmm does not perform any kind of inference directly from the data. Instead, estimates from the latent scale (e.g. intercept, total variance and additive genetic variance) are its input.
This means that the package will usually be used \textit{after} some analysis using a GLMM-based software has been conducted. 

\paragraph{}
It is thus up to the user to extract these estimates from the software output and provide them to QGglmm. No automatic extraction of these estimates directly from model objects is available. This is mainly for two reasons:
\begin{itemize}
 \item There are a very large diversity of GLMM-based software out there, which makes difficult the task to implement an automatic extraction for all of them,
 \item But most importantly, every statistical design is unique, and automatic extractions can only very roughly account for them. 
 What if the user wants to discard some random effect variance from the total variance? Which variance component is the additive genetic one (e.g. for sire/dam models)? Etc...
\end{itemize}
As an illustration, we will however see how to extract estimate values from different but simple models using MCMCglmm and lme4.

\paragraph{Animal model with MCMCglmm}
Imagine we have an animal model fitted with MCMCglmm to analyse count data using a Poisson distribution. The model would be fitted using, for example, the following command:
\begin{Schunk}
 \begin{Sinput}
model <- MCMCglmm(phen ~ 1, random = ~animal,
                  pedigree = pedigree, data = data,
                  prior = prior, family = "poisson")
 \end{Sinput}
\end{Schunk}
Now, all we need is to extract, from the \texttt{model} object, the latent population mean (here, the intercept of the model), additive genetic variance and phenotypic variance:
\begin{Sinput}
mu <- mean(model[["Sol"]][ , "(Intercept)"])
va <- mean(model[["VCV"]][ , "animal"])
vp <- mean(rowSums(model[["VCV"]]))
\end{Sinput}
And that's everything that will be needed by QGglmm. For binary traits, it is not needed to add 1 (for probit link) or $\pi^{2}/3$ (for logit link)

\paragraph{Multivariate animal model with MCMCglmm}
Now, what if we wanted to fit a multivariate animal model rather than a univariate one? Something like this:
\begin{Schunk}
 \begin{Sinput}
model <- MCMCglmm(cbind(phen1, phen2) ~ trait - 1, 
                  random = ~ us(trait):animal,
                  rcov = ~us(trait):units, 
                  data = data, pedigree = pedigree,
                  family = c("ordinal", "gaussian"), 
                  prior = prior)
 \end{Sinput}
\end{Schunk}
Extracting the parameters from the \texttt{model} object is a bit more tedious here, because most of them are actually matrices and need to be re-formatted as such:
\begin{Schunk}
 \begin{Sinput}
mu <-  c(mean(model[["Sol"]][ , "traitphen1"]),
         mean(model[["Sol"]][ , "traitphen2"]))
G <- 
  matrix(c(mean(model[["VCV"]][ , "traitphen1:traitphen1.animal"]),
           mean(model[["VCV"]][ , "traitphen1:traitphen2.animal"]),
           mean(model[["VCV"]][ , "traitphen1:traitphen2.animal"]),
           mean(model[["VCV"]][ , "traitphen2:traitphen2.animal"])),
         ncol = 2)
R <- 
  matrix(c(mean(model[["VCV"]][ , "traitphen1:traitphen1.units"]),
           mean(model[["VCV"]][ , "traitphen1:traitphen2.units"]),
           mean(model[["VCV"]][ , "traitphen1:traitphen2.units"]),
           mean(model[["VCV"]][ , "traitphen2:traitphen2.units"])),
         ncol = 2)
P <- G + R
 \end{Sinput}
\end{Schunk}
Note that contrary to the command lines on the previous paragraph, those lines are quite specific to the model used: they use the name of the phenotypic variables (\texttt{phen1} and \texttt{phen2}) and the last command assumes that no random effect was included in the model. 
Should there be more random effects, their variance-covariance matrix of course need to be added up to obtain the phenotypic variance-covariance matrix \texttt{P}.


\paragraph{Sire/dam model with lme4}
Imagine now we have a sire/dam model fitted with lme4 to analyse binary data\footnote{Note that the model used here belongs to an analysis assuming that ``dam effect'' contains maternal effects but ``sire effect'' doesn't contain paternal effects.}. The model would be fitted using, for example, the following command:
\begin{Schunk}
 \begin{Sinput}
model <- glmer(phen ~ 1 + (1|sire) + (1|dam), 
	 data = data, family = binomial(link = "probit"))
 \end{Sinput}
\end{Schunk}
What we would like is to extract the intercept and variance components from the \texttt{model} object. This can be done using the following commands:
\begin{Schunk}
 \begin{Sinput}
vars <- as.data.frame(VarCorr(model))[ , c('grp', 'vcov')]
intercept <- fixef(model)['(Intercept)']
 \end{Sinput}
\end{Schunk}
Now, all is needed left is to construct the actual parameters of interest. The latent population mean is quite straightforward:
\begin{Schunk}
 \begin{Sinput}
mu <- intercept
 \end{Sinput}
\end{Schunk}
The additive genetic variance of the model is four times the sire variance and the latent phenotypic variance on the latent scale is simply the sum of the variance components:
\begin{Schunk}
 \begin{Sinput}
va <- 4 * vars[vars[["grp"]] == "sire", "vcov"]
vp <- sum(vars[, "vcov"])
 \end{Sinput}
\end{Schunk}
And just like that, we have everything required to use QGglmm!

\subsection{Using QGparams to obtain parameters on the observed data scale}

\paragraph{Getting some parameters to play with}
Let's assume we performed an analysis using any kind of GLMM software on a count trait. From this analysis, we obtain the following parameters:
\begin{Schunk}
 \begin{Sinput}
va <- 1.34
vp <- 2.13
mu <- 0.89
 \end{Sinput}
\end{Schunk}

\paragraph{Running QGparams (the easy way)}
We can use these parameters and our knowledge of the model (here a Poisson model with a log link) to compute the quantitative genetics parameters on the observed data scale using the simple following command:
\begin{Schunk}
 \begin{Sinput}
QGparams(mu = mu, var.a = va, var.p = vp, model = "Poisson.log")
 \end{Sinput}
 \begin{Soutput}
[1] "Using the closed forms for a Poisson-log model."
  mean.obs  var.obs var.a.obs    h2.obs
1 4.116486 35.59524  9.150549 0.2570723
 \end{Soutput}
\end{Schunk}
From this output, we can see different parameters on the observed phenotypic trait, i.e. the count number:
\begin{itemize}
 \item The population mean \texttt{mean.obs} of roughly of 4.1, meaning this is the average expected count number in the population.
 \item The variance \texttt{var.obs} is the total phenotypic variance of the count number in the population. It's large value (35.6) is quite typical for a Poisson/log distributed trait.
 \item The variance \texttt{var.a.obs} is the additive genetic variance of the count data.
 \item The parameter \texttt{h2.obs} is the ratio between \texttt{var.a.obs} and \texttt{var.obs}, i.e. the heritability of the count number.
\end{itemize}
If we compare the value of the latent heritability:
\begin{Schunk}
 \begin{Sinput}
va/vp
 \end{Sinput}
 \begin{Soutput}
0.5142857
 \end{Soutput}
\end{Schunk}
with the value of the heritability on the observed data scale (here 0.26), we can see that they differ greatly, and that the latter is smaller than the former. 
Though the absolute difference can vary depending on the data and model, \texttt{h2.obs} is \textit{always} expected to be smaller than the latent heritability. This is due to the added ``noise'' in GLMM models (see section \ref{subsec_QGandGLMM}).\\
Because the Poisson/log model has a closed-form solution to our framework, the computation is very quick. Some common models (e.g. binomial with logit link) do not have such solution (yet?) and for them computation is slower. You can see whether \texttt{QGparams} is using the closed forms through its verbose output:
\begin{Schunk}
 \begin{Sinput}
QGparams(mu = mu, var.a = va, var.p = vp, 
         model = "Poisson.log", closed.form = FALSE)
 \end{Sinput}
 \begin{Soutput}
[1] "Computing observed mean..."
[1] "Computing variances..."
[1] "Computing Psi..."
  mean.obs  var.obs var.a.obs    h2.obs
1 4.116486 35.59524  9.150549 0.2570723
 \end{Soutput}
\end{Schunk}
Note the longer and more verbose output than latter. Here, \texttt{QGparams} takes time (not MUCH more, but still more) to compute integrals for the mean, then variances, then Psi...\\
A last thing to note is the format of the output: \texttt{QGparams} yields one row of a \texttt{data.frame}, this will become handy in section \ref{subsec_posterior} on posterior distribution, because those rows are easily stackable.

\paragraph{List of available models}
There are quite a bunch of models that are implemented in QGglmm, for which we have coded all the functions needed for computation and the closed forms when available. When available, \texttt{QGparams} defaults to using the closed forms (as can be seen in the above paragraph). The table \ref{tab_models} lists all the currently available models and some of their characteristics.

\begin{table}
\bigcentering
\rowcolors{2}{gray!15}{}
\caption{Name, description and characteristics of the models implemented in QGglmm.}
\label{tab_models}
\small
\begin{tabular}{lm{6cm}m{1cm}m{2cm}m{4cm}}
\toprule
\headcol Name & Description & Closed form? & Extra parameter & Comment\\
\midrule
\texttt{Gaussian} & Gaussian distribution with identity link & \cmark & --- & Essentially: LMM\\
\texttt{binom1.probit} & Binomial with 1 trial and probit link & \cmark & --- & For binary trait\\
\texttt{binomN.probit} & Binomial with N trials and probit link & \cmark & \texttt{n.obs} & \texttt{n.obs} is the number of trials\\
\texttt{binom1.logit} & Binomial with 1 trial and logit link & \xmark & --- & For binary trait\\
\texttt{binomN.logit} & Binomial with N trials and logit link & \xmark & \texttt{n.obs} & \texttt{n.obs} is the number of trials\\
\texttt{Poisson.log} & Poisson distribution wiht a log link & \cmark & --- & ---\\
\texttt{Poisson.sqrt} & Poisson distribution with a square-root link & \cmark & --- & ---\\
\texttt{negbin.log} & Negative-Binomial distribution wiht a log link & \cmark & \texttt{theta} & \texttt{theta} is the overdispersion parameter\\
\texttt{negbin.sqrt} & Negative-Binomial distribution wiht a square-root link & \cmark & \texttt{theta} & \texttt{theta} is the overdispersion parameter\\
\texttt{ordinal} & Multiple threshold model for ordinal traits & \cmark & --- & See section \ref{subsec_ordinal}.\\
\bottomrule
\end{tabular}
\end{table}

\paragraph{Running QGglmm (the custom way)}
What should be done if the model you used is not in this list? Well, that means that using QGglmm is still possible but will require somewhat more efforts from \textit{your} part. Of course, if you don't need to implement your own model, you can skip this rather technical part\footnote{Though I would recommend readers to read it, as it explains how \texttt{QGparams} works ``under the hood''.}. Three things are needed:
\begin{description}
 \item[\texttt{inv.link}] The inverse function of the link function your model, i.e. if you model uses a link function $g$, you need to impute $g^{-1}$.
 \item[\texttt{var.func}] The ``variance function'' $v(\ell, \bm{\theta})$ (see Eq.~\ref{eq_vardist}), which is the function giving the variance to expect around a value for the latent trait $\ell$ given some (possibly empty!) parameter $\bm{\theta}$, assuming your custom distribution $\mathcal{D}$.
 \item[\texttt{d.inv.link}] Derivative of the inverse-link function \texttt{inv.link}, this should require little mathematical work since link functions are often relatively simple.
\end{description}
To illustrate how to compute and use those things, we will ``manually'' implement the binomial/logit model. So, the first thing is to know what the link function looks like. \href{https://en.wikipedia.org/wiki/Logit}{Wikipedia} tells us that a logit function looks like this:
\begin{equation}
 g(x) = \log\left(\frac{x}{1-x}\right)
\end{equation}
The inverse of this function is so that:
\begin{equation}
  g(g^{-1}(x)) = x = \log\left(\frac{g^{-1}(x)}{1-g^{-1}(x)}\right)
\end{equation}
A tiny bit of mathematical work gives:
\begin{equation}
  g^{-1}(x) = \dfrac{\exp(x)}{1+\exp(x)}
\end{equation}
This, is our \texttt{inv.link} function:
\begin{Schunk}
 \begin{Sinput}
inv.link <- function(x)\{exp(x)/(1+exp(x))\}
 \end{Sinput}
\end{Schunk}
Derivating this function is quite easy and gives:
\begin{equation}
  \dfrac{\text{d}g^{-1}(x)}{\text{d}x} = \dfrac{\exp(x)}{(1+\exp(x))^{2}}
\end{equation}
So, \texttt{d.inv.link} is:
\begin{Schunk}
 \begin{Sinput}
d.inv.link <- function(x)\{exp(x)/((1+exp(x))^2)\}
 \end{Sinput}
\end{Schunk}
Now, the last bit requires more thinking. The function $v(x, \bm{\theta})$ gives us the variance of the values on the observed data scale for a given latent value $x$. So, for a given latent value $x$, Eq.~\ref{eq_GLMM} tells that the distribution of the values will be:
\begin{equation}
 z|x \sim \mathcal{B}(g^{-1}(x), 1)
\end{equation}
where $\mathcal{B}(p, N)$ is the binomial distribution with probability of success $p$ and number of trials $N$ (here $N = 1$ is our general parameter $\bm{\theta}$). We know that the variance of this distribution is generally $N p (1-p)$, so in our case:
\begin{equation}
 v(x, \bm{\theta}) = g^{-1}(x) (1 - g^{-1}(x))
\end{equation}
So, we finally have \texttt{var.func}:
\begin{Schunk}
 \begin{Sinput}
var.func <- function(x)\{(exp(x)/(1+exp(x))) *
                        (1 - (exp(x)/(1+exp(x))))\}
 \end{Sinput}
\end{Schunk}
QGglmm requires that these functions are provided using a named list:
\begin{Schunk}
 \begin{Sinput}
custom.functions <- list(inv.link = inv.link,
                         var.func = var.func, 
                         d.inv.link = d.inv.link)
 \end{Sinput}
\end{Schunk}
Now, we can use our ``custom'' model in QGparams:
\begin{Schunk}
 \begin{Sinput}
QGparams(mu = 0.5, var.a = 0.5, var.p = 1,
         custom.model = custom.functions)
 \end{Sinput}
 \begin{Soutput}
[1] "Computing observed mean..."
[1] "Computing variances..."
[1] "Computing Psi..."
   mean.obs   var.obs var.a.obs     h2.obs
1 0.6020271 0.2395905 0.0197978 0.08263184
 \end{Soutput}
\end{Schunk}
which gives exactly the same output as the built-in model:
\begin{Schunk}
 \begin{Sinput}
QGparams(mu = 0.5, var.a = 0.5, var.p = 1, model = "binom1.logit")
 \end{Sinput}
 \begin{Soutput}
[1] "Computing observed mean..."
[1] "Computing variances..."
[1] "Computing Psi..."
   mean.obs   var.obs var.a.obs     h2.obs
1 0.6020271 0.2395905 0.0197978 0.08263184
 \end{Soutput}
\end{Schunk}
Surprisingly, QGglmm does not need to \textit{know} exactly which distribution you are using, and the only part where the distribution $\mathcal{D}$ (and actually, solely its variance) is used is for the computation of \texttt{var.func}.

\subsection{Using QGmvparams to obtain multivariate parameters on the observed data scale}


\paragraph{Getting some parameters to play with}
Let's assume we just performed a large multivariate quantitative genetics analysis with 3 traits, among which a binary trait (binomial/probit), a Gaussian trait and a count trait (Poisson/log).
We obtained the following parameters:
\begin{Schunk}
 \begin{Sinput}
G <- matrix(c(0.5, 0.4, 0, 0.4, 2, 0, 0, 0, 0.1), nrow = 3)
P <- matrix(c(1, 0.4, 0, 0.4, 5, 0, 0, 0, 0.5), nrow = 3)
mu <- c(-0.5, 10, 1)
 \end{Sinput}
\end{Schunk}
By looking at G, we can that the two first traits are genetically correlated, but the last one is independent from the others (on the latent scale!):
\begin{Schunk}
 \begin{Sinput}
G
 \end{Sinput}
 \begin{Soutput}
     [, 1] [, 2] [, 3]
[1, ]  0.5  0.4  0.0
[2, ]  0.4  2.0  0.0
[3, ]  0.0  0.0  0.1
 \end{Soutput}
\end{Schunk}
All the phenotypic covariance is of phenotypic origin though:
\begin{Schunk}
 \begin{Sinput}
  P - G
 \end{Sinput}
 \begin{Soutput}
     [, 1] [, 2] [, 3]
[1, ]  0.5    0  0.0
[2, ]  0.0    3  0.0
[3, ]  0.0    0  0.4
 \end{Soutput}
\end{Schunk}
If only real estimates could be that clean!

\paragraph{Running QGmvparams}
The function \texttt{QGmvparams} behave mostly the same as \texttt{QGparams}, but has a modified arguments and output to adapt to the multivariate case. For example, it requires not simply variances, but variance-covariance matrices and a vector of intercept for \texttt{mu}. It also requires that all the models used for the trait are given (as a vector):
\begin{Schunk}
 \begin{Sinput}
QGmvparams(mu = mu, vcv.G = G, vcv.P = P,
           model = c("binom1.probit", "Gaussian", "Poisson.log"))
 \end{Sinput}
 \begin{Soutput}
[1] "Computing observed mean..."
[1] "Computing variance-covariance matrix..."
[1] "Computing Psi..."
\$mean.obs
[1]  0.361887 10.000149  3.490865

\$vcv.P.obs
              [, 1]      [, 2]          [, 3]
[1, ]  0.2308944225 0.1056209 -0.0002702066
[2, ]  0.1056208909 5.2382325  0.0577576973
[3, ] -0.0002702066 0.0577577 11.3775643645

\$vcv.G.obs
           [, 1]      [, 2]     [, 3]
[1, ] 0.03511883 0.1063377 0.000000
[2, ] 0.10633770 2.0124007 0.000000
[3, ] 0.00000000 0.0000000 1.225777
 \end{Soutput}
\end{Schunk}
A few things ought to be noted here regarding this output. First, you can see that the output has substantially changed. It is not a \texttt{data.frame} any more, but a \texttt{list} object. Not as easily stackable as \texttt{data.frame}, but much more convenient to store matrices! 
Second, despite the fact that all models used here have a closed form (see Table \ref{tab_models}), \texttt{QGmvparams} seems to be doing the integral computation (see the verbose output on the three first lines).
This is because the computation for each model are not independent, so using closed forms would require to solve this particular case (binomial/probit + Gaussian + Poisson/log). 
This is much more complex than univariate models and there are so many possibilities that using closed forms for the multivariate is practically impossible. Hence \texttt{QGmvparams} \textit{always} resort to integral computations (using the \href{https://cran.r-project.org/web/packages/cubature/index.html}{cubature} package)\footnote{In previous versions, QGglmm was using R2Cuba which has been deprecated. The switch to cubature, however, allowed for using its ``vectorised'' approach which considerably improved the speed of the package: up to 50x for QGmvparams and up to x300 faster for QGmvicc!!}.\\

\paragraph{Looking closer at the estimates}
This example is interesting because it allows to see some of the peculiar stuff happening when converting from the latent to the observed data scale. Let's save the output of \texttt{QGmvparams} to study it further:
\begin{Schunk}
 \begin{Sinput}
out <- QGmvparams(mu = mu, vcv.G = G, vcv.P = P,
       model = c("binom1.probit", "Gaussian", "Poisson.log"))
 \end{Sinput}
\end{Schunk}
One interesting thing is to compare the additive genetic variance on the latent scale and on the observed data scale:
\begin{Schunk}
 \begin{Sinput}
G
out[["vcv.G.obs"]]
 \end{Sinput}
 \begin{Soutput}
     [, 1] [, 2] [, 3]
[1, ]  0.5  0.4  0.0
[2, ]  0.4  2.0  0.0
[3, ]  0.0  0.0  0.1

           [, 1]      [, 2]     [, 3]
[1, ] 0.03511883 0.1063377 0.000000
[2, ] 0.10633770 2.0124007 0.000000
[3, ] 0.00000000 0.0000000 1.225777
 \end{Soutput}
\end{Schunk}
You can see that some of the structure was kept during the transformation. For example, the last trait is still genetically independent from the others. The estimates regarding the Gaussian haven't changed much (this is because the Gaussian trait is not really ``transformed'', it is pretty much kept the same). Yet, the variances of the non-Gaussian traits changed: the first one was reduced, while the third one was increased.\\
The changes about the non-genetic part are more striking:
\begin{Schunk}
 \begin{Sinput}
P
out[["vcv.P.obs"]]
 \end{Sinput}
 \begin{Soutput}
     [, 1] [, 2] [, 3]
[1, ]  0.5    0  0.0
[2, ]  0.0    3  0.0
[3, ]  0.0    0  0.4

              [, 1]          [, 2]          [, 3]
[1, ]  0.1957755888 -0.0007168094 -0.0002702066
[2, ] -0.0007168094  3.2258318034  0.0577576973
[3, ] -0.0002702066  0.0577576973 10.1517870576
 \end{Soutput}
\end{Schunk}
whereas the variance-covariance of the non-genetic part on the latent scale is completely diagonal, this is not the case any more on the observed data scale: the second and third traits now slightly covariate whereas they were independent on the latent and are not even genetically correlated.\\
This happens because of the non-linearity of the link functions (again!) which can generate a slight covariance between traits, even if they are not correlated on the latent scale.

\subsection{Using QGpredict to obtain evolutionary prediction}

\paragraph{Why use QGpredict?}
Obtaining heritability estimates on the observed data scale is interesting because it allows to infer how of the variance of the \textit{actual} phenotypic trait is of additive genetic origin.
Yet, contrary to what happens for Gaussian traits, heritability of non-Gaussian traits is a poor predictor of the evolutionary response to selection \citep{de_villemereuil_general_2016}. This is where \texttt{QGpredict} is useful: using fitness information on the observed data scale, it allows to infer evolutionary predictions on the latent scale.

\paragraph{How does it work?}
The starting point of the approach is to have fitness information for each phenotypic category (non-Gaussian traits are most often categorical traits: dichotomies, counts, ordinal traits, etc...), or a fitness model which allows to compute the expected fitness given a latent value $\ell$:
\begin{equation}\label{eq_fit_lat}
 W_{\text{exp}}(\ell) = \sum_{k} W_{P}(k) P(Z = k|\ell),
\end{equation}
The LHS term is the sum fitness value for each possible category $k$, weighted by the probability of this category given a latent value $\ell$. Let's use a tangible example: imagine that in a population of bird composed of dispersers and non-dispersers, we are interested in the evolution of dispersal. 
We measure a fitness value (say life-time reproductive success, LRS) for each category of birds: dispersers have a LRS of 2.5 and non-dispersers have a LRS of 2.
Now, if we assume a binomial/probit model, we also know that the probability of ``success'' (here, say, of being a disperser) given a latent value $\ell$ is $g^{-1}(\ell)$ so:
\begin{equation}\label{eq_fit_lat_example}
  W_{\text{exp}}(\ell) = 2.5 g^{-1}(\ell) + 2 \left(1 - g^{-1}(\ell)\right)
\end{equation}
We will use this function to ``translate'' selection on the observed data scale (i.e. the \textit{actual} phenotype) to the latent scale (i.e. a hypothetical, but nicely behave phenotype).\\
To compute the selection gradient, we also need the derivative of the function in Eq.~\ref{eq_fit_lat}, which in our case is:
\begin{equation}\label{eq_dfit_example}
 \dfrac{\text{d}W_{\text{exp}}(\ell)}{\text{d}\ell} = 2.5 \dfrac{\text{d}g^{-1}(\ell)}{\text{d}\ell} - 2  \dfrac{\text{d}g^{-1}(\ell)}{\text{d}\ell}
\end{equation}
We will soon seen that this derivative is easy to implement in R for this particular case. This derivative is used by \texttt{QGpred} to obtain the predicted shift in the latent intercept $\mu$ due to selection:
\begin{equation}\label{eq_deltaLatent}
\Delta \mu = V_A E\left[\frac{\text{d} W_{\text{exp}}}{\text{d}\ell}\right]\frac{1}{\bar{W}}.
\end{equation}

\paragraph{Running QGpred}
To illustrate how to run \texttt{QGpred}, we will re-use the example above, with the following estimates from a GLMM binomial/probit analysis:
\begin{Schunk}
 \begin{Sinput}
va <- 0.93
vp <- 1.76
mu <- -0.5
 \end{Sinput}
\end{Schunk}
The inverse of the probit link happens to be the \href{https://en.wikipedia.org/wiki/Cumulative_distribution_function}{CDF} of a Normal distribution, so in R, Eq.~\ref{eq_fit_lat_example} is actually quite easy to write:
\begin{Schunk}
 \begin{Sinput}
fit <- function(x)\{2.5 * pnorm(x) + 2 * (1 - pnorm(x))\}
 \end{Sinput}
\end{Schunk}
The derivative of a CDF of a distribution is its \href{https://en.wikipedia.org/wiki/Probability_density_function}{PDF}, so writing Eq.~\ref{eq_dfit_example} is quite easy in R:
\begin{Schunk}
 \begin{Sinput}
d.fit <- function(x)\{2.5 * dnorm(x) - 2 * dnorm(x)\}
 \end{Sinput}
\end{Schunk}
Now, we have everything we need to run \texttt{QGpred}\footnote{One might be surprised that the model (distribution + link function) assumed is not required as an argument by \texttt{QGpred}. In fact, all the information about the model is already accounted for when we wrote \texttt{fit} and \texttt{d.fit}, nothing else about the distribution is needed.}:
\begin{Schunk}
 \begin{Sinput}
QGpred(mu = mu, var.a = va, var.p = vp,
       fit.func = fit, d.fit.func = d.fit)
 \end{Sinput}
 \begin{Soutput}
[1] "Computing mean fitness..."
[1] "Computing the latent selection and response..."
  mean.lat.fit   lat.grad    lat.sel   lat.resp
1      2.19086 0.05237713 0.09218375 0.04871073
 \end{Soutput}
\end{Schunk}
The function yields different information: \texttt{mean.lat.fit} is the mean latent fitness ($\bar{W}$ in Eq.~\ref{eq_deltaLatent}), \texttt{lat.grad} is the latent gradient of selection ($E\left[\frac{\text{d} W_{\text{exp}}}{\text{d}\ell}\right]\frac{1}{\bar{W}}$), \texttt{lat.sel} is the latent shift in the selected population and \texttt{lat.resp} is the latent response to selection, i.e. the latent shift in the next population.\\
Obtaining the response to selection on the observed data scale from there is quite straightforward using the function \texttt{QGmean} provided by the package\footnote{The \texttt{QGmean} fu}:
\begin{Schunk}
 \begin{Sinput}
delta.mu <- QGpred(mu = mu, var.a = va, var.p = vp,
                   fit.func = fit, d.fit.func = d.fit)[["lat.resp"]]
QGmean(mu = mu, var = vp,
       link.inv = QGlink.funcs("binom1.probit")[["inv.link"]])
QGmean(mu = mu+delta.mu, var = vp, 
       link.inv = QGlink.funcs("binom1.probit")[["inv.link"]])
 \end{Sinput}
 \begin{Soutput}
0.3817207
0.3929478
 \end{Soutput}
\end{Schunk}
So, despite quite a strong selection (dispersers have 25\% more offspring in their life-time than non-dispersers), we expect the proportion of dispersers to only increase of roughly 3\% from this generation to the next.

\section{Particular cases}

\subsection{Including fixed effects}
\label{subsec_fixedeffects}

\paragraph{Case study}
Imagine the phenotypic trait you are studying is the juvenile survival to a common disease. You suspect there is genetic component to it, but at the same time, you know that survival varies at look according to the nutrient intake provided by the parents, which you have a way to measure quite precisely.
One way to analyse these data is to include the nutrient intake as a fixed effect in the model, while inferring the additive genetic variance of the survival to the disease. 
Yet, as stated in section \ref{subsec_QGandGLMM}, including fixed effects in GLMM has strong consequences on the inference of quantitative genetics parameters on the observed data scale.
Fortunately, QGglmm has a way to deal with fixed effects by averaging over them: this allows to produce meaningful parameters on the observed data scale.

\paragraph{Getting the predicted values}
Using the example above, we ran an animal model in MCMCglmm like this:
\begin{Schunk}
 \begin{Sinput}
model <- MCMCglmm(phen ~ nutr, random = ~animal, 
                  pedigree = pedigree, data = data,
                  prior = prior, family = "ordinal")
 \end{Sinput}
\end{Schunk}
where \texttt{nutr} is the nutrient intake fixed effect. To account for fixed effects in \texttt{QGparams}, we need the \textit{marginal} predicted values of the model. What this means is that predicted values must be computed using only the fixed-effect part of the model, not the random part (e.g. not including the breeding values!). 
Most implementation of \texttt{predict} in R defaults to marginal prediction, and at least \texttt{predict.MCMCglmm} does, in our case.
What we also need is for predictions to be computed on the latent scale, not on the observed/expected data scale. Here, the default for \texttt{predict.MCMCglmm} does not suit us and we need to custom it a bit:
\begin{Schunk}
 \begin{Sinput}
yhat <- predict(model, type = "terms")
 \end{Sinput}
\end{Schunk}
The argument \texttt{type = "terms"} tells \texttt{predict.MCMCglmm} to compute predictions on the latent scale. This is, of course, just an example: depending on the software you are using, getting the predicted values might be totally different. The important thing is to check they are marginally computed and on the latent scale.

\paragraph{Running QGparams with fixed effects}
Once these values are obtained, running \texttt{QGparams} is pretty straightforward:
\begin{Schunk}
 \begin{Sinput}
va <- mean(model[["VCV"]][, "animal"])
vp <- mean(rowSums(model[["VCV"]]))
QGparams(predict = yhat, var.a = va, var.p = vp,
         model = "binom1.probit")
 \end{Sinput}
 \begin{Soutput}
[1] "Using the closed forms for a Binomial1-probit model."
   mean.obs   var.obs  var.a.obs   h2.obs
1 0.2896591 0.2057567 0.04275686 0.207803
 \end{Soutput}
\end{Schunk}
Note that \texttt{mu} being already accounted for in \texttt{predict}, it is not necessary any more\footnote{Actually, when using \texttt{predict}, the function makes sure that \texttt{mu} is not used at all, even it is passed as an argument!}.
The difference with the output, shouldn't we have used the \texttt{predict} argument is quite striking:
\begin{Schunk}
 \begin{Sinput}
mu <- mean(model[["Sol"]][, "(Intercept)"])
QGparams(mu = mu, var.a = va, var.p = vp, model = "binom1.probit")
 \end{Sinput}
 \begin{Soutput}
[1] "Using the closed forms for a Binomial1-probit model."
   mean.obs   var.obs  var.a.obs    h2.obs
1 0.6582622 0.2249531 0.06650048 0.2956193
 \end{Soutput}
\end{Schunk}
Admittedly, the example here was forged so that these outputs were different, but it is certainly not an unlikely one!

\subsection{Obtaining intra-class correlation (ICC) coefficients}
\label{subsec_ICC}

\paragraph{What are intra-class correlation coefficients?}
\href{https://en.wikipedia.org/wiki/Intraclass_correlation}{Intra-class correlation} (ICC) measure how much of the data belonging to a given class (e.g. individual, maternal identity, environment, etc.) resemble each other. 
In other words, it measures how much we can \textit{predict} the look of the data, simply by knowing to which class it belongs.
In LMM, formally, ICC are simply the ratio of the variance of the focus component (individuals in the case of repeatability) to the total phenotypic variance.
One famous ICC example is the repeatability. It is computed as the ratio of the variance of individual effect (say, $V_{\text{I}}$) to the phenotypic variance :
\begin{equation}
 r^{2} = \dfrac{V_{\text{I}}}{V_{\text{P}}},
\end{equation}
and quantify how consecutive measurements from the same individual are similar to each other.
As yet another example, the heritability can be considered as an ICC measuring how much we can \textit{predict} the phenotype, using e.g. relatedness data.

\paragraph{What about GLMM?}
As always, the situation is more complex in GLMM. 
First, computing the variance component on the observed data scale (i.e. for the actual phenotype) is even more complex that computing the additive genetic variance on this scale \citep{de_villemereuil_general_2016}.
Second, the link between heritability and ICC is blurred. Narrow-sense heritability on the observed data scale can no longer be considered an ICC. Broad-sense heritability can be computed as an ICC on that level, but it contains some non-additive genetic variance.

\paragraph{Case study}
Let's say we have multiple individual measurement of a count data set and performed a Poisson/log GLMM using ``individual'' as a random effect beside the additive genetic one. We obtained the following estimates:
\begin{Schunk}
 \begin{Sinput}
mu <- 1
vi <- 0.5	#Individual-effect variance
va <- 0.3	#Additive genetic variance
vp <- 1
 \end{Sinput}
\end{Schunk}
Now, what we would like to know is, how are measures repeatable on the observed scale? To do so, we will use the function \texttt{QGicc}.

\paragraph{Running QGicc}
Running \texttt{QGicc} is very similar to running \texttt{QGparams}:
\begin{Schunk}
 \begin{Sinput}
QGicc(mu = mu, var.comp = vi + va, var.p = vp, model = "Poisson.log")
 \end{Sinput}
 \begin{Soutput}
[1] "Using the closed forms for a Poisson-log model."
  mean.obs var.obs var.comp.obs   icc.obs
1 4.481689 38.9943     24.61565 0.6312627
 \end{Soutput}
\end{Schunk}
Just as \texttt{QGparams}, \texttt{QGicc} returns the population mean and phenotypic variance that helps to put estimates in context. The parameter \texttt{var.comp.obs} is the component variance (here the individual-effect variance) on the observed data scale and \texttt{icc.obs} is the ratio of this variance component to the phenotypic variance on the observed data scale.

\paragraph{Some characteristics and other features}
As said above, computing variance component on the observed data scale is a bit complex. In general, it requires the use of a double integrate, which can sometimes take times. Closed forms are available only for Poisson/log and Negative-Binomial/log models. 
Binomial/probit models uses a semi-closed form, meaning that a close-form is known for one of the integral, but not the other, so the computation is much faster than we using a double integral, but still slower than when using a fully closed-form.
Basically, \texttt{QGicc} has all the features \texttt{QGparams} has: fixed-effects can be accounted for using the \texttt{predict} function and it has a multivariate counter-part \texttt{QGmvicc} which yields variance-covariance matrix on the observed data scale. Note that this multivariate function, like \texttt{QGmvparams} never uses closed forms. As a consequence, because of the double integration, it is the slowest function of the package\footnote{Note that when QGglmm switched to cubature, the speed of this function was increased by more than x300, meaning a computation of 25 minutes in the old version now takes... 4 seconds. If you were annoyed by its slugginess, I encourage you to give it another try now!}!\\
Finally, note that the ``ordinal'' model cannot be used with \texttt{QGicc} due to its complexity and lack of closed forms for ICC.


\subsection{Integrating over a posterior prediction}
\label{subsec_posterior}

\paragraph{Why integrate over a posterior distribution?}
When using a Bayesian implementation of a GLMM (e.g. MCMCglmm), we obtain posterior distributions, rather than point estimates for the parameters on the latent scale. 
The nice thing about posterior distributions is that they convey a very complex information and yet are quite easy to handle for further transformation of the inference (especially with sampling algorithms such as MCMC). For example, the posterior distribution of heritability is easily computed from a MCMCglmm output as:
\begin{Schunk}
 \begin{Sinput}
h2.post <- model[["VCV"]][, "animal"] / rowSums(model[["VCV"]])
 \end{Sinput}
\end{Schunk}
We can then study directly the shape of \texttt{h2.post}, e.g. to determine whether it is different from 0 or not.

\paragraph{Can this be done with QGparams?}
Absolutely. Recall that the output of \texttt{QGparams} is a row of a \texttt{data.frame}, which are easily stackable. The only tricky part is to create a \texttt{data.frame} to stock our model output, because it's easier to deal with:
\begin{Schunk}
 \begin{Sinput}
df <- data.frame(mu = as.vector(model[["Sol"]][, "(Intercept)"]),
                 va = as.vector(model[["VCV"]][, "animal"]),
                 vp = rowSums(model[["VCV"]]))
head(df)
 \end{Sinput}
 \begin{Soutput}
         mu       va       vp
1 0.7329956 1.715276 2.715276
2 0.7444525 1.783855 2.783855
3 0.7700467 1.707488 2.707488
4 0.6952074 1.728199 2.728199
5 0.4953782 2.012740 3.012740
6 0.4433023 1.448746 2.448746
 \end{Soutput}
\end{Schunk}
Then, we use \texttt{apply} to go through this \texttt{data.frame} and ``stack'' our output as one \texttt{data.frame} with \texttt{do.call("rbind", ...)}:
\begin{Schunk}
 \begin{Sinput}
post <- do.call("rbind", apply(df, 1, function(row)\{
            QGparams(mu = row[["mu"]],
                     var.a = row[["va"]],
                     var.p = row[["vp"]],
                     model = "binom1.probit", verbose = FALSE)
        \}))
head(post)
 \end{Sinput}
 \begin{Soutput}
     mean.obs   var.obs  var.a.obs    h2.obs
va  0.6481320 0.2280569 0.06358546 0.2788140
va1 0.6490326 0.2277893 0.06480902 0.2845130
va2 0.6553937 0.2258528 0.06246510 0.2765744
va3 0.6405957 0.2302328 0.06480583 0.2814795
va4 0.5976603 0.2404625 0.07509439 0.3122915
va5 0.5943345 0.2411010 0.06315448 0.2619420
 \end{Soutput}
\end{Schunk}
Now, you have the posterior distribution of all the parameters on the observed data scale.

\paragraph{Can this be done with QGmvparams?}
Absolutely. But it does require a bit more work. The best way to go about it\footnote{At least from the top of my head, but you can have your own --possibly better-- strategy of course!} is to create a large data.frame for which each element corresponds to one iteration, and which will contain all latent parameters:
\begin{Schunk}
 \begin{Sinput}
df <- cbind(mu1 = model[["Sol"]][, "traitphen1"],
            mu2 = model[["Sol"]][, "traitphen2"], 
            model[["VCV"]])
 \end{Sinput}
\end{Schunk}
Now, all we need to do is construct the matrix ``on the fly'' before calling \texttt{QGmvparams}:
\begin{Schunk}
 \begin{Sinput}
post <- apply(df, 1, function(row) \{
  mu <- c(row["mu1"], row["mu2"])
  G <- matrix(c(row["traitphen1:traitphen1.animal"],
                row["traitphen1:traitphen2.animal"],
                row["traitphen1:traitphen2.animal"],
                row["traitphen2:traitphen2.animal"]),
                ncol = 2)
  R <- matrix(c(row["traitphen1:traitphen1.units"],
                row["traitphen1:traitphen2.units"],
                row["traitphen1:traitphen2.units"],
                row["traitphen2:traitphen2.units"]),
                ncol = 2)
  P <- G + R
  QGmvparams(mu = mu, vcv.G = G, vcv.P = P,
       model = c("binom1.probit", "Gaussian"), verbose = FALSE)
\})
 \end{Sinput}
\end{Schunk}
Of course, all names (``phen1'', ``phen2'', etc.) should be changed to fit your actual code, as should your selection of models in QGmvparams.

\subsection{The special case of ordinal data}
\label{subsec_ordinal}

\paragraph{What is an ordinal trait?}
An ordinal trait is a categorical trait for which the categories have a meaningful order\footnote{Though binary traits are a special case of ordinal trait, they are excluded here for two reasons. First, they are a very peculiar, degenerate kind of ordinal trait. Second, the core function of QGglmm can deal with them as binomial traits much efficiently.}. Think about, for example, a morphological trait categorised as ``small'', ``intermediate'' and ``large'' or a disease which could manifest a ``asymptomatic'', ``unwell'' and ``severe''. It is pretty clear that these categories are ordered and what the order is (whether you begin by small or large doesn't really matter).

\paragraph{How are these traits studied?}
The most common mod	el to study those traits in quantitative genetics is called the \textit{multiple threshold model}. In this model, a Gaussian variable (the ``liability'') is cut into separate parts by cut-points (or thresholds) corresponding to each categories (see Fig.~\ref{fig_threshold}), e.g. defining their relative proportions. Because of unidentifiability issues, one of the cut-points (or the intercept $\mu$) has to be arbitrarily set. Thus, most often, the first cut-point is set to be 0 (see Fig.~\ref{fig_threshold}).

\begin{figure}
 \centering
 \includegraphics[width = 0.8\textwidth]{Figs/threshold.pdf}
 \caption{A schematic representation of the multiple threshold model using the example of the ``small'', ``intermediate'' and ``large'' categories. The area under the curve shows the relative proportions of each category: here ``small'' would be the rarest one.}
 \label{fig_threshold}
\end{figure}

\paragraph{The GLMM specification}
In the GLMM realm, this model can be translated as a multionial/probit model where the probit link is a bit peculiar: it is ``sliced'' according to the different cut-points (hereafter $\gamma_i$), corresponding to the multiple thresholds. 
As a consequence, the link function outputs a vector containing the relative probability for each category, all of which sum up to 1. This vector is then used to sample a (unique) value in a multinomial distribution:
\begin{subequations}
 \begin{equation}
  \bm{\ell} = \mu+\mathbf{X}\mathbf{b}+ \mathbf{Z_a}\mathbf{a} + \mathbf{Z_1}\mathbf{u_{1}} + ... + \mathbf{Z}_k\mathbf{u_{k}} + \mathbf{o}
 \end{equation}
\begin{equation}
  \bm{p}_{i}(\bm{\ell}) = \Phi(\gamma_{i} - \bm{\ell}) - \Phi(\gamma_{i-1} - \bm{\ell})
\end{equation}
\begin{equation}
  \bm{Z} \sim \text{Multinom}(\bm{p}_{1}, ... , \bm{p}_{K})
\end{equation}
\end{subequations}
where $\Phi$ is a standard Normal CDF (inverse of the probit link) and $K$ the number of categories. Note that the equations above suppose that there are two ``extreme'' cut-points $-\infty$ and $\infty$.
Something important to note here is that $\bm{Z}$ is a matrix of $K$ rows and as many columns as there are individuals. Each column has 1 for the expressed phenotypic category and 0 elsewhere.
As a consequence, despite the latent being univariate, the observed data scale is actually multivariate and of dimension $K$!

\paragraph{Case study}
Let's assume you have a phenotypic trait with 3 categories (small, intermediate, large). You want to study the quantitative genetics behind this trait and run a multinomial GLMM for this\footnote{Note that the package MCMCglmm has both the ``multinomial'' and ``ordinal'' models. The former one actually uses a logit link, which is not implemented in QGglmm (yet?), while the latter one corresponds to the model described here.}. You obtain the following parameters:
\begin{Schunk}
 \begin{Sinput}
mu <- 1.5
va <- 0.5
vp <- 1
cp <- c(0, 2) # Estimated cut-points
 \end{Sinput}
\end{Schunk}

\paragraph{An illustrative simulation}
To fully understand the model and what these parameters stand for, let's simulate a few data point according to them. First, let's fix a few things:
\begin{Schunk}
 \begin{Sinput}
# Number of simulated individuals
N <- 10
# All cut-points including the infinite extremes
g <- c(-Inf, cp, Inf)
 \end{Sinput}
\end{Schunk}
Now, we can proceed. The latent values are pretty straightforward, as always:
\begin{Schunk}
 \begin{Sinput}
l <- mu + rnorm(N, 0, sqrt(va)) + rnorm(N, 0, sqrt(vp-va))
l
 \end{Sinput}
 \begin{Soutput}
[1] 1.3991485 1.4866290 1.7736644 0.9845936 1.3013626 1.5379076 3.4074896
[8] 0.7511216 0.4951887 3.3479212
 \end{Soutput}
\end{Schunk}
As we can see, \texttt{l} is just a vector containing 10 values (one for each simulated individual). Now, the complicated part is to use the ``sliced'' probit:
\begin{Schunk}
 \begin{Sinput}
p = matrix(0, ncol = N, nrow = 3)
for (i in 1:3) \{
  p[i, ] =  pnorm(g[i + 1] - l) - pnorm(g[i] - l)
\}
p
 \end{Sinput}
 \begin{Soutput}
      [, 1]       [, 2]       [, 3]      [, 4]       [, 5]      [, 6]
[1, ] 0.08088423 0.06855641 0.03805934 0.1624119 0.09656718 0.0620356
[2, ] 0.64514632 0.62759767 0.55147046 0.6826321 0.66104348 0.6159569
[3, ] 0.27396945 0.30384592 0.41047020 0.1549561 0.24238933 0.3220075
      [, 7]      [, 8]      [, 9]        [, 10]
[1, ] 0.000327817 0.2262897 0.3102334 0.0004071008
[2, ] 0.079313308 0.6678555 0.6235802 0.0884347631
[3, ] 0.920358875 0.1058548 0.0661863 0.9111581361
 \end{Soutput}
\end{Schunk}
We can see that for each of the ten individuals, we obtain the probabilities to belong to each of the category (first row is small, etc.). We can also see the relationship between the latent values \texttt{l} and the probabilities in \texttt{p}. For example, the 7th and 10th values in \texttt{l} are quite large:
\begin{Schunk}
 \begin{Sinput}
l[c(7, 10)]
 \end{Sinput}
 \begin{Soutput}
[1] 3.407490 3.347921
 \end{Soutput}
\end{Schunk}
leading to very strong probabilities to belong to the last category:
\begin{Schunk}
 \begin{Sinput}
p[, c(7, 10)]
 \end{Sinput}
 \begin{Soutput}
            [, 1]         [, 2]
[1, ] 0.000327817 0.0004071008
[2, ] 0.079313308 0.0884347631
[3, ] 0.920358875 0.9111581361
 \end{Soutput}
\end{Schunk}
Finally, we can use the multinomial distribution to sample the actual phenotypic category of the individuals given these probabilities:
\begin{Schunk}
 \begin{Sinput}
z <- apply(p, 2, function(vec) \{
  vec <- as.vector(vec)
  rmultinom(1, size = 1, prob = vec)
\})
z
 \end{Sinput}
 \begin{Soutput}
     [, 1] [, 2] [, 3] [, 4] [, 5] [, 6] [, 7] [, 8] [, 9] [, 10]
[1, ]    0    0    0    0    0    0    0    0    0     0
[2, ]    0    0    0    1    1    0    0    1    1     0
[3, ]    1    1    1    0    0    1    1    0    0     1
 \end{Soutput}
\end{Schunk}
Individuals with 1 on row 1 (here none) have a phenotype ``small'', those with 1 on row 2 have a phenotype ``intermediate'' and those with 1 on row 3 have a phenotype ``large''.

\paragraph{Running QGparams for ordinal traits}
Running \texttt{QGparams} for ordinal is actually quite easy, yet the output can be surprising:
\begin{Schunk}
 \begin{Sinput}
out <- QGparams(mu = mu, var.a = va, var.p = vp,
                model = "ordinal", cut.points = c(-Inf, cp, Inf))
out
 \end{Sinput}
 \begin{Soutput}
\$mean.obs
[1] 0.1444222 0.4937410 0.3618368

\$vcv.P.obs
            [, 1]        [, 2]        [, 3]
[1, ]  0.12356442 -0.07130715 -0.05225726
[2, ] -0.07130715  0.24996083 -0.17865367
[3, ] -0.05225726 -0.17865367  0.23091093

\$vcv.G.obs
             [, 1]         [, 2]        [, 3]
[1, ]  0.012917511  0.008379864 -0.02129738
[2, ]  0.008379864  0.005436196 -0.01381606
[3, ] -0.021297376 -0.013816061  0.03511344

\$h2.obs
[1] 0.10454071 0.02174819 0.15206485
 \end{Soutput}
\end{Schunk}
Despite being a univariate analysis, the output is a multivariate one. It is a \texttt{list}, not a \texttt{data.frame} and contains variance-covariance matrices and not variances. Also, it contains one heritability estimate for each category.
Importantly, the G-matrix on the observed data scale is a $K \times K$ matrix, but has only one axis of variation:
\begin{Schunk}
 \begin{Sinput}
# Only 1 non-null eigen value
eigen(cov2cor(out[["vcv.G.obs"]]))[["values"]]
 \end{Sinput}
 \begin{Soutput}
[1] 3.000000e+00 8.881784e-16 0.000000e+00
 \end{Soutput}
\end{Schunk}


\bibliography{Vignette}
\bibliographystyle{perso_sorted_en}

\end{document}
