% Created 2024-05-12 Sun 23:07
% Intended LaTeX compiler: pdflatex
\documentclass[12pt]{article}

%%%% settings when exporting code %%%% 

\usepackage{listings}
\lstdefinestyle{code-small}{
backgroundcolor=\color{white}, % background color for the code block
basicstyle=\ttfamily\small, % font used to display the code
commentstyle=\color[rgb]{0.5,0,0.5}, % color used to display comments in the code
keywordstyle=\color{black}, % color used to highlight certain words in the code
numberstyle=\ttfamily\tiny\color{gray}, % color used to display the line numbers
rulecolor=\color{black}, % color of the frame
stringstyle=\color[rgb]{0,.5,0},  % color used to display strings in the code
breakatwhitespace=false, % sets if automatic breaks should only happen at whitespace
breaklines=true, % sets automatic line breaking
columns=fullflexible,
frame=single, % adds a frame around the code (non,leftline,topline,bottomline,lines,single,shadowbox)
keepspaces=true, % % keeps spaces in text, useful for keeping indentation of code
literate={~}{$\sim$}{1}, % symbol properly display via latex
numbers=none, % where to put the line-numbers; possible values are (none, left, right)
numbersep=10pt, % how far the line-numbers are from the code
showspaces=false,
showstringspaces=false,
stepnumber=1, % the step between two line-numbers. If it's 1, each line will be numbered
tabsize=1,
xleftmargin=0cm,
emph={anova,apply,class,coef,colnames,colNames,colSums,dim,dcast,for,ggplot,head,if,ifelse,is.na,lapply,list.files,library,logLik,melt,plot,require,rowSums,sapply,setcolorder,setkey,str,summary,tapply},
aboveskip = \medskipamount, % define the space above displayed listings.
belowskip = \medskipamount, % define the space above displayed listings.
lineskip = 0pt} % specifies additional space between lines in listings
\lstset{style=code-small}
%%%% packages %%%%%

\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage{textcomp}
\usepackage{color}
\usepackage{graphicx}
\usepackage{grffile}
\usepackage{wrapfig}
\usepackage{rotating}
\usepackage{longtable}
\usepackage{multirow}
\usepackage{multicol}
\usepackage{changes}
\usepackage{pdflscape}
\usepackage{geometry}
\usepackage[normalem]{ulem}
\usepackage{amssymb}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{dsfont}
\usepackage{array}
\usepackage{ifthen}
\usepackage{hyperref}
\usepackage{natbib}
\RequirePackage{setspace} % to modify the space between lines - incompatible with footnote in beamer
\renewcommand{\baselinestretch}{1.1}
\geometry{a4paper, left=10mm, right=10mm, top=10mm}
\usepackage{titlesec}
\usepackage{etoolbox}

\makeatletter
\patchcmd{\ttlh@hang}{\parindent\z@}{\parindent\z@\leavevmode}{}{}
\patchcmd{\ttlh@hang}{\noindent}{}{}{}
\makeatother
\RequirePackage{colortbl} % arrayrulecolor to mix colors
\definecolor{myorange}{rgb}{1,0.2,0}
\definecolor{mypurple}{rgb}{0.7,0,8}
\definecolor{mycyan}{rgb}{0,0.6,0.6}
\newcommand{\lightblue}{blue!50!white}
\newcommand{\darkblue}{blue!80!black}
\newcommand{\darkgreen}{green!50!black}
\newcommand{\darkred}{red!50!black}
\definecolor{gray}{gray}{0.5}
\hypersetup{
citecolor=[rgb]{0,0.5,0},
urlcolor=[rgb]{0,0,0.5},
linkcolor=[rgb]{0,0,0.5},
}
\newenvironment{note}{\small \color{gray}\fontfamily{lmtt}\selectfont}{\par}
\newenvironment{activity}{\color{orange}\fontfamily{qzc}\selectfont}{\par}
\RequirePackage{pifont}
\RequirePackage{relsize}
\newcommand{\Cross}{{\raisebox{-0.5ex}%
{\relsize{1.5}\ding{56}}}\hspace{1pt} }
\newcommand{\Valid}{{\raisebox{-0.5ex}%
{\relsize{1.5}\ding{52}}}\hspace{1pt} }
\newcommand{\CrossR}{ \textcolor{red}{\Cross} }
\newcommand{\ValidV}{ \textcolor{green}{\Valid} }
\usepackage{stackengine}
\usepackage{scalerel}
\newcommand\Warning[1][3ex]{%
\renewcommand\stacktype{L}%
\scaleto{\stackon[1.3pt]{\color{red}$\triangle$}{\tiny\bfseries !}}{#1}%
\xspace
}
\RequirePackage{fancyvrb}
\DefineVerbatimEnvironment{verbatim}{Verbatim}{fontsize=\small,formatcom = {\color[rgb]{0.5,0,0}}}
\definecolor{grayR}{HTML}{8A8990}
\definecolor{grayL}{HTML}{C4C7C9}
\definecolor{blueM}{HTML}{1F63B5}
\newcommand{\Rlogo}[1][0.07]{
\begin{tikzpicture}[scale=#1]
\shade [right color=grayR,left color=grayL,shading angle=60]
(-3.55,0.3) .. controls (-3.55,1.75)
and (-1.9,2.7) .. (0,2.7) .. controls (2.05,2.7)
and (3.5,1.6) .. (3.5,0.3) .. controls (3.5,-1.2)
and (1.55,-2) .. (0,-2) .. controls (-2.3,-2)
and (-3.55,-0.75) .. cycle;

\fill[white]
(-2.15,0.2) .. controls (-2.15,1.2)
and (-0.7,1.8) .. (0.5,1.8) .. controls (2.2,1.8)
and (3.1,1.2) .. (3.1,0.2) .. controls (3.1,-0.75)
and (2.4,-1.45) .. (0.5,-1.45) .. controls (-1.1,-1.45)
and (-2.15,-0.7) .. cycle;

\fill[blueM]
(1.75,1.25) -- (-0.65,1.25) -- (-0.65,-2.75) -- (0.55,-2.75) -- (0.55,-1.15) --
(0.95,-1.15)  .. controls (1.15,-1.15)
and (1.5,-1.9) .. (1.9,-2.75) -- (3.25,-2.75)  .. controls (2.2,-1)
and (2.5,-1.2) .. (1.8,-0.95) .. controls (2.6,-0.9)
and (2.85,-0.35) .. (2.85,0.2) .. controls (2.85,0.7)
and (2.5,1.2) .. cycle;

\fill[white]  (1.4,0.4) -- (0.55,0.4) -- (0.55,-0.3) -- (1.4,-0.3).. controls (1.75,-0.3)
and (1.75,0.4) .. cycle;

\end{tikzpicture}
}
\RequirePackage{epstopdf} % to be able to convert .eps to .pdf image files
\RequirePackage{capt-of} %
\RequirePackage{caption} % newlines in graphics
\RequirePackage{tikz-cd} % graph
\RequirePackage{booktabs} % for nice lines in table (e.g. toprule, bottomrule, midrule, cmidrule)
\RequirePackage{amsmath}
\RequirePackage{algorithm}
\RequirePackage[noend]{algpseudocode}
\RequirePackage{dsfont}
\RequirePackage{amsmath,stmaryrd,graphicx}
\RequirePackage{prodint} % product integral symbol (\PRODI)
\usepackage{ifthen}
\usepackage{xifthen}
\usepackage{xargs}
\usepackage{xspace}
\newcommand\defOperator[7]{%
\ifthenelse{\isempty{#2}}{
\ifthenelse{\isempty{#1}}{#7{#3}#4}{#7{#3}#4 \left#5 #1 \right#6}
}{
\ifthenelse{\isempty{#1}}{#7{#3}#4_{#2}}{#7{#3}#4_{#1}\left#5 #2 \right#6}
}
}
\newcommand\defUOperator[5]{%
\ifthenelse{\isempty{#1}}{
#5\left#3 #2 \right#4
}{
\ifthenelse{\isempty{#2}}{\underset{#1}{\operatornamewithlimits{#5}}}{
\underset{#1}{\operatornamewithlimits{#5}}\left#3 #2 \right#4}
}
}
\newcommand{\defBoldVar}[2]{
\ifthenelse{\equal{#2}{T}}{\boldsymbol{#1}}{\mathbf{#1}}
}
\newcommandx\Esp[2][1=,2=]{\defOperator{#1}{#2}{E}{}{\lbrack}{\rbrack}{\mathbb}}
\newcommandx\Prob[2][1=,2=]{\defOperator{#1}{#2}{P}{}{\lbrack}{\rbrack}{\mathbb}}
\newcommandx\Qrob[2][1=,2=]{\defOperator{#1}{#2}{Q}{}{\lbrack}{\rbrack}{\mathbb}}
\newcommandx\Var[2][1=,2=]{\defOperator{#1}{#2}{V}{ar}{\lbrack}{\rbrack}{\mathbb}}
\newcommandx\Cov[2][1=,2=]{\defOperator{#1}{#2}{C}{ov}{\lbrack}{\rbrack}{\mathbb}}
\newcommandx\Binom[2][1=,2=]{\defOperator{#1}{#2}{B}{}{(}{)}{\mathcal}}
\newcommandx\Gaus[2][1=,2=]{\defOperator{#1}{#2}{N}{}{(}{)}{\mathcal}}
\newcommandx\Wishart[2][1=,2=]{\defOperator{#1}{#2}{W}{ishart}{(}{)}{\mathcal}}
\newcommandx\Likelihood[2][1=,2=]{\defOperator{#1}{#2}{L}{}{(}{)}{\mathcal}}
\newcommandx\logLikelihood[2][1=,2=]{\defOperator{#1}{#2}{\ell}{}{(}{)}{}}
\newcommandx\Information[2][1=,2=]{\defOperator{#1}{#2}{I}{}{(}{)}{\mathcal}}
\newcommandx\Hessian[2][1=,2=]{\defOperator{#1}{#2}{H}{}{(}{)}{\mathcal}}
\newcommandx\Score[2][1=,2=]{\defOperator{#1}{#2}{S}{}{(}{)}{\mathcal}}
\newcommandx\Vois[2][1=,2=]{\defOperator{#1}{#2}{V}{}{(}{)}{\mathcal}}
\newcommandx\IF[2][1=,2=]{\defOperator{#1}{#2}{IF}{}{(}{)}{\mathcal}}
\newcommandx\Ind[1][1=]{\defOperator{}{#1}{1}{}{(}{)}{\mathds}}
\newcommandx\Max[2][1=,2=]{\defUOperator{#1}{#2}{(}{)}{min}}
\newcommandx\Min[2][1=,2=]{\defUOperator{#1}{#2}{(}{)}{max}}
\newcommandx\argMax[2][1=,2=]{\defUOperator{#1}{#2}{(}{)}{argmax}}
\newcommandx\argMin[2][1=,2=]{\defUOperator{#1}{#2}{(}{)}{argmin}}
\newcommandx\cvD[2][1=D,2=n \rightarrow \infty]{\xrightarrow[#2]{#1}}
\newcommandx\Hypothesis[2][1=,2=]{
\ifthenelse{\isempty{#1}}{
\mathcal{H}
}{
\ifthenelse{\isempty{#2}}{
\mathcal{H}_{#1}
}{
\mathcal{H}^{(#2)}_{#1}
}
}
}
\newcommandx\dpartial[4][1=,2=,3=,4=\partial]{
\ifthenelse{\isempty{#3}}{
\frac{#4 #1}{#4 #2}
}{
\left.\frac{#4 #1}{#4 #2}\right\rvert_{#3}
}
}
\newcommandx\dTpartial[3][1=,2=,3=]{\dpartial[#1][#2][#3][d]}
\newcommandx\ddpartial[3][1=,2=,3=]{
\ifthenelse{\isempty{#3}}{
\frac{\partial^{2} #1}{\partial #2^2}
}{
\frac{\partial^2 #1}{\partial #2\partial #3}
}
}
\newcommand\Real{\mathbb{R}}
\newcommand\Rational{\mathbb{Q}}
\newcommand\Natural{\mathbb{N}}
\newcommand\trans[1]{{#1}^\intercal}%\newcommand\trans[1]{{\vphantom{#1}}^\top{#1}}
\newcommand{\independent}{\mathrel{\text{\scalebox{1.5}{$\perp\mkern-10mu\perp$}}}}
\newcommand\half{\frac{1}{2}}
\newcommand\normMax[1]{\left|\left|#1\right|\right|_{max}}
\newcommand\normTwo[1]{\left|\left|#1\right|\right|_{2}}
\newcommand\Veta{\boldsymbol{\eta}}
\newcommand{\Model}{\mathcal{M}}
\newcommand{\ModelHat}{\widehat{\mathcal{M}}}
\newcommand{\param}{\Theta}
\newcommand{\paramHat}{\widehat{\param}}
\newcommand{\paramCon}{\widetilde{\param}}
\newcommand{\Vparam}{\boldsymbol{\param}}
\newcommand{\VparamT}{\Vparam_0}
\newcommand{\VparamHat}{\boldsymbol{\paramHat}}
\newcommand{\VparamCon}{\boldsymbol{\paramCon}}
\newcommand{\X}{X}
\newcommand{\x}{x}
\newcommand{\VX}{\boldsymbol{X}}
\newcommand{\Vx}{\boldsymbol{x}}
\newcommand{\Y}{Y}
\newcommand{\y}{y}
\newcommand{\VY}{\boldsymbol{Y}}
\newcommand{\Vy}{\boldsymbol{y}}
\newcommand{\Vvarepsilon}{\boldsymbol{\varepsilon}}
\author{Brice Ozenne}
\date{\today}
\title{Overview of the package LMMstar}
\hypersetup{
 colorlinks=true,
 pdfauthor={Brice Ozenne},
 pdftitle={Overview of the package LMMstar},
 pdfkeywords={},
 pdfsubject={},
 pdfcreator={Emacs 27.1 (Org mode 9.4.6)},
 pdflang={English}
 }
\begin{document}

\maketitle
This vignette describes the main functionalities of the \textbf{LMMstar}
package. This package implements specific types of linear mixed
models, mainly useful when having repeated observations over a
discrete variable: \(\VY=(Y_1,\ldots,Y_T)\) where \(T\) can be
for example be time (chronological ordering of the repetitions) or
brain region (arbitrary ordering of the repetitions). Denoting by
\(\VX\) the associated covariates and \(\boldsymbol{\varepsilon} =
(\varepsilon_1,\ldots,\varepsilon_T)\), the model can be written:
\[ \VY = \VX \beta + \boldsymbol{\varepsilon} \text{ where } \varepsilon \sim \Gaus(0,\Omega) \]
where \(\beta\) are the mean parameters and the residual
variance-covariance matrix, \(\Omega\), depends on a set of
variance-covariance parameters (say \(\gamma\)) distinct of
\(\beta\). Key assumptions are:
\begin{itemize}
\item we observe \(n\) independent replicates of
\(\mathcal{O}=(\VY,\VX)\), i.e. at the cluster level,
observations \(\left(\mathcal{O}_1,\ldots,\mathcal{O}_n\right)\) are
independent. The replicates should also be identically distributed
up to a categorical variable (called strata variable in the following).
\item the residual variance is independent of the mean value.
\end{itemize}
Additional assumptions are necessary in presence of missing values,
typically correct specification of the conditional mean to have
consistent estimates of the mean parameters. This case will sometimes
be examplified by considering that only last outcome may be missing:
the conditional mean \(\Esp[Y_T|Y_1,Y_2,\ldots,Y_{T-1}]\) is then
abreviated as \(\Esp[Y_T|Y_{T-1}]\). Note that we do not require the
residuals to be normally distributed to have valid estimates or
statistical inference in large samples.

\bigskip

To get start, one should load the \textbf{LMMstar} package in the \Rlogo session:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
library(LMMstar)
\end{lstlisting}

This package is under active development. Newer package versions may
include additional functionalities and fix previous bugs. The version
of the package that is being used for this overview is:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
utils::packageVersion("LMMstar")
\end{lstlisting}

\begin{verbatim}
[1] ‘1.1.0’
\end{verbatim}


It is recommanded to also the following packages, as some of the
methods implemented in the package are relative to a generic method
implmented in other packages:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
library(ggplot2) ## autoplot method
library(nlme) ## ranef method
library(lava) ## iid, information, manifest methods
\end{lstlisting}

\clearpage

The user interface of the \textbf{LMMstar} package is made of the following
functions:
\begin{itemize}
\item functions to describe or visualize the dataset: 
\begin{itemize}
\item \texttt{scatterplot} to visualize the marginal and bivariate distribution of continuous variables.
\item \texttt{summarize} to compute summary statistics, possibly stratified on a categorical variable.
\item \texttt{summarizeNA} to identify missing data patterns.
\item \texttt{partialCor} to compute partial correlation between two variables.
\end{itemize}
\item the function \texttt{mt.test} to perform multiple Student's t-Tests and
adjust the results for multiple testing.
\item the function \texttt{lmm} is the main function of the package which fits
linear mixed models. The user can interact with \emph{lmm} objects using:
\begin{itemize}
\item \texttt{anova} to perform Wald tests, i.e. test linear combinations of
coefficients (\(\widehat{\beta}_1+\widehat{\beta}_2=0\) or
\(\widehat{\beta}_1=\widehat{\beta}_2=0\)). The output obtained
with different \texttt{lmm} can be combined using \texttt{rbind}.
\item \texttt{coef} to extract the estimated model parameters (\(\widehat{\beta}\) and possibly \(\widehat{\gamma}\)).
\item \texttt{confint} to extract the estimates with their confidence intervals.
\item \texttt{effects} to evaluate marginal effects, e.g. \(\Esp\left[\Esp[Y|X_1=1]-\Esp[Y|X_1=0]\right]\) when \(\VX=(X_1,X_2)\).
\item \texttt{estimate} to test non-linear combinations of coefficients (Wald test via a first order delta method, e.g. \(\widehat{\beta}_1/\widehat{\beta}_2=1\)).
\item \texttt{fitted} to output the fitted mean (\(X\widehat{\beta}\)) or the
conditional mean for observations with missing outcome
(e.g. \(X\widehat{\beta} +
      \widehat{\Esp}[\varepsilon_T|\varepsilon_{-T}]\)).
\item \texttt{iid} to extract the influence function of the estimated
parameters (\(\varphi\)), which satisfies \newline
\(\sqrt{n}(\widehat{\beta}-\beta) = \frac{1}{\sqrt{n}}
      \sum_{i=1}^n \varphi\left(\mathcal{O}_i\right) +o_p(1)\)
\item \texttt{levels} to extract the reference level for the mean structure.
(i.e. what \texttt{(Intercept)} refers to in presence of categorical.
covariates).
\item \texttt{logLik} to output the log-likelihood of the estimated model.
\item \texttt{model.tables} to extract the estimates, standard errors, p-value, and confidence intervals.
\item \texttt{plot} to obtain a diagnostic plots, partial residual plots, or a graphical display of the fitted values.
\item \texttt{predict} to compute the mean conditional on covariates and
possible outcome values.
\item \texttt{profile} to display the likelihood or profile likelihood of the model.
\item \texttt{resample} to use non-parametric bootstrap or permutation test for statistical inference.
\item \texttt{residuals} to extract the observed residuals of the fitted
model, possibly normalized
(\(\widehat{\Omega}^{-\frac{1}{2}}\widehat{\varepsilon}\)).
\item \texttt{sigma} to extract the modeled residual variance covariance matrix (\(\widehat{\Omega}\)).
\item \texttt{summary} to obtain a summary of the input, model fit, and estimated values.
\item \texttt{vcov} to extract the variance-covariance matrix of the mean
parameters (\(\widehat{\Sigma}_{\widehat{\beta}}\)).
\end{itemize}
\item the \texttt{mlmm} function to fit group-specific linear mixed models and
gather the estimated coefficients.
\item the \texttt{sampleRem} function to simulate longitudinal data.
\item the \texttt{LMMstar.options} function enables the user to display the
default values used in the \textbf{LMMstar} package. The function
can also change the default values to better match the user needs.
\end{itemize}


\clearpage

\section{Illustrative dataset}
\label{sec:orgb73e316}

To illustrate the functionalities of the package, we will use the
gastricbypass dataset. The long format can be imported using:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
data(gastricbypassL, package = "LMMstar")
head(gastricbypassL)
\end{lstlisting}

\begin{verbatim}
  id visit time weight glucagonAUC
1  1     1  -13  127.2      20.690
2  2     1  -13  165.2      49.922
3  3     1  -13  109.7      42.434
4  4     1  -13  146.2      27.517
5  5     1  -13  113.1      29.151
6  6     1  -13  158.8      42.700
\end{verbatim}


See \texttt{?gastricbypassL} for a presentation of the dataset. It is
convenient to encode the time variable in two formats:
\begin{itemize}
\item numeric, e.g. here with the time in week since surgery (\texttt{time}
variable taking values -13,-1,1,13 - negative times refering to
before an intervention and positive times after the intervention).
\item factor, e.g. here with the visit index (\texttt{visit} variable taking
value 1,2,3,4)
\end{itemize}

To illustrate certain functionalities we will use an (artificial)
group variable:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
gastricbypassL$group <- as.factor(as.numeric(gastricbypassL$id)%%2)
\end{lstlisting}

and dichotomize time as before and after the intervention:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
gastricbypassL$baseline <- gastricbypassL$time<0
\end{lstlisting}

The corresponding wide format is
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
data(gastricbypassW, package = "LMMstar")
head(gastricbypassW)
\end{lstlisting}

\begin{verbatim}
  id weight1 weight2 weight3 weight4 glucagonAUC1 glucagonAUC2 glucagonAUC3 glucagonAUC4
1  1   127.2   120.7   115.5   108.1       20.690       20.535       92.600       43.434
2  2   165.2   153.4   149.2   132.0       49.922       58.513       49.633       35.747
3  3   109.7   101.6    97.7    87.1       42.434       25.770       91.240       83.137
4  4   146.2   142.4   136.7   123.0       27.517       27.552       59.360       21.371
5  5   113.1   105.6    99.9    87.7       29.151           NA       86.859       57.970
6  6   158.8   143.6   134.6   108.7       42.700       31.616       53.408       37.636
\end{verbatim}


for which we can also add the group variable:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
gastricbypassW$group <- as.numeric(gastricbypassW$id)%%2
\end{lstlisting}

In some cases we will, for comparison, perform complete case analyses
with the following dataset:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
gastricbypassL.NNA <- gastricbypassL[!is.na(gastricbypassL$glucagonAUC),]
\end{lstlisting}

\clearpage

\section{Visualization \& descriptive statistics}
\label{sec:org5fb8c7e}
\subsection{Graphical display}
\label{sec:orgbbc958a}

A scatterplot of the data can obtained by specifying which columns to
display when using the wide format:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
scatterplot(gastricbypassW, ## left panel
            columns = c("weight1","weight2","weight3","weight4")) 
\end{lstlisting}

\noindent When using the long format, a formula should describe the
structure of the data: \texttt{outcome \textasciitilde{} order|cluster}
\begin{itemize}
\item the left hand side indicates the values to be displayed (here weight)
\item the right hand side indicates the ordering of the repetitions (here over time) and
how the repetitions are grouped within clusters (here within subject).
\end{itemize}

When calling \texttt{scatterplot}, the argument \texttt{group} leads to different
color per group and the argument \texttt{type.diag} enables to use histograms
(or density plots) instead of boxplots:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
scatterplot(weight~time|id, data = gastricbypassL, ## right panel
            type.diag = "hist", group = "group")
\end{lstlisting}


\bigskip

\begin{minipage}{0.48\linewidth}
\begin{center}
\includegraphics[trim={0 0 0 0},width=\textwidth]{./figures/scatterplot.pdf}
\end{center}
\end{minipage}
\begin{minipage}{0.48\linewidth}
\begin{center}
\includegraphics[trim={0 0 0 0},width=\textwidth]{./figures/scatterplot-group.pdf}
\end{center}
\end{minipage}


\bigskip

By default the resulting object will be of class \texttt{list}. A \texttt{ggplot2}
object can be obtained by setting the argument \texttt{facet} to
\texttt{"grid2"}. This requires to have installed the package ggh4x and will
produce a slightly different graphical display.

\bigskip

There is (currently) not dedicated function to obtain spaghetti
plots. Instead one can use the ggplot2 package with the long format, e.g.:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
gg.spa <- ggplot(gastricbypassL, aes(x=time,y=weight,group=id,color=id))
gg.spa <- gg.spa + geom_point() + geom_line()
gg.spa
\end{lstlisting}

\clearpage

\subsection{Missing data patterns}
\label{sec:org693fd4c}

The \texttt{summarizeNA} function identifies the possible combinations of
observed/missing data:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
mp <- summarizeNA(gastricbypassL)
mp
\end{lstlisting}

\begin{verbatim}
frequency missing.pattern n.missing id visit time weight glucagonAUC group baseline
       78         0000000         0  0     0    0      0           0     0        0
        2         0000100         1  0     0    0      0           1     0        0
\end{verbatim}


A graphical representation can be obtained using \texttt{plot}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
plot(mp)
\end{lstlisting}

See \texttt{help(plot.summarizeNA)} for options to customize the graphical
display.

\begin{center}
\includegraphics[trim={0 0 0 0},width=1\textwidth]{./figures/summarizeNA.pdf}
\end{center}



\clearpage

\subsection{Summary statistics}
\label{sec:org4ef97bf}

Mean, standard deviation, and other summary statistic can be computed
with respect to a categorical variable (typically time) using the
\texttt{summarize} function: \newline (\Warning this function has the same
name as a function from the dplyr package. If you have loaded dplyr,
you should use \texttt{LMMstar:::summarize})
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
sss <- summarize(weight+glucagonAUC ~ time, data = gastricbypassL, na.rm = TRUE)
print(sss, digits = 3)
\end{lstlisting}

\begin{verbatim}
      outcome time observed missing  mean   sd    min    q1 median    q3   max
1      weight  -13       20       0 129.0 20.3 100.90 115.3  123.1 139.8 173.0
2               -1       20       0 121.2 18.9  95.70 107.8  114.5 134.5 162.2
3                1       20       0 115.7 18.3  89.90 102.2  110.6 128.4 155.0
4               13       20       0 102.4 17.1  78.80  90.4   98.5 108.2 148.0
5 glucagonAUC  -13       20       0  32.3 15.5  10.28  21.3   27.9  42.5  69.1
6               -1       19       1  29.7 13.7   9.87  21.2   25.8  33.6  67.7
7                1       19       1  76.9 27.9  35.85  56.5   73.8  91.9 135.9
8               13       20       0  52.0 21.0  21.37  37.2   51.2  57.9 109.2
\end{verbatim}


\noindent Specifying a cluster (\texttt{id}) and ordering variable (\texttt{time})
enable to output correlation matrices: \newline (\Warning there should be
no duplicated value of the ordering variable within cluster)
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
sss2 <- summarize(weight ~ time|id, data = gastricbypassL, na.rm = TRUE)
print(sss2, digits = 3)
\end{lstlisting}

\begin{verbatim}
  time observed missing mean   sd   min    q1 median  q3 max
1  -13       20       0  129 20.3 100.9 115.3  123.1 140 173
2   -1       20       0  121 18.9  95.7 107.8  114.5 135 162
3    1       20       0  116 18.3  89.9 102.2  110.6 128 155
4   13       20       0  102 17.1  78.8  90.4   98.5 108 148

 Pearson's correlation: 
      -13    -1     1    13
-13 1.000 0.990 0.986 0.946
-1  0.990 1.000 0.997 0.959
1   0.986 0.997 1.000 0.966
13  0.946 0.959 0.966 1.000
\end{verbatim}

Graphical displays of the summary statistics can be obtained via the
\texttt{plot} method, where the argument \texttt{type} specifies the summary
statistic to be displayed:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
plot(sss2, type = "mean") ## left panel
plot(sss2, type = "sd") ## middle panel
plot(sss2, type = "cor") ## right panel
\end{lstlisting}

See \texttt{help(plot.summarize)} for options to customize the graphical
display.

\begin{center}
\includegraphics[trim={0 0 0 0},width=1\textwidth]{./figures/summarize.pdf}
\end{center}

\clearpage

\subsection{Correlation and partial correlations}
\label{sec:org9fe2eeb}

The \texttt{partialCor} function can be used to evaluate group-specific
correlations, e.g.:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
partialCor(weight + glucagonAUC ~ 1, by = "group", data = gastricbypassL)
\end{lstlisting}

\begin{verbatim}
                           estimate    se   df  lower    upper p.value
0: rho(weight,glucagonAUC)   -0.328 0.143 21.8 -0.587 -0.00886  0.0447
1: rho(weight,glucagonAUC)   -0.354 0.141 22.5 -0.607 -0.03631  0.0313
\end{verbatim}


This willl lead to the same estimate as the \texttt{cor.test} function
(Pearson correlation):
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
gastricbypassL.0 <- gastricbypassL[gastricbypassL$group==0,]
rho <- cor.test(gastricbypassL.0$weight, gastricbypassL.0$glucagonAUC)
c(rho$estimate, p.value = rho$p.value)
\end{lstlisting}

\begin{verbatim}
      cor   p.value 
-0.328481  0.038505
\end{verbatim}


However the p-value may differ, especially in small samples, as
\texttt{partialCor} uses a different (and probably more crude) small sample
approximation for the estimator's distribution. Nevertheless
\texttt{partialCor} enables to compare correlation coefficients across
groups, by specifying the argument \texttt{effects}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
partialCor(weight + glucagonAUC ~ 1, by = "group", effects = "Dunnett",
           data = gastricbypassL)
\end{lstlisting}

\begin{verbatim}
                                                      estimate se df lower upper p.value
1:rho(weight,glucagonAUC) - 0:rho(weight,glucagonAUC)  -0.0255 NA NA    NA    NA   0.899
\end{verbatim}



Partial correlations can be also computed by specifying covariate to
adjust for on the right-hand side:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
partialCor(weight4 + glucagonAUC4 ~ weight1,
           data = gastricbypassW)
\end{lstlisting}

\begin{verbatim}
                          estimate    se   df  lower upper p.value
rho(weight4,glucagonAUC4)    0.112 0.233 9.12 -0.397 0.568   0.645
\end{verbatim}


When the set of covariates is outcome-dependent, a list of formulas
can be used instead:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
partialCor(list(weight1 ~ glucagonAUC1, weight4 ~ glucagonAUC4),
           data = gastricbypassW)
\end{lstlisting}

\begin{verbatim}
                     estimate     se   df lower upper  p.value
rho(weight1,weight4)    0.946 0.0252 26.4 0.861 0.979 5.51e-08
\end{verbatim}


These partial correlations are defined as the residual correlation
between the outcomes, i.e. the correlation once the covariate effects
have been substracted from the outcome, and a linear mixed model is
used to estimated them.

\clearpage

\section{Multiple Student's t-tests}
\label{sec:orgabf9b00}

When working with multiple outcomes and having no missing data, mean
comparisons between exposure groups can be carried out using Student's
t-tests at each timepoint, e.g.:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
restt <- t.test(weight1 ~ group, data = gastricbypassW)
c(estimate = unname(diff(restt$estimate)), p.value = restt$p.value)
\end{lstlisting}

\begin{verbatim}
 estimate   p.value 
-10.60000   0.25282
\end{verbatim}


And so on for the three other timepoints. Morever results would
typically need to be adjusted for multiple comparisons, e.g. when
looking for any mean difference. This can be faciliated by
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
## single step max-test adjustment (see help(confint.Wald_lmm) for details)
mt.test(weight1+weight2+weight3+weight4~group, data = gastricbypassW)
\end{lstlisting}

\begin{verbatim}
       by parameter estimate     se     df   lower   upper p.value
1 weight1     group   -10.60 8.9717 17.965 -30.968  9.7680 0.31894
2 weight2     group    -9.50 8.3951 17.985 -28.559  9.5590 0.34164
3 weight3     group    -8.92 8.1295 17.959 -27.376  9.5358 0.35891
4 weight4     group    -4.59 7.7607 17.682 -22.209 13.0286 0.66331
\end{verbatim}


The method used to adjust confidence intervals and p-values for
multiple comparisons can be specified via the \texttt{method} argument, e.g.:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
## no adjustment
mt.test(weight1+weight2+weight3+weight4~group, data = gastricbypassW, method = "none")
\end{lstlisting}

\begin{verbatim}
       by parameter estimate     se     df   lower   upper p.value
1 weight1     group   -10.60 8.9717 17.965 -29.452  8.2516 0.25281
2 weight2     group    -9.50 8.3951 17.985 -27.139  8.1386 0.27266
3 weight3     group    -8.92 8.1295 17.959 -26.002  8.1622 0.28703
4 weight4     group    -4.59 7.7607 17.682 -20.916 11.7356 0.56171
\end{verbatim}


\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
## bonferroni adjustment
mt.test(weight1+weight2+weight3+weight4~group, data = gastricbypassW, method = "bonferroni")
\end{lstlisting}

\begin{verbatim}
       by parameter estimate     se     df   lower  upper p.value
1 weight1     group   -10.60 8.9717 17.965 -35.498 14.298       1
2 weight2     group    -9.50 8.3951 17.985 -32.795 13.795       1
3 weight3     group    -8.92 8.1295 17.959 -31.481 13.641       1
4 weight4     group    -4.59 7.7607 17.682 -26.165 16.985       1
\end{verbatim}



\clearpage

\section{Linear mixed model (LMM)}
\label{sec:org8ea2d3b}
\subsection{Classical covariance patterns}
\label{sec:org7209430}

Several build-in covariance patterns can be used when specifying the
linear model. The most basic ones are the \textbf{identity} structure:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eId.lmm <- lmm(glucagonAUC ~ visit*group, repetition = ~time|id, 
               structure = "ID", data = gastricbypassL)
eId.lmm
cat(" modeled residual variance-covariance: \n");sigma(eId.lmm)
\end{lstlisting}

\begin{verbatim}
		Linear regression 

 outcome/cluster/time: glucagonAUC/id/time 
 data                : 78 observations from 20 clusters 
 parameter           : 8 mean ((Intercept) visit2 visit3 visit4 group1 visit2:group1 visit3:group1 visit4:group1) 
                       1 variance (sigma) 
 log-restr.likelihood: -316.461119970244 
 convergence         : TRUE (0 iterations)
 modeled residual variance-covariance: 
       -13     -1      1     13
-13 381.35   0.00   0.00   0.00
-1    0.00 381.35   0.00   0.00
1     0.00   0.00 381.35   0.00
13    0.00   0.00   0.00 381.35
\end{verbatim}

and the \textbf{independence} structure:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eInd.lmm <- lmm(glucagonAUC ~ visit*group, repetition = ~time|id, 
                structure = "IND", data = gastricbypassL)
eInd.lmm
cat(" modeled residual variance-covariance: \n");sigma(eInd.lmm)
\end{lstlisting}

\begin{verbatim}
		Linear regression with heterogeneous residual variance 

 outcome/cluster/time: glucagonAUC/id/time 
 data                : 78 observations from 20 clusters 
 parameter           : 8 mean ((Intercept) visit2 visit3 visit4 group1 visit2:group1 visit3:group1 visit4:group1) 
                       4 variance (sigma k.-1 k.1 k.13) 
 log-restr.likelihood: -310.428096419287 
 convergence         : TRUE (0 iterations)
 modeled residual variance-covariance: 
       -13     -1      1     13
-13 209.44   0.00   0.00   0.00
-1    0.00 174.81   0.00   0.00
1     0.00   0.00 768.23   0.00
13    0.00   0.00   0.00 382.95
\end{verbatim}

\clearpage

The most common linear mixed model uses a \textbf{compound symmetry} structure:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eCS.lmm <- lmm(glucagonAUC ~ visit*group, repetition = ~time|id,
               structure = "CS", data = gastricbypassL)
eCS.lmm
cat(" modeled residual variance-covariance: \n");sigma(eCS.lmm)
\end{lstlisting}

\begin{verbatim}
		Linear Mixed Model with a compound symmetry covariance matrix 

 outcome/cluster/time: glucagonAUC/id/time 
 data                : 78 observations from 20 clusters 
 parameter           : 8 mean ((Intercept) visit2 visit3 visit4 group1 visit2:group1 visit3:group1 visit4:group1) 
                       1 variance (sigma) 
                       1 correlation (rho(id)) 
 log-restr.likelihood: -314.394203759159 
 convergence         : TRUE (6 iterations)
 modeled residual variance-covariance: 
        -13      -1       1      13
-13 380.580  82.741  82.741  82.741
-1   82.741 380.580  82.741  82.741
1    82.741  82.741 380.580  82.741
13   82.741  82.741  82.741 380.580
\end{verbatim}

\noindent A more flexible model can be obtained with a \textbf{toeplitz} covariance matrix:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eTOE.lmm <- lmm(glucagonAUC ~ visit*group, repetition = ~time|id,
                structure = "TOEPLITZ", data = gastricbypassL)
eTOE.lmm
cat(" modeled residual correlation: \n");cov2cor(sigma(eTOE.lmm))
\end{lstlisting}

\begin{verbatim}
		Linear Mixed Model with a block Toeplitz covariance matrix 

 outcome/cluster/time: glucagonAUC/id/time 
 data                : 78 observations from 20 clusters 
 parameter           : 8 mean ((Intercept) visit2 visit3 visit4 group1 visit2:group1 visit3:group1 visit4:group1) 
                       4 variance (sigma k.-1 k.1 k.13) 
                       4 correlation (rho(12) rho(14) rho(26) rho(2)) 
 log-restr.likelihood: -297.525485582536 
 convergence         : TRUE (15 iterations)
 modeled residual correlation: 
          -13       -1        1        13
-13  1.000000 0.700020 0.093615 -0.082963
-1   0.700020 1.000000 0.016795  0.093615
1    0.093615 0.016795 1.000000  0.700020
13  -0.082963 0.093615 0.700020  1.000000
\end{verbatim}

\clearpage

\noindent And an even more flexible model can be obtained with an
\textbf{unstructured} covariance matrix:

\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eUN.lmm <- lmm(glucagonAUC ~ visit*group, repetition = ~time|id,
               structure = "UN", data = gastricbypassL)
eUN.lmm
cat(" modeled residual variance-covariance: \n");sigma(eUN.lmm)
\end{lstlisting}

\begin{verbatim}
		Linear Mixed Model with an unstructured covariance matrix 

 outcome/cluster/time: glucagonAUC/id/time 
 data                : 78 observations from 20 clusters 
 parameter           : 8 mean ((Intercept) visit2 visit3 visit4 group1 visit2:group1 visit3:group1 visit4:group1) 
                       4 variance (sigma k.-1 k.1 k.13) 
                       6 correlation (rho(-13,-1) rho(-13,1) rho(-13,13) rho(-1,1) rho(-1,13) rho(1,13)) 
 log-restr.likelihood: -295.314056198772 
 convergence         : TRUE (8 iterations)
 modeled residual variance-covariance: 
        -13       -1        1      13
-13 209.442 150.2502 106.4000 -24.202
-1  150.250 168.1138   1.3064 -23.884
1   106.400   1.3064 748.0769 288.184
13  -24.202 -23.8844 288.1839 382.952
\end{verbatim}

\noindent Stratification of the covariance structure on a categorical
variable is also possible:
\begin{itemize}
\item e.g. to get a \textbf{stratified compound symmetry}
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eSCS.lmm <- lmm(glucagonAUC ~ visit*group, repetition = ~time|id,
                structure = CS(group~1), data = gastricbypassL)
eSCS.lmm
\end{lstlisting}

\begin{verbatim}
	       Linear Mixed Model with a stratified compound symmetry covariance matrix 

outcome/cluster/time: glucagonAUC/id/time 
data                : 78 observations from 20 clusters 
parameter           : 8 mean ((Intercept) visit2 visit3 visit4 group1 visit2:group1 visit3:group1 visit4:group1) 
                      2 variance (sigma:0 sigma:1) 
                      2 correlation (rho(id):0 rho(id):1) 
log-restr.likelihood: -314.123797063042 
convergence         : TRUE (7 iterations)
\end{verbatim}


\clearpage

\begin{itemize}
\item e.g. \textbf{stratified unstructured} covariance matrix:
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eSUN.lmm <- lmm(glucagonAUC ~ visit*group, repetition = ~time|id,
                structure = UN(group~1), data = gastricbypassL)
eSUN.lmm
\end{lstlisting}
\begin{verbatim}
	       Linear Mixed Model with a stratified unstructured covariance matrix 

outcome/cluster/time: glucagonAUC/id/time 
data                : 78 observations from 20 clusters 
parameter           : 8 mean ((Intercept) visit2 visit3 visit4 group1 visit2:group1 visit3:group1 visit4:group1) 
                      8 variance (sigma:0 sigma:1 k.-1:0 k.1:0 k.13:0 k.-1:1 k.1:1 k.13:1) 
                      12 correlation (rho(-13,-1):0 rho(-13,1):0 rho(-13,13):0 rho(-1,1):0 rho(-1,13):0 rho(1,13):0 rho(-13,-1):1 rho(-13,1):1 rho(-13,13):1 rho(-1,1):1 rho(-1,13):1 rho(1,13):1) 
log-restr.likelihood: -286.536815485471 
convergence         : TRUE (10 iterations)
\end{verbatim}


with modeled residual variance-covariance:

\bigskip

\begin{minipage}{0.47\linewidth}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
sigma(eSCS.lmm)
\end{lstlisting}

\begin{verbatim}
$`0`
        -13      -1       1      13
-13 334.289  50.782  50.782  50.782
-1   50.782 334.289  50.782  50.782
1    50.782  50.782 334.289  50.782
13   50.782  50.782  50.782 334.289

$`1`
       -13     -1      1     13
-13 428.46 115.09 115.09 115.09
-1  115.09 428.46 115.09 115.09
1   115.09 115.09 428.46 115.09
13  115.09 115.09 115.09 428.46
\end{verbatim}
\end{minipage}
\begin{minipage}{0.47\linewidth}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
sigma(eSUN.lmm)
\end{lstlisting}

\begin{verbatim}
$`0`
       -13      -1       1      13
-13 309.85 251.512 102.189 -42.250
-1  251.51 274.752 -79.811 -90.718
1   102.19 -79.811 579.110 163.767
13  -42.25 -90.718 163.767 173.439

$`1`
         -13     -1       1       13
-13 109.0309 48.667 104.908  -6.1549
-1   48.6665 59.395  93.976  43.2144
1   104.9077 93.976 967.583 450.8899
13   -6.1549 43.214 450.890 592.4655
\end{verbatim}
\end{minipage}

\clearpage

\noindent Finally the some covariance patterns like the compound
symmetry structure may depend on covariates:
\begin{itemize}
\item e.g. to obtain a \textbf{block compound symmetry} structure\footnote{similar to
nested random effects}:
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eBCS.lmm <- lmm(glucagonAUC ~ visit*group, repetition = ~time|id,
                structure = CS(~baseline, type = "homogeneous"), data = gastricbypassL)
eBCS.lmm
cat(" modeled residual variance-covariance: \n");sigma(eBCS.lmm)
\end{lstlisting}

\begin{verbatim}
		Linear Mixed Model with a block compound symmetry covariance matrix 

 outcome/cluster/time: glucagonAUC/id/time 
 data                : 78 observations from 20 clusters 
 parameter           : 8 mean ((Intercept) visit2 visit3 visit4 group1 visit2:group1 visit3:group1 visit4:group1) 
                       1 variance (sigma) 
                       2 correlation (rho(id/baseline) rho(id)) 
 log-restr.likelihood: -308.994835006264 
 convergence         : TRUE (6 iterations)
 modeled residual variance-covariance: 
        -13      -1       1      13
-13 380.957 226.403  15.465  15.465
-1  226.403 380.957  15.465  15.465
1    15.465  15.465 380.957 226.403
13   15.465  15.465 226.403 380.957
\end{verbatim}

\begin{itemize}
\item e.g. to obtain a \textbf{block unstructured} covariance matrix:
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eBUN.lmm <- lmm(glucagonAUC ~ visit*group, repetition = ~time|id,
                structure = CS(~baseline, type = "heterogeneous"), data = gastricbypassL)
eBUN.lmm
cat(" modeled residual variance-covariance: \n");sigma(eBUN.lmm)
\end{lstlisting}

\begin{verbatim}
		Linear Mixed Model with a block unstructured covariance matrix 

 outcome/cluster/time: glucagonAUC/id/time 
 data                : 78 observations from 20 clusters 
 parameter           : 8 mean ((Intercept) visit2 visit3 visit4 group1 visit2:group1 visit3:group1 visit4:group1) 
                       2 variance (sigma k.TRUE) 
                       3 correlation (rho(FALSE) rho(FALSE,TRUE) rho(TRUE)) 
 log-restr.likelihood: -300.047474124556 
 convergence         : TRUE (7 iterations)
 modeled residual variance-covariance: 
        -13      -1       1      13
-13 189.420 150.356  15.353  15.353
-1  150.356 189.420  15.353  15.353
1    15.353  15.353 570.908 300.071
13   15.353  15.353 300.071 570.908
\end{verbatim}

\clearpage

\subsection{User-specific covariance patterns}
\label{sec:orgf0176ab}

It is possible input user-specific covariance patterns under the
following model for the residuals: \[\Omega =
\trans{\boldsymbol{\sigma}} R \boldsymbol{\sigma}\]
\begin{itemize}
\item \(\boldsymbol{\sigma}=f(\boldsymbol{\theta}_{\sigma},Z_{\sigma})\)
is a vector of residual standard errors depending on a vector of
parameters \(\boldsymbol{\theta}_{\sigma}\) and possible covariates
via the design matrix \(Z_{\sigma}\).
\item \(R=g(\boldsymbol{\theta}_{R},Z_R)\) is a matrix of residual
correlations depending on a vector of parameters
\(\boldsymbol{\theta}_{R}\) and possible covariates via the design
matrix \(Z_R\).
\end{itemize}

\bigskip

To be more concrete, consider the following correlation matrix
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
rho.2block <- function(p,n.time,X){
  rho <- matrix(1, nrow = n.time, ncol = n.time)
  rho[1,2] <- rho[2,1] <- rho[4,5] <- rho[5,4] <- p["rho1"]
  rho[1,3] <- rho[3,1] <- rho[4,6] <- rho[6,4] <- p["rho2"]
  rho[2,3] <- rho[3,2] <- rho[5,6] <- rho[6,5] <- p["rho3"]
  rho[4:6,1:3] <- rho[1:3,4:6] <- p["rho4"]
  return(rho)
}
Rho <- rho.2block(p = c(rho1=0.25,rho2=0.5,rho3=0.4,rho4=0.1),
                  n.time = 6)
Rho
\end{lstlisting}

\begin{verbatim}
     [,1] [,2] [,3] [,4] [,5] [,6]
[1,] 1.00 0.25  0.5 0.10 0.10  0.1
[2,] 0.25 1.00  0.4 0.10 0.10  0.1
[3,] 0.50 0.40  1.0 0.10 0.10  0.1
[4,] 0.10 0.10  0.1 1.00 0.25  0.5
[5,] 0.10 0.10  0.1 0.25 1.00  0.4
[6,] 0.10 0.10  0.1 0.50 0.40  1.0
\end{verbatim}


and the corresponding dataset:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
set.seed(11)
Y <- mvtnorm::rmvnorm(1000, mean = rep(0,6), sigma = Rho)
dfW <- cbind(id = 1:NROW(Y), as.data.frame(Y))
dfL <- reshape2::melt(dfW, id.vars = "id", variable.name = "time")
dfL[dfL$id %in% 1:2,]
\end{lstlisting}

\begin{minipage}{0.45\linewidth}
\begin{verbatim}
     id time      value
1     1   V1 -0.9842079
1001  1   V2 -0.3681245
2001  1   V3 -1.6174652
3001  1   V4 -1.4994103
4001  1   V5  0.7493107
5001  1   V6 -1.0719657
\end{verbatim}


\end{minipage}
\begin{minipage}{0.45\linewidth}
\begin{verbatim}
     id time      value
2     2   V1  1.2402726
1002  2   V2  0.6494215
2002  2   V3  0.3272105
3002  2   V4 -1.0626973
4002  2   V5 -0.9013244
5002  2   V6 -0.6696714
\end{verbatim}


\end{minipage}

\clearpage

To estimate the corresponding mixed model we first define a new
covariance structure:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
myStruct <- CUSTOM(~time,
                   FCT.sigma = function(p,n.time,X){rep(p,n.time)}, ## function f
                   init.sigma = c("sigma"=1),
                   FCT.rho = rho.2block, ## function g
                   init.rho = c("rho1"=0.25,"rho2"=0.25,"rho3"=0.25,"rho4"=0.25))
\end{lstlisting}

and then call \texttt{lmm} with this structure structure:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.lmmCUSTOM <- lmm(value~time, repetition=~time|id,
                   structure = myStruct, data=dfL,
                   df = FALSE) ## df = FALSE to save computation time
logLik(e.lmmCUSTOM)
\end{lstlisting}

\begin{verbatim}
[1] -7962.243
\end{verbatim}


The optimization procedure may be slow but should eventually reaches
an optimum. We can then output the estimated correlation matrix:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
cov2cor(sigma(e.lmmCUSTOM))
\end{lstlisting}

\begin{verbatim}
           V1         V2         V3         V4         V5         V6
V1 1.00000000 0.24898095 0.50058994 0.09053785 0.09053785 0.09053785
V2 0.24898095 1.00000000 0.36110943 0.09053785 0.09053785 0.09053785
V3 0.50058994 0.36110943 1.00000000 0.09053785 0.09053785 0.09053785
V4 0.09053785 0.09053785 0.09053785 1.00000000 0.24898095 0.50058994
V5 0.09053785 0.09053785 0.09053785 0.24898095 1.00000000 0.36110943
V6 0.09053785 0.09053785 0.09053785 0.50058994 0.36110943 1.00000000
\end{verbatim}


\textbf{Comparison to build-in structure}: consider the following model using
a build-in compound symmetry structure:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
system.time(
  e.lmmDEFAULT.CS <- lmm(value~time, repetition = ~time|id,
                         structure = "CS", data = dfL,
                         df = FALSE)
)
\end{lstlisting}

\begin{verbatim}
 user  system elapsed 
0.097   0.000   0.097
\end{verbatim}


Using instead \texttt{CUSTOM} to specifying this structure:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
myCS <- CUSTOM(~1,
               FCT.sigma = function(p,n.time,X){rep(p,n.time)},
               init.sigma = c("sigma"=1), 
               FCT.rho = function(p,n.time,X){p+diag(1-p,n.time,n.time)},
               init.rho = c("rho"=0.5))
\end{lstlisting}

is considerably slower than using the pre-specified structure:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
system.time(
  e.lmmCUSTOM.CS <- lmm(value~time, repetition = ~time|id,
                        structure = myCS, data = dfL,
                        df = FALSE)
)
\end{lstlisting}

\begin{verbatim}
 user  system elapsed 
0.952   0.019   0.972
\end{verbatim}



but will lead to the same estimates:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
logLik(e.lmmDEFAULT.CS)
logLik(e.lmmCUSTOM.CS)
\end{lstlisting}

\begin{verbatim}
[1] -8186.859
[1] -8186.859
\end{verbatim}


There are two reasons for the slower execution time: slower evaluation
of the derivatives (since they are obtained by numerical
differentiation) and worse starting point, as reflected by the larger
number of interations needed to reach convergence:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.lmmDEFAULT.CS$opt$n.iter
e.lmmCUSTOM.CS$opt$n.iter
\end{lstlisting}

\begin{verbatim}
[1] 1
[1] 4
\end{verbatim}


Faster execution time can be obtained by specifying the first and
second derivative regarding each parameter:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
myCS.wD <- CUSTOM(~1,
                  FCT.sigma = function(p,n.time,X){rep(p,n.time)},
                  dFCT.sigma = function(p,n.time,X){list(sigma = rep(1,n.time))},
                  d2FCT.sigma = function(p,n.time,X){list(sigma = rep(0,n.time))},
                  init.sigma = c("sigma"=1),
                  FCT.rho = function(p,n.time,X){p+diag(1-p,n.time,n.time)},
                  dFCT.rho = function(p,n.time,X){list(rho = 1-diag(1,n.time,n.time))},
                  d2FCT.rho = function(p,n.time,X){list(rho = matrix(0,n.time,n.time))},
                  init.rho = c("rho"=0.5))
\end{lstlisting}

\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
system.time(
  e.lmmCUSTOMwD.CS <- lmm(value~time,
                          repetition = ~time|id,
                          structure = myCS.wD, 
                          data = dfL, df = FALSE
                          )
)
\end{lstlisting}

\begin{verbatim}
 user  system elapsed 
0.699   0.004   0.703
\end{verbatim}



\clearpage

\subsection{Estimation procedure}
\label{sec:org4846baa}

\textbf{Initialiation}: by default the mean parameters are initialized using
 Ordinary Least Squares (OLS) and the variance and correlation
 parameters are initialized by minimizing the difference between the
 observed and residuals variance-covariance matrix. These values can
 be visualized by specifying the argument \texttt{control}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eCS.lmm.bis <- update(eCS.lmm, control = list(trace = 2))
\end{lstlisting}

\begin{verbatim}
Initialization:
  (Intercept)        visit2        visit3        visit4        group1 visit2:group1 visit3:group1 
     38.72897      -4.73433      31.43303       4.52138     -12.82462       3.75946      27.00150 
visit4:group1         sigma       rho(id) 
     30.22391      19.52828       0.22819 

Loop:
******
  (Intercept)        visit2        visit3        visit4        group1 visit2:group1 visit3:group1 
     38.72897      -4.73433      31.43303       4.52138     -12.82462       3.80337      27.48103 
visit4:group1         sigma       rho(id) 
     30.22391      19.50846       0.21741 
Convergence after 6 iterations: max score=1.2413e-05 | max change in coefficient=4.5167e-06
\end{verbatim}

It is possible to input user-defined value:
\begin{itemize}
\item for all parameters (vector)
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
init.all <- coef(eCS.lmm, effects = "all")
eCS.lmm.bis <- update(eCS.lmm, control = list(init = init.all, trace = 1))
\end{lstlisting}

\begin{verbatim}
Convergence after 0 iteration: max score=1.2413e-05
\end{verbatim}


\begin{itemize}
\item the mean parameters only (vector)
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
init.mean <- coef(eCS.lmm, effects = "mean")
eCS.lmm.bis <- update(eCS.lmm, control = list(init = init.mean, trace = 2))
\end{lstlisting}

\begin{verbatim}
Initialization:
  (Intercept)        visit2        visit3        visit4        group1 visit2:group1 visit3:group1 
     38.72897      -4.73433      31.43303       4.52138     -12.82462       3.80337      27.48103 
visit4:group1         sigma       rho(id) 
     30.22391      19.52904       0.22849 

Loop:
******
  (Intercept)        visit2        visit3        visit4        group1 visit2:group1 visit3:group1 
     38.72897      -4.73433      31.43303       4.52138     -12.82462       3.80337      27.48103 
visit4:group1         sigma       rho(id) 
     30.22391      19.50846       0.21741 
Convergence after 6 iterations: max score=1.4893e-05 | max change in coefficient=5.3866e-06
\end{verbatim}

\begin{itemize}
\item a full data variance-covariance matrix (matrix).
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
init.vcov <- sigma(eCS.lmm)
eCS.lmm.bis <- update(eCS.lmm, control = list(init = init.vcov, trace = 1))
\end{lstlisting}

\begin{verbatim}
Convergence after 0 iteration: max score=1.2413e-05
\end{verbatim}


\textbf{Optimizer}: by default the optimizer is a Newton Raphson algorithm
with backtracking. At each iteration:
\begin{itemize}
\item it computes the first two moments (score, information) according to
the current parameters values.
\item it updates the variance-covariance parameters according to the
gradient multiplied by the inverse of the information.
\item it updates the mean parameters by generalized least squares (using
the updated variance-covariance parameters).
\item it checks whether the log-likelihoood at the updated estimates is
well defined and higher than at the previous estimates. If this is
not the case, the step is re-run with half the update of the
variance-covariance parameters (backtracking).
\end{itemize}

One can modify the maximum number of iterations (\texttt{n.iter}), maximum
number of backtracking steps (\texttt{n.backtracking}), the maximum score
(absolute) value over all parameters (\texttt{tol.score}) and (absolute)
maximum difference in parameter value between to iterations
(\texttt{tol.param}) used to declare convergence. It is also possible to use
another optimizer (\texttt{optimizer}). All these elements should be passed
to the argument \texttt{control} of \texttt{lmm} using a list.

\clearpage

\subsection{Model output}
\label{sec:org900cd46}

The \texttt{summary} method can be used to display the main information
relative to the model fit:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
summary(eUN.lmm)
\end{lstlisting}

\begin{verbatim}
		Linear Mixed Model 
 
Dataset: gastricbypassL 

  - 20 clusters 
  - 78 observations were analyzed, 2 were excluded because of missing values 
  - between 3 and 4 observations per cluster 

Summary of the outcome and covariates: 

    $ glucagonAUC: num  20.7 49.9 42.4 27.5 29.2 ...
    $ visit      : Factor w/ 4 levels "1","2","3","4": 1 1 1 1 1 1 1 1 1 1 ...
    $ group      : Factor w/ 2 levels "0","1": 2 1 2 1 2 1 2 1 2 1 ...
    reference level: visit=1;group=0 

Estimation procedure 

  - Restricted Maximum Likelihood (REML) 
  - log-likelihood :-295.31
  - parameters: mean = 8, variance = 4, correlation = 6
  - convergence: TRUE (8 iterations) 
    largest |score| = 4.6771e-05 for rho(-1,1)
            |change|= 1.68033723859651e-05 for visit3:group1
 
Residual variance-covariance: unstructured 

  - correlation structure: ~0 + time 
            -13       -1       1      13
    -13  1.0000  0.80072 0.26880 -0.0855
    -1   0.8007  1.00000 0.00368 -0.0941
    1    0.2688  0.00368 1.00000  0.5384
    13  -0.0855 -0.09413 0.53842  1.0000

  - variance structure: ~time 
              standard.deviation ratio
    sigma.-13               14.5 1.000
    sigma.-1                13.0 0.896
    sigma.1                 27.4 1.890
    sigma.13                19.6 1.352
\end{verbatim}

\clearpage

\begin{verbatim}
Fixed effects: glucagonAUC ~ visit * group 
 
                  estimate     se   df   lower  upper p.value    
    (Intercept)     38.729  4.576   18  29.114 48.344 < 1e-04 ***
    visit2          -4.734  2.776 17.5 -10.577  1.109 0.10574    
    visit3          31.433   8.63 17.6  13.272 49.594 0.00192  **
    visit4           4.521  8.005   18 -12.297  21.34 0.57917    
    group1         -12.825  6.472   18 -26.422  0.773 0.06302   .
    visit2:group1    3.987  3.996 17.9   -4.41 12.383 0.33169    
    visit3:group1   27.571  12.42 17.8   1.461 53.682 0.03963   *
    visit4:group1   30.224 11.321   18   6.439 54.008 0.01562   *
    -------------------------------------------------------- 
   Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1.
   Columns lower and upper contain 95% pointwise confidence intervals for each coefficient.
   Model-based standard errors are derived from the observed information (column se). 
   Degrees of freedom were computed using a Satterthwaite approximation (column df).
\end{verbatim}

\uline{Note:} the calculation of the degrees of freedom, especially when
using the observed information can be quite slow. Setting the
arguments \texttt{df} to \texttt{FALSE} and \texttt{type.information} to \texttt{"expected"} when
calling \texttt{lmm} should lead to a more reasonnable computation time.

\subsection{Extract estimated coefficients}
\label{sec:org71044da}
The value of the estimated coefficients can be output using \texttt{coef}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
coef(eUN.lmm)
\end{lstlisting}

\begin{verbatim}
  (Intercept)        visit2        visit3        visit4        group1 visit2:group1 visit3:group1 
      38.7290       -4.7343       31.4330        4.5214      -12.8246        3.9866       27.5714 
visit4:group1 
      30.2239
\end{verbatim}


Variance coefficients can be output by specifying the \texttt{effects} argument:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
coef(eUN.lmm, effects = "variance")
\end{lstlisting}

\begin{verbatim}
   sigma     k.-1      k.1     k.13 
14.47212  0.89592  1.88991  1.35220
\end{verbatim}


The first coefficient is the residual standard deviation at the
reference timepoint (here -13 week) and the remaining coefficient the
residual standard deviation at later timepoints relative to the
reference timepoint. It is possible to apply specific transformation
on the variance coefficients, for instance to obtain the residual
variance at each timepoint:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
coef(eUN.lmm, effects = "variance", transform.k = "sd")
\end{lstlisting}

\begin{verbatim}
sigma.-13  sigma.-1   sigma.1  sigma.13 
   14.472    12.966    27.351    19.569
\end{verbatim}

\subsection{Extract estimated coefficient and associated uncertainty}
\label{sec:orged2e9f9}

The uncertainty about the mean coefficients can be obtained using the
\texttt{model.tables} method \footnote{it is equivalent to \texttt{confint} method
except that by default it also outputs \texttt{se} and \texttt{p.value}}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
model.tables(eUN.lmm)
\end{lstlisting}

\begin{verbatim}
              estimate      se     df    lower    upper    p.value
(Intercept)    38.7290  4.5765 18.003  29.1143 48.34369 1.0891e-07
visit2         -4.7343  2.7759 17.543 -10.5772  1.10851 1.0574e-01
visit3         31.4330  8.6297 17.585  13.2719 49.59411 1.9229e-03
visit4          4.5214  8.0050 17.995 -12.2968 21.33958 5.7917e-01
group1        -12.8246  6.4721 18.003 -26.4219  0.77265 6.3015e-02
visit2:group1   3.9866  3.9957 17.937  -4.4102 12.38329 3.3169e-01
visit3:group1  27.5714 12.4199 17.831   1.4605 53.68232 3.9634e-02
visit4:group1  30.2239 11.3208 17.995   6.4394 54.00840 1.5624e-02
\end{verbatim}


Values for the all correlation parameters can be displayed
too, by specifying \texttt{effect=c("variance","correlation")}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
model.tables(eUN.lmm, effect = c("variance","correlation"))
\end{lstlisting}

\begin{verbatim}
              estimate       se      df    lower    upper    p.value
sigma       14.4721183 2.412020 15.3158 10.15148 20.63170         NA
k.-1         0.8959206 0.127032 20.2671  0.66670  1.20396 0.44721963
k.1          1.8899095 0.431098 25.9157  1.18244  3.02067 0.00974152
k.13         1.3521979 0.317550 29.8074  0.83694  2.18468 0.20874407
rho(-13,-1)  0.8007214 0.085177 13.4142  0.52949  0.92343 0.00042923
rho(-13,1)   0.2688043 0.219200  7.9286 -0.26374  0.67576 0.27735748
rho(-13,13) -0.0854578 0.233981  8.5882 -0.55306  0.42309 0.72505145
rho(-1,1)    0.0036838 0.237237  8.1487 -0.49424  0.49979 0.98798445
rho(-1,13)  -0.0941328 0.233649  8.9191 -0.55697  0.41331 0.69821381
rho(1,13)    0.5384239 0.176221 10.2233  0.05058  0.81883 0.03522642
\end{verbatim}

Because these parameters are constrained (e.g. strictly positive),
they uncertainty is by default computed after transformation
(e.g. \texttt{log}) and then backtransformed. The column argument can be used
to extract more or less information, e.g.:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
model.tables(eUN.lmm, columns = c("estimate","p.value"))
\end{lstlisting}

\begin{verbatim}
              estimate    p.value
(Intercept)    38.7290 1.0891e-07
visit2         -4.7343 1.0574e-01
visit3         31.4330 1.9229e-03
visit4          4.5214 5.7917e-01
group1        -12.8246 6.3015e-02
visit2:group1   3.9866 3.3169e-01
visit3:group1  27.5714 3.9634e-02
visit4:group1  30.2239 1.5624e-02
\end{verbatim}


All parameters can be displayed by specifying
\texttt{effect="all"}.  The functions \texttt{add} (resp. \texttt{remove})
can be used to add (resp. remove) one or several columns from the
default display, e.g.:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
model.tables(eUN.lmm, columns = add("statistic"))
\end{lstlisting}

\begin{verbatim}
              estimate      se statistic     df    lower    upper    p.value
(Intercept)    38.7290  4.5765   8.46260 18.003  29.1143 48.34369 1.0891e-07
visit2         -4.7343  2.7759  -1.70552 17.543 -10.5772  1.10851 1.0574e-01
visit3         31.4330  8.6297   3.64242 17.585  13.2719 49.59411 1.9229e-03
visit4          4.5214  8.0050   0.56482 17.995 -12.2968 21.33958 5.7917e-01
group1        -12.8246  6.4721  -1.98151 18.003 -26.4219  0.77265 6.3015e-02
visit2:group1   3.9866  3.9957   0.99772 17.937  -4.4102 12.38329 3.3169e-01
visit3:group1  27.5714 12.4199   2.21995 17.831   1.4605 53.68232 3.9634e-02
visit4:group1  30.2239 11.3208   2.66977 17.995   6.4394 54.00840 1.5624e-02
\end{verbatim}

\subsection{Extract estimated residual variance-covariance structure}
\label{sec:org62af89d}

The method \texttt{sigma} can be used to output the modeled residual
covariance structure and then converted to a correlation matrix using
\texttt{cov2cor}:

\medskip

\begin{minipage}{0.45\linewidth}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
Sigma <- sigma(eUN.lmm)
Sigma
\end{lstlisting}

\begin{verbatim}
        -13      -1       1      13
-13 209.442 150.250 106.400 -24.202
-1  150.250 168.114   1.306 -23.884
1   106.400   1.306 748.077 288.184
13  -24.202 -23.884 288.184 382.952
\end{verbatim}

\end{minipage}
\begin{minipage}{0.05\linewidth}
\hphantom{x}
\end{minipage}
\begin{minipage}{0.45\linewidth}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
cov2cor(Sigma)
\end{lstlisting}

\begin{verbatim}
       -13     -1     1     13
-13  1.000  0.801 0.269 -0.085
-1   0.801  1.000 0.004 -0.094
1    0.269  0.004 1.000  0.538
13  -0.085 -0.094 0.538  1.000
\end{verbatim}

\end{minipage}

The method can also be used to extract the residual covariance
relative to a "known" individual:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
sigma(eUN.lmm, cluster = 5)
\end{lstlisting}

\begin{verbatim}
        -13      1      13
-13 209.442 106.40 -24.202
1   106.400 748.08 288.184
13  -24.202 288.18 382.952
\end{verbatim}


or for a new individual:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
newdata <- data.frame(id = "X", time = c("-13","-1","1","13"))
sigma(eUN.lmm, cluster = newdata)
\end{lstlisting}

\begin{verbatim}
        -13       -1        1      13
-13 209.442 150.2502 106.4000 -24.202
-1  150.250 168.1138   1.3064 -23.884
1   106.400   1.3064 748.0769 288.184
13  -24.202 -23.8844 288.1839 382.952
\end{verbatim}


\clearpage

\subsection{Marginal effects}
\label{sec:orgc77dffe}

The \texttt{effects} method can be used to evaluate marginal means with
respect to a categorical variable:
\begin{itemize}
\item \(\Esp[Y_t \mid \text{group}]\)
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
effects(eUN.lmm, variable = "group")
\end{lstlisting}

\begin{verbatim}
		Average counterfactual outcome
		 w.r.t 'group' values 

                  estimate    se   df  lower   upper
   group=0(t=-13)   38.729 4.576   18 29.114  48.344
   group=0(t=-1)    33.995   4.1 17.9 25.377  42.612
   group=0(t=1)     70.162 8.649 17.7 51.968  88.356
   group=0(t=13)     43.25 6.188   18 30.249  56.251
   group=1(t=-13)   25.904 4.576   18  16.29  35.519
   group=1(t=-1)    25.157 4.167 18.7 16.425  33.889
   group=1(t=1)     84.909 8.951 18.2 66.115 103.702
   group=1(t=13)     60.65 6.188   18 47.649  73.651
\end{verbatim}

\begin{itemize}
\item \(\Esp[Y_t-Y_0 \mid \text{group}]\)
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
effects(eUN.lmm, type = "change", variable = "group")
\end{lstlisting}

\begin{verbatim}
		Average counterfactual change in outcome
		 w.r.t 'group' values 

                  estimate    se   df   lower  upper
   group=0(dt=-1)   -4.734 2.776 17.5 -10.577  1.109
   group=0(dt=1)    31.433  8.63 17.6  13.272 49.594
   group=0(dt=13)    4.521 8.005   18 -12.297  21.34
   group=1(dt=-1)   -0.748 2.874 18.3  -6.779  5.283
   group=1(dt=1)    59.004 8.932   18  40.242 77.767
   group=1(dt=13)   34.745 8.005   18  17.927 51.563
\end{verbatim}

\begin{itemize}
\item \(\Esp[\int_0^T Y_t dt \mid \text{group}]\)
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
effects(eUN.lmm, type = "auc", variable = "group")
\end{lstlisting}

\begin{verbatim}
	     Average counterfactual area under the outcome curve
	      w.r.t 'group' values 

             estimate      se   df    lower    upper
group=0(auc) 1220.972 104.098 17.8 1002.072 1439.873
group=1(auc) 1289.782 105.512 18.5 1068.508 1511.056
\end{verbatim}


It can also be used to contrast these marginal means:
\begin{itemize}
\item \(\Esp[Y_t \mid \text{group}=1]-\Esp[Y_t \mid \text{group}=0]\)
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
effects(eUN.lmm, type = "difference", variable = "group")
\end{lstlisting}

\begin{verbatim}
	     Difference in average counterfactual outcome
	      w.r.t 'group' values 

                 estimate     se   df   lower  upper p.value  
group=1-0(t=-13)  -12.825  6.472   18 -26.422  0.773  0.0630 .
group=1-0(t=-1)    -8.838  5.846 18.3 -21.106   3.43  0.1477  
group=1-0(t=1)     14.747 12.447 17.9 -11.409 40.903  0.2516  
group=1-0(t=13)    17.399  8.752   18  -0.987 35.785  0.0622 .
\end{verbatim}


\begin{itemize}
\item \(\Esp[Y_t-Y_0 \mid \text{group}=1]-\Esp[Y_t-Y_0 \mid \text{group}=0]\)
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
effects(eUN.lmm, type = c("change","difference"), variable = "group")
\end{lstlisting}

\begin{verbatim}
	     Difference in average counterfactual change in outcome
	      w.r.t 'group' values 

                 estimate     se   df lower  upper p.value  
group=1-0(dt=-1)    3.987  3.996 17.9 -4.41 12.383  0.3317  
group=1-0(dt=1)    27.571  12.42 17.8 1.461 53.682  0.0396 *
group=1-0(dt=13)   30.224 11.321   18 6.439 54.008  0.0156 *
\end{verbatim}


\begin{itemize}
\item \(\Esp[\int_0^T Y_t dt \mid \text{group}=1]-\Esp[\int_0^T Y_t dt \mid \text{group}=0]\)
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
effects(eUN.lmm, type = c("auc","difference"), variable = "group")
\end{lstlisting}

\begin{verbatim}
	     Difference in average counterfactual area under the outcome curve
	      w.r.t 'group' values 

               estimate     se   df   lower   upper p.value  
group=1-0(auc)   68.809 148.22 18.1 -242.44 380.059   0.648
\end{verbatim}


It is possible to control the set of covariates used to condition on
via the \texttt{conditional} argument. This can be useful when considering an
interaction with a biomarker to obtain biomarker-specific effects.

\clearpage

\subsection{Random effects}
\label{sec:orgf97f01f}

Mixed model having a compound symmetry structure with positive
correlation parameters may be equivalent to random intercept models,
possibly with nested random effects. Indeed in some case the residual
variance-covariance matrix can then be decomposed as:
\[ \Omega = Z \Psi \trans{Z} + \Delta \]
\begin{itemize}
\item \(Z\) is the design matrix associated to the random effect (e.g. patient id)
\item \(\Psi\) is the variance-covariance of the random effects
\item \(\Delta\) the residual variance covariance conditional to the random effects.
\end{itemize}
One can the use \texttt{lme4} syntax to fit random intercept models with
\texttt{lmm}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eRI.lmm <- lmm(glucagonAUC ~ visit*group + (1|id), data = gastricbypassL)
eRI.lmm
\end{lstlisting}

\begin{verbatim}
	       Linear Mixed Model with a random intercept 

outcome/cluster/time: glucagonAUC/id/XXtimeXX 
data                : 78 observations from 20 clusters 
parameter           : 8 mean ((Intercept) visit2 visit3 visit4 group1 visit2:group1 visit3:group1 visit4:group1) 
                      1 variance (sigma) 
                      1 correlation (rho(id)) 
log-restr.likelihood: -314.394203759159 
convergence         : TRUE (6 iterations)
\end{verbatim}


It is also possible to specify cross or nested random effects, e.g.:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eNRI.lmm <- lmm(glucagonAUC ~ visit*group + (1|id/baseline), data = gastricbypassL)
eNRI.lmm
\end{lstlisting}

\begin{verbatim}
	       Linear Mixed Model with nested random intercepts 

outcome/cluster/time: glucagonAUC/id/XXtimeXX 
data                : 78 observations from 20 clusters 
parameter           : 8 mean ((Intercept) visit2 visit3 visit4 group1 visit2:group1 visit3:group1 visit4:group1) 
                      1 variance (sigma) 
                      2 correlation (rho(id/baseline) rho(id)) 
log-restr.likelihood: -308.994835006264 
convergence         : TRUE (6 iterations)
\end{verbatim}


We obtain the same log-likelihood as, respectively, \texttt{eCS.lmm} and
\texttt{eBCS.lmm}. Indeed, as previously mentioned, with positive residual
correlation the random effect structure is equivalent to a compound
symmetry structure. \newline \Warning random slopes are not currently
supported in LMMstar. \newline \Warning the proposed implementation can
be very inefficient compared to \texttt{lme4}.

\bigskip

The joint distribution between the outcome \(\VY\)
and the random effects \(\Veta\) can be expressed as:
\[
\begin{bmatrix} \VY \\ \Veta \end{bmatrix} \sim \Gaus\left(\begin{bmatrix} \boldsymbol{\mu} \\ \mathbf{0} \end{bmatrix}, \begin{bmatrix} \Omega & Z \Psi \\ \Psi \trans{Z} & \Psi \end{bmatrix}\right)
\]
Denote by \(\varepsilon_i=\VY_i-\boldsymbol{\mu}_i\) the vector of
marginal residuals relative to individual \(i\), \(\Omega_i\) its
variance-covariance matrix, and \(\psi_j=(\Psi)_{jj}\) the variance of the
\(j\)-th random effect. We can re-express the expected value of the
\(j\)-th random effect for individual \(i\) as:
\[ \eta_{ij} = \psi_{j} Z_{ij} \Omega_i^{-1}\varepsilon_i \]
This is what the \texttt{ranef} method returns:

\bigskip

\begin{minipage}{0.48\linewidth}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
head(ranef(eRI.lmm, format = "wide"))
\end{lstlisting}

\begin{verbatim}
  id estimate
1  1 -2.51154
2  2  1.01043
3  3  6.08384
4  4 -6.62350
5  5  0.39519
6  6 -2.73384
\end{verbatim}

\end{minipage}
\begin{minipage}{0.48\linewidth}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
head(ranef(eNRI.lmm, format = "wide"))
\end{lstlisting}

\begin{verbatim}
  id  estimate estimate.FALSE estimate.TRUE
1  1 -0.494271       -3.50959      -3.23209
2  2  0.186051      -10.39431      12.93198
3  3  1.088409        9.36327       5.48225
4  4 -1.219596      -11.06703      -5.56784
5  5  0.081686       -0.71254       1.82672
6  6 -0.503386       -7.81700       0.95098
\end{verbatim}

\end{minipage}


It is also possible to extract the variance decomposition by setting
the argument \texttt{effects} to \texttt{"variance"}:

\medskip

\begin{minipage}{0.47\linewidth}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
ranef(eRI.lmm, effects = "variance",
      format = "wide")
\end{lstlisting}

\begin{verbatim}
      type absolute relative
1    total  380.580  1.00000
2       id   82.741  0.21741
3 residual  297.839  0.78259

\end{verbatim}

\end{minipage}
\begin{minipage}{0.47\linewidth}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
ranef(eNRI.lmm, effects = "variance",
      format = "wide")
\end{lstlisting}

\begin{verbatim}
      type absolute relative
1    total  380.957 1.000000
2       id   15.465 0.040595
3 baseline  210.938 0.553705
4 residual  154.554 0.405700
\end{verbatim}

\end{minipage}


Confidence intervals can also be obtained setting the argument \texttt{se} to
\texttt{TRUE} and \texttt{format} equal to \texttt{"long"}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
head(ranef(eRI.lmm, se = TRUE))
\end{lstlisting}

\begin{verbatim}
  id estimate     se      df    lower   upper
1  1 -2.51154 2.3019 11.1302  -7.5708  2.5477
2  2  1.01043 2.1163 15.7355  -3.4821  5.5030
3  3  6.08384 2.9771  6.2085  -1.1421 13.3098
4  4 -6.62350 3.1114  5.8319 -14.2902  1.0432
5  5  0.39519 1.9661 23.8446  -3.6640  4.4543
6  6 -2.73384 2.2940 10.0189  -7.8438  2.3761
\end{verbatim}


\clearpage

\subsection{Sum of squares}
\label{sec:org6c55814}

\Warning The definition of the sum of squares is not straightforward with mixed
models. Intuitively summing residuals across several outcomes will be
hard to interpret unless all outcomes have the same variance. This is
why LMMstar does not provide them. Nevertheless for specific
covariance structure, namely independence and compound symmetry (with
positive correlation) structure, sum of squares can be deduced from
the \texttt{lmm} object - see appendix \ref{SM:sumSquares} for the theoretical
derivations. Importantly, with these structures the residuals can be
reparametrised as random effects plus independent residuals,
i.e. \(\Omega = Z \Psi \trans{Z} + \delta I\) where \(I\) is the
identity matrix and \(\delta\) the variance of these independent
residuals.

\bigskip

Appendix \ref{SM:sumSquares} illustrate how to extract the sum of squares
for univariate linear regression (i.e. independence structure) and
here we illustrate the case of a compound symmetry structure.  A key
step is to extract from the \texttt{lmm} object the conditional residual variance
\(\delta\):
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
sigma2 <- coef(eCS.lmm, effect = "variance")^2
tau <- coef(eCS.lmm, effect = "correlation")*sigma2
delta <- unname(sigma2 - tau)
\end{lstlisting}

This step will typically depend on the covariance structure. The
residual sum of squares (SSE) equals the residual degrees of freedom
times the conditional variance:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
df.res <- df.residual(eCS.lmm)
SSE <- df.res * delta
c(df.res = df.res, SSE = SSE)
\end{lstlisting}

\begin{verbatim}
df.res    SSE 
    70  20849
\end{verbatim}


For the regression sum of squares (SSR), we first extract the mean
parameters and their variance-covariance based on the expected
information:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eBeta.lmm <- coef(eCS.lmm)
eVcov.lmm <- vcov(eCS.lmm, type.information = "expected")
\end{lstlisting}

Parameters are grouped with respect to the original variable:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
attr(model.matrix(eCS.lmm),"assign")
\end{lstlisting}

\begin{verbatim}
[1] 0 1 1 1 2 3 3 3
\end{verbatim}


\bigskip

So we respect this grouping when computing the normalized SSR: 
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
SSRstar.time <- eBeta.lmm[2:4] %*% solve(eVcov.lmm[2:4,2:4]) %*% eBeta.lmm[2:4] 
SSRstar.group <- eBeta.lmm[5] %*% solve(eVcov.lmm[5,5]) %*% eBeta.lmm[5] 
\end{lstlisting}
The SSR is obtained by multiplying the normalized SSR by the
conditional variance:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
SSR.time <- as.double(SSRstar.time * delta)
SSR.group <- as.double(SSRstar.group * delta)
c(time = SSR.time, group = SSR.group)
\end{lstlisting}
\begin{verbatim}
   time   group 
7872.19  643.57
\end{verbatim}

\subsection{Proportion of explained variance and partial correlation}
\label{sec:org1b78b7b}

For a univariate linear model with homoschedastic residual variance,
the proportion of explained variance, also called partial \(R^2\) or
partial \(\eta^2\), is defined as the ratio between sum of squares
(e.g. \cite{lakens2013calculating}, equation 12):
\[ R^2=\frac{SSR}{SSR + SSE} \]

\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
c(SSR.time/ (SSR.time + SSE),
  SSR.group/ (SSR.group + SSE))
\end{lstlisting}

\begin{verbatim}
[1] 0.274092 0.029944
\end{verbatim}


Computing the SSR for each individual coefficients, taking its squared
root, and multiplying by the sign of the corresponding coefficient
leads to the partial correlation. This procedure extends to covariance
structures that can be reparametrised as random effects plus
independent residuals (see previous subsection) such as the compound
symmetry with non-negative correlation.
\begin{description}
\item[{\Warning}] for other covariance structures, especially when the
variance may be repetition-dependent, the definition of explained
variance/partial correlation is not straightforward.
\end{description}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eCS.R2 <- partialCor(eCS.lmm, R2 = TRUE)
summary(eCS.R2)
\end{lstlisting}

\begin{verbatim}

		Partial correlation 

                 estimate    se   df  lower upper p.value
   visit2          -0.073 0.119 52.4 -0.311 0.165 0.54028
   visit3           0.438 0.089 51.4   0.26 0.616 < 1e-04
   visit4            0.07 0.119 52.4 -0.168 0.308 0.55876
   group1          -0.173 0.114 60.7 -0.402 0.056 0.13527
   visit2:group1    0.041 0.119 52.8 -0.198  0.28 0.73256
   visit3:group1    0.284 0.106   52  0.071 0.497 0.01007
   visit4:group1    0.314 0.103   52  0.107 0.521 0.00365
   ------------------------------------------------------ 
  Columns lower and upper contain 95% pointwise confidence intervals for each coefficient.
  Degrees of freedom were computed using a Satterthwaite approximation (column df). 

		Coefficient of determination (R2)

               estimate    se   df  lower upper p.value
   visit          0.274  0.08 50.5  0.114 0.434  0.0012
   group           0.03  0.04 60.7 -0.049 0.109  0.4520
   visit:group    0.147 0.073 51.7 <0.001 0.295  0.0500
   global         0.598 0.053 40.4  0.492 0.705  <1e-04
   ---------------------------------------------------- 
  Columns lower and upper contain 95% pointwise confidence intervals for each coefficient.
  Degrees of freedom were computed using a Satterthwaite approximation (column df).
\end{verbatim}

Here the line "global" refer to the R2 for all covariates, computed
based on the SSR relative to all mean parameters but the intercept.
\begin{description}
\item[{\Warning}] \texttt{partialCor} will compute values for all types of mixed
models. But their interpretation as partial correlation and
proportion of explained variance outside the compound symmetry with
non-negative correlation is questionnable.
\end{description}

\bigskip

\uline{Note:} Other software packages like \texttt{effectsize::eta\_squared} uses
another formula to estimate the partial R2:
\[ R^2=\frac{F df_{num}}{F df_{num} + df_{denom}} \]

where \(F\) denote the F-statistic, \(df_{num}\)
(resp. \(df_{denom}\)) the degrees of freedom of the numerator
(resp. denominator) of this statistic. However since the calculation
of degrees of freedom in LMM is approximate, I would expect this
approach to be less reliable than the one of \texttt{partialCor} based on the
SSR and SSE.

\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
aCS.aov <- anova(eCS.lmm)$multivariate
setNames(with(aCS.aov, statistic*df.num/(statistic*df.num+df.denom)), aCS.aov$test)
\end{lstlisting}

\begin{verbatim}
   visit       group visit:group 
0.335374    0.033811    0.186290
\end{verbatim}



\bigskip


\clearpage

\subsection{Model diagnostic}
\label{sec:org98f4b82}

The method \texttt{residuals} returns the residuals in the wide format:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eUN.diagW <- residuals(eUN.lmm, type = "normalized", format = "wide")
colnames(eUN.diagW) <- gsub("normalized.","",colnames(eUN.diagW))
head(eUN.diagW)
\end{lstlisting}

\begin{verbatim}
  id    r.-13     r.-1       r.1     r.13
1  1 -0.36029 -0.11344  0.377177 -1.45539
2  2  0.77339  2.12301 -0.232908 -0.10708
3  3  1.14219 -1.44778 -0.654876  2.01259
4  4 -0.77473  0.20612 -0.127117 -1.39519
5  5  0.22435       NA  0.011432 -0.15398
6  6  0.27439 -0.67308 -1.031131  0.42724
\end{verbatim}


or in the long format:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eUN.diagL <- residuals(eUN.lmm, type = "normalized", format = "long", keep.data = TRUE)
head(eUN.diagL)
\end{lstlisting}

\begin{verbatim}
  id visit time weight glucagonAUC group baseline fitted r.normalized
1  1     1  -13  127.2      20.690     1     TRUE 25.904     -0.36029
2  2     1  -13  165.2      49.922     0     TRUE 38.729      0.77339
3  3     1  -13  109.7      42.434     1     TRUE 25.904      1.14219
4  4     1  -13  146.2      27.517     0     TRUE 38.729     -0.77473
5  5     1  -13  113.1      29.151     1     TRUE 25.904      0.22435
6  6     1  -13  158.8      42.700     0     TRUE 38.729      0.27439
\end{verbatim}


Various type of residuals can be extract but the normalized one are
recommanded when doing model checking. Diagnostic plots can then be
generated by the user, or directly from the \texttt{lmm} object via the
method \texttt{plot} (which internally calls the \texttt{residuals} method):
\begin{itemize}
\item misspecification of the mean structure
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
plot(eUN.lmm, type = "scatterplot")
\end{lstlisting}

\begin{center}
\includegraphics[width=0.4\textwidth]{./figures/diag-scatterplot.pdf}
\end{center}

\clearpage

\begin{itemize}
\item misspecification of the variance structure
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
plot(eUN.lmm, type = "scatterplot2")
\end{lstlisting}

\begin{center}
\includegraphics[width=0.4\textwidth]{./figures/diag-scatterplot2.pdf}
\end{center}

\begin{itemize}
\item misspecification of the correlation structure
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
plot(eUN.lmm, type = "correlation", type.residual = "response")
plot(eUN.lmm, type = "correlation", type.residual = "normalized")
\end{lstlisting}

\begin{center}
\includegraphics[width=0.6\textwidth]{./figures/diag-correlation.pdf}
\end{center}

\begin{itemize}
\item residual distribution vs. normal distribution \footnote{see \cite{oldford2016self} for guidance
about how to read quantile-quantile plots.}:
\end{itemize}

\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
plot(eUN.lmm, type = "qqplot", engine = "qqtest",
     facet = ~time, labeller = "label_both", facet_nrow=1)
## Note: the qqtest package to be installed to use the argument engine.plot = "qqtest" 
\end{lstlisting}

\begin{center}
\includegraphics[width=\textwidth]{./figures/diag-qqplot.pdf}
\end{center}

\Warning Deviation from the normal distribution does not necessarily
question the validity of the statistical inference. Moreover, for
variance and correlation parameters, normally distributed data is not
enougth to ensure valid statistical inference. Instead one could
assess whether the log-likelihood is locally quadratic as this ensures
normally distributed estimates in finite samples
\citep{geyer2013asymptotics}. Since the likelihood function is a
multi-dimensional function this is not an easy task but one can look
at specific 'slices' using the \texttt{profile} method:

\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eUN.lmm_profile <- profile(eUN.lmm, effects = c("sigma","rho(-13,-1)"))
plot(eUN.lmm_profile)
\end{lstlisting}


\begin{center}
\includegraphics[width=0.75\textwidth]{./figures/diag-profileUN.pdf}
\end{center}

\clearpage

\subsection{Visualize model fit}
\label{sec:orgb5816c5}

The fitted values can be displayed via the \texttt{plot} method:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
## left panel
plot(eUN.lmm, type = "fit", color = "group", size.text = 20)
\end{lstlisting}

\Warning the shaded area represent 95\% confidence intervals (CIs),
  i.e. is not adjusted for multiplicity over time. More explicit (but
  sometimes less readable) representation of the CIs can be obtained
  by setting the argument \texttt{ci.alpha} to \texttt{NA}:

\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
## middle panel
plot(eUN.lmm, type = "fit", color = "group", ci.alpha = NA, size.text = 20)
\end{lstlisting}

\noindent It is also possible to display the observed values along with the
fitted values by setting the argument \texttt{obs.alpha} to a strictly
positive value below or equal to 1. This argument controls the
transparency of the color used to display the observed values:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
## right panel
plot(eUN.lmm, type = "fit", obs.alpha = 0.25, ci = FALSE, size.text = 20)
\end{lstlisting}

\begin{minipage}{0.3\linewidth}
\begin{center}
\includegraphics[width=\textwidth]{./figures/fit-autoplot.pdf}
\end{center}
\end{minipage}
\begin{minipage}{0.3\linewidth}
\begin{center}
\includegraphics[width=\textwidth]{./figures/fit-autoplot2.pdf}
\end{center}
\end{minipage}
\begin{minipage}{0.3\linewidth}
\begin{center}
\includegraphics[width=\textwidth]{./figures/fitAll-autoplot.pdf}
\end{center}
\end{minipage}


When considering continuous covariates, e.g.:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
## add baseline weight
gastricbypassLB <- merge(gastricbypassL, gastricbypassW[c("id","weight1")], by = "id")

eUN.lmmB <- lmm(glucagonAUC ~ weight1 + visit*group, repetition = ~time|id,
                structure = "UN", data = gastricbypassLB)
\end{lstlisting}


\noindent The default graphical display can be confusing as it shows
one curve per distinct set of covariate values, i.e. one line per
subject:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
## left panel
plot(eUN.lmmB, type = "fit", color = "group", ci = FALSE, size.text = 20)
\end{lstlisting}

It is possible to restrict the display specific to a covariate value
via the argument \texttt{at}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
## middel panel
plot(eUN.lmmB, type = "fit", color = "group", ci = FALSE, size.text = 20,
     at = data.frame(weight1 = 150), obs.alpha = 0.2)
\end{lstlisting}

\clearpage

The \texttt{plot} method calls the \texttt{autoplot} methods which returns a list
containing:
\begin{itemize}
\item a ggplot2 object (element \texttt{plot})
\item the dataset used to generate the ggplot2 object (element \texttt{data})
\end{itemize}
This should ease further customization of the graphical display, e.g.:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
## right panel
gg.traj <- autoplot(eUN.lmmB, type = "fit", color = "group", size.text = 20, facet =~id)
gg.traj$plot + theme(legend.position = "bottom")
\end{lstlisting}

\begin{minipage}{0.3\linewidth}
\begin{center}
\includegraphics[width=\textwidth]{./figures/fit-baseline-autoplot.pdf}
\end{center}
\end{minipage}
\begin{minipage}{0.3\linewidth}
\begin{center}
\includegraphics[width=\textwidth]{./figures/fitAll-autoplot.pdf}
\end{center}
\end{minipage}
\begin{minipage}{0.3\linewidth}
\begin{center}
\includegraphics[width=\textwidth]{./figures/fit-autoplot-indiv.pdf}
\end{center}
\end{minipage}

\clearpage

\subsection{Partial residuals}
\label{sec:orga26c8f7}

In a linear model where we split the covariates and mean parameters into two sets:
\begin{align*}
Y_i = X_{1,i} \beta_1 + X_{2,i} \beta_2 + \varepsilon_i
\end{align*}

\noindent the partial residuals w.r.t. to the covariate(s) \(X_2\) are defined
by \(\varepsilon^{X_2}_{i} = Y_i - X_{1,i} \beta_1\). \newline They can be
computed via the \texttt{residuals} method:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
df.pres <- residuals(eUN.lmmB, type = "partial", variable = "weight1", keep.data = TRUE)
head(df.pres)
\end{lstlisting}

\begin{verbatim}
  id visit time weight glucagonAUC group baseline weight1  fitted r.partial
1  1     1  -13  127.2      20.690     0     TRUE   127.2 -20.684  -25.3242
2  1     1    1  115.5      92.600     0    FALSE   127.2 -20.684  -12.2923
3  1     1   -1  120.7      20.535     0     TRUE   127.2 -20.684  -24.7703
4  1     1   13  108.1      43.434     0    FALSE   127.2 -20.684  -37.3259
5 10     1   13   90.9      57.942     0    FALSE   118.0 -19.188   -7.1423
6 10     1    1   99.3     103.728     0    FALSE   118.0 -19.188   11.7323
\end{verbatim}


In the output, the \(X_1\) covariates (\texttt{time} and \texttt{group}) have been
set to the reference level (\texttt{-13} and \texttt{0}) for all
observations. Confusion with the ordering variable from the
\texttt{repetition} argument of \texttt{lmm} was avoided by using a different 'time'
variable in the mean (\texttt{time}) and repetition argument (\texttt{visit}) when
calling \texttt{lmm}.  These residuals can be directly displayed via the
\texttt{plot} method:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
## left panel
plot(eUN.lmmB, type = "partial", variable = "weight1")
## right panel
plot(eUN.lmmB, type = "partial", variable = c("(Intercept)","weight1"))
\end{lstlisting}

\begin{center}
\includegraphics[width=0.75\textwidth]{./figures/fit-pres.pdf}
\end{center}

The \texttt{plot} methods can handle one continuous and one categorical
covariate (in addition to the intercept) to display interaction
plots. In that case each observation/fitted line is colored according
to the categorical covariate.

\clearpage

\subsection{Statistical inference (single model, linear)}
\label{sec:orgf86f6a7}

The \texttt{anova} method can be used to test one or several linear
combinations of the model coefficients using Wald tests. By default,
it will simultaneously test all parameters associated to a variable:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
anova(eUN.lmm)
\end{lstlisting}

\begin{verbatim}
	     Multivariate Wald test 

                  F-statistic       df p.value   
mean: visit             5.803 (3,16.9) 0.00647 **
    : group             3.926 (1,18.0) 0.06302  .
    : visit:group       2.762 (3,17.3) 0.07332  .
\end{verbatim}


Note that here the p-values are not adjust for multiple comparisons
over variables. It is possible to specify a null hypothesis to be
test: e.g. is there a change in average weight just after taking the
treatment in the reference group:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
anova(eUN.lmm, effects = c("visit3-visit2=0"))
\end{lstlisting}

\begin{verbatim}
	     Multivariate Wald test 

       F-statistic       df p.value   
all: 1      14.318 (1,17.8) 0.00138 **
\end{verbatim}


One can also simulateneously tests several null hypotheses:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.anova <- anova(eUN.lmm, effects = c("visit3-visit2=0","visit4-visit2=0"))
summary(e.anova)
\end{lstlisting}

\begin{verbatim}
		Multivariate Wald test 

          F-statistic       df p.value   
   all: 1       8.512 (2,17.2)  0.0027 **
   -------------------------------------- 
  Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1.
  Degrees of freedom were computed using a Satterthwaite approximation (column df). 

		Univariate Wald test 

                   estimate    se   df  lower  upper p.value   
   visit3 - visit2   36.167 9.558 17.8 13.381 58.953 0.00263 **
   visit4 - visit2    9.256 7.738   18 -9.192 27.704 0.38153   
   ------------------------------------------------------------ 
  Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1.
  Columns lower/upper/p.value adjusted for multiple comparisons -- max-test.
  (1e+05 samples have been used)
  Model-based standard errors are derived from the observed information (column se). 
  Degrees of freedom were computed using a Satterthwaite approximation (column df).
\end{verbatim}

\clearpage

or return all pairwise comparisons for a given factor using the \texttt{mcp}
function of the multcomp package:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
library(multcomp)
summary(anova(eUN.lmm, effects = mcp(visit = "Tukey")))
\end{lstlisting}

\begin{verbatim}
Singular contrast matrix: contrasts "3 - 2" "4 - 2" "4 - 3" have been removed. 

		Multivariate Wald test 

              F-statistic       df p.value   
   all: visit       5.803 (3,16.9) 0.00647 **
   ------------------------------------------ 
  Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1.
  Degrees of freedom were computed using a Satterthwaite approximation (column df). 

		Univariate Wald test 

         estimate    se   df   lower  upper p.value   
   2 - 1   -4.734 2.776 17.5 -12.451  2.982 0.32482   
   3 - 1   31.433  8.63 17.6   7.444 55.422 0.00860 **
   4 - 1    4.521 8.005   18 -17.731 26.774 0.93260   
   3 - 2   36.167 9.558 17.8   9.597 62.737 0.00660 **
   4 - 2    9.256 7.738   18 -12.256 30.767 0.60663   
   4 - 3  -26.912 7.448 16.4 -47.615 -6.209 0.00916 **
   --------------------------------------------------- 
  Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1.
  Columns lower/upper/p.value adjusted for multiple comparisons -- max-test.
  (1e+05 samples have been used)
  Model-based standard errors are derived from the observed information (column se). 
  Degrees of freedom were computed using a Satterthwaite approximation (column df). 

Warning message:
In mcp2matrix(model, linfct = linfct) :
  covariate interactions found -- default contrast might be inappropriate
\end{verbatim}

Here the \texttt{summary} method prints not only the global test but also the
result associated to each hypothesis. The warning is triggered by the
presence of an interaction between \texttt{visit} and \texttt{group}: the time
effect is only tested here for the reference group. One should look
also at the time effect in the other group before concluding about the
possible absence of a time effect.

\bigskip

\textbf{Special characters}: special characters, such as parentheses or
mathematical operators, can cause problems when using this
formula-like interface to specify linear contrasts on parameters. This
typically arises when testing (transformed) variance or correlation parameters,
parentheses:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
try(
  anova(eUN.lmm,
        effects = c("log(k).-1=0","log(k).1=0","log(k).13=0"))
)
\end{lstlisting}

\begin{verbatim}
Error in .anova_Wald(object, effects = effects, robust = robust, multivariate = multivariate,  : 
  Possible mispecification of the argument 'effects' as running mulcomp::glht lead to the following error: 
Error in parse(text = ex[i]) : <text>:1:7: unexpected symbol
1: log(k).
          ^
\end{verbatim}


It is then advised to build a contrast matrix, e.g.:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
name.coef <- rownames(confint(eUN.lmm, effects = "all"))
name.varcoef <- grep("^k",name.coef, value = TRUE)
C <- matrix(0, nrow = 3, ncol = length(name.coef), dimnames = list(name.varcoef, name.coef))
diag(C[name.varcoef,name.varcoef]) <- 1
C[,1:9]
\end{lstlisting}

\begin{verbatim}
     (Intercept) visit2 visit3 visit4 group1 visit2:group1 visit3:group1 visit4:group1 sigma
k.-1           0      0      0      0      0             0             0             0     0
k.1            0      0      0      0      0             0             0             0     0
k.13           0      0      0      0      0             0             0             0     0
\end{verbatim}


And then call the \texttt{anova} method specifying the null hypothesis via the
contrast matrix:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
anova(eUN.lmm, effects = C)
\end{lstlisting}

\begin{verbatim}
	     Multivariate Wald test 

       F-statistic       df p.value  
all: 1       3.388 (3,25.7)  0.0332 *
\end{verbatim}


\clearpage

\subsection{Statistical inference (multiple models, linear)}
\label{sec:org51f00e1}

It is possible to adjust for multiple testing across several linear
contrasts that may originate from differente \texttt{lmm} using the approach
of \cite{pipper2012versatile}:
\begin{itemize}
\item fit the mixed models using \texttt{lmm}. The LMM must be fitted on the same
dataset (or on subsets on a common larger dataset) with the same \texttt{repetition} argument.
\item use the \texttt{anova} method to indicate which hypotheses are being tested
\item combine the tests using \texttt{rbind}.
\end{itemize}

Here is an (artificial) example:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
Manova <- rbind(anova(eInd.lmm, effects = "visit3:group1 = 0", robust = FALSE),
                anova(eCS.lmm, effects = "visit3:group1 = 0", robust = FALSE),
                anova(eUN.lmm, effects = "visit3:group1 = 0", robust = FALSE),
                name = c("Ind","CS","UN"))
summary(Manova) 
\end{lstlisting}

\begin{verbatim}
		Multivariate Wald test 

          Chi2-statistic      df p.value    
   all: 1          116.9 (3,Inf)  <1e-04 ***
   ----------------------------------------- 
  Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1.

		Univariate Wald test 

                      estimate     se   df  lower  upper p.value  
   Ind: visit3:group1   27.001 14.285 25.3 -1.482 55.485  0.0631 .
   CS: visit3:group1    27.481  11.09 52.8  5.369 49.593  0.0137 *
   UN: visit3:group1    27.571  12.42 17.8  2.808 52.335  0.0268 *
   --------------------------------------------------------------- 
  Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1.
  Columns lower/upper/p.value adjusted for multiple comparisons -- max-test.
  (error when computing the adjusted columns lower/upper/p.value by numerical integration: 0.00073)
  Model-based standard errors are derived from the observed information (column se).
\end{verbatim}

\clearpage

\subsection{Statistical inference (single model, non-linear)}
\label{sec:orgbdfbcb2}

The \texttt{estimate} function can be used to test one or several non-linear
combinations of model coefficients, using a first order delta method
to quantify uncertainty. The combination has to be specified via a
function (argument \texttt{f}). To illustrate its use consider an ANCOVA
analysis:
\[ Y_{i1} = \textcolor{\darkred}{\alpha} + \textcolor{\darkblue}{\beta} Y_{i,0} + \textcolor{\darkgreen}{\gamma} X_{i} + e_{i} \]

\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.ANCOVA <- lm(weight4 ~ weight1 + group, data = gastricbypassW)
summary(e.ANCOVA)$coef
\end{lstlisting}

\begin{verbatim}
            Estimate Std. Error  t value   Pr(>|t|)
(Intercept) -5.92851   8.780064 -0.67522 5.0861e-01
weight1      0.82363   0.064116 12.84598 3.5247e-10
group        4.14046   2.533355  1.63438 1.2056e-01
\end{verbatim}


We can replicate this analysis by first fitting a mixed model:
\[ Y_{ij} = \alpha_j + \gamma_j X_{i} + \varepsilon_{i,j} \text{ where } \varepsilon_i \sim \Gaus \left( \begin{bmatrix} 0 \\ 0 \end{bmatrix}, \begin{bmatrix} \sigma^2_1 & \rho \sigma_1 \sigma_2 \\ \rho \sigma_1 \sigma_2 & \sigma^2_2 \end{bmatrix} \right) \]
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
gastricbypassL14 <- gastricbypassL[gastricbypassL$visit %in% c(1,4),]
gastricbypassL14$visit <- droplevels(gastricbypassL14$visit)
e.lmmANCOVA <- lmm(weight ~ visit + visit:group, repetition = ~visit|id,
                   data = gastricbypassL14)
\end{lstlisting}

and then perform a first order delta-method:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
lava::estimate(e.lmmANCOVA, f = function(p){
  c(Y1 = as.double(p["rho(1,4)"]*p["k.4"]),
    X1 = as.double(p["visit4:group1"]-p["rho(1,4)"]*p["k.4"]*p["visit1:group1"]))
})
\end{lstlisting}

\begin{verbatim}
   estimate       se      df    lower  upper    p.value
Y1  0.82363 0.062309  9.8746  0.68456 0.9627 1.3327e-07
X1  4.14046 2.461978 15.1613 -1.10227 9.3832 1.1309e-01
\end{verbatim}


Indeed:
\begin{align*}
\Esp[Y_{i2}|Y_{i1},X_{i}] &= \alpha_2 + \gamma_2 X_{i} + \rho \frac{\sigma_2}{\sigma_1}\left(Y_{i1} - \alpha_1 - \gamma_1 X_{i}\right) \\
                         &= \textcolor{\darkred}{\alpha_2 - \rho \frac{\sigma_2}{\sigma_1} \alpha_1}
                         + \textcolor{\darkblue}{\rho \frac{\sigma_2}{\sigma_1}Y_{i1}}
                         + \textcolor{\darkgreen}{\left(\gamma_2 - \rho \frac{\sigma_2}{\sigma_1} \gamma_1\right)  X_{i} }
\end{align*}

We obtain identical estimate but different standard-errors/degrees of
freedom compared to the univariate linear model approach. The later is
to be prefer as it does not rely on approximation. The former is
nevertheless useful as it can handle missing data in the outcome
variable.

\clearpage

\subsection{Baseline adjustment}
\label{sec:orgd0dd12a}

In clinical trial the group and intervention variable often do not
coincide, e.g., in presence of baseline measurement. In our running
example, the first two measurement are pre-treatment (i.e. treatment
should be \texttt{"none"}) while the last two measurements are post-treatment
(i.e. treatment should be \texttt{1} or \texttt{2}). The \texttt{baselineAdjustment}
function can be helpful to define a time varying treatment variable:
\begin{itemize}
\item where baseline takes a specific value
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
gastricbypassL$treat <- baselineAdjustment(gastricbypassL, variable = "group",
                                repetition = ~visit|id, constrain = c("1","2"),
                                new.level = "none")
table(treat = gastricbypassL$treat,
      visit = gastricbypassL$visit,
      group = gastricbypassL$group)
\end{lstlisting}

\begin{minipage}{0.45\linewidth}
\begin{verbatim}
, , group = 0

      visit
treat   1  2  3  4
  none 10 10  0  0
  0     0  0 10 10
  1     0  0  0  0
\end{verbatim}

\end{minipage}
\begin{minipage}{0.05\linewidth}
\hphantom{x}
\end{minipage}
\begin{minipage}{0.45\linewidth}
\begin{verbatim}
, , group = 1

      visit
treat   1  2  3  4
  none 10 10  0  0
  0     0  0  0  0
  1     0  0 10 10
\end{verbatim}


\end{minipage}


\begin{itemize}
\item where baseline corresponds to the reference group
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
gastricbypassL$treat2 <- baselineAdjustment(gastricbypassL, variable = "group",
                                 repetition = ~visit|id, constrain = c("1","2"))
table(treat = gastricbypassL$treat2,
      visit = gastricbypassL$visit,
      group = gastricbypassL$group)
\end{lstlisting}

\begin{minipage}{0.45\linewidth}
\begin{verbatim}
, , group = 0

     visit
treat  1  2  3  4
    0 10 10 10 10
    1  0  0  0  0
\end{verbatim}

\end{minipage}
\begin{minipage}{0.05\linewidth}
\hphantom{x}
\end{minipage}
\begin{minipage}{0.45\linewidth}
\begin{verbatim}
, , group = 1

     visit
treat  1  2  3  4
    0 10 10  0  0
    1  0  0 10 10
\end{verbatim}


\end{minipage}

\begin{itemize}
\item including interactions with group
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
gastricbypassL$visitXtreat <- baselineAdjustment(gastricbypassL, variable = "group",
                                      repetition = ~visit|id, constrain = c("1","2"),
                                      collapse.time = ".")

table(treat = gastricbypassL$visitXtreat,
      visit = gastricbypassL$visit,
      group = gastricbypassL$group)
\end{lstlisting}

\begin{minipage}{0.45\linewidth}
\begin{verbatim}
, , group = 0

     visit
treat  1  2  3  4
  1   10  0  0  0
  2    0 10  0  0
  3.0  0  0 10  0
  4.0  0  0  0 10
  3.1  0  0  0  0
  4.1  0  0  0  0
\end{verbatim}
\end{minipage}
\begin{minipage}{0.05\linewidth}
\hphantom{x}
\end{minipage}
\begin{minipage}{0.45\linewidth}
\begin{verbatim}
, , group = 1

     visit
treat  1  2  3  4
  1   10  0  0  0
  2    0 10  0  0
  3.0  0  0  0  0
  4.0  0  0  0  0
  3.1  0  0 10  0
  4.1  0  0  0 10
\end{verbatim}

\end{minipage}

We would then typically like to model group differences only after
baseline (i.e. only at 1 week and 3 months after). This can be
performed using the time varying treatment variable, e.g.:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eC.lmm <- lmm(glucagonAUC ~ visitXtreat, data = gastricbypassL,
              repetition = ~visit|id, structure = "UN")
coef(eC.lmm) ## change from baseline
\end{lstlisting}

\begin{verbatim}
(Intercept)   visitXtreat2 visitXtreat3.0 visitXtreat4.0 visitXtreat3.1 visitXtreat4.1 
    32.3167        -2.7478        34.3703        11.6559        56.0581        27.6108
\end{verbatim}


or
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eC2.lmm <- lmm(glucagonAUC ~ 0 + visitXtreat, data = gastricbypassL,
              repetition = ~visit|id, structure = "UN")
coef(eC2.lmm) ## absolute value
\end{lstlisting}

\begin{verbatim}
visitXtreat1   visitXtreat2 visitXtreat3.0 visitXtreat4.0 visitXtreat3.1 visitXtreat4.1 
      32.317         29.569         66.687         43.973         88.375         59.927
\end{verbatim}


The parametrization however does not (directly) output treatment
effects. Instead one may be tempted to use a formula like
\texttt{treatment*time}. However this will lead to a non-indentifiable
model. Indeed we are only able to estimate a total of 6 means when
constraining the expected baseline value between the two groups to be
the same. Therefore can at most identify 6 effects. However the design
matrix for the interaction model:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
colnames(model.matrix(glucagonAUC ~ treat*visit, data = gastricbypassL))
\end{lstlisting}

\begin{verbatim}
[1] "(Intercept)"   "treat0"        "treat1"        "visit2"        "visit3"        "visit4"       
[7] "treat0:visit2" "treat1:visit2" "treat0:visit3" "treat1:visit3" "treat0:visit4" "treat1:visit4"
\end{verbatim}


contains 12 parameters (i.e. 6 too many). Fortunately, the \texttt{lmm} will
 drop non-identifiable effects from the model and fit the resulting
 simplified model:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eC3.lmm <- lmm(glucagonAUC ~ treat2*visit, data = gastricbypassL,
               repetition = ~visit|id, structure = "UN")
\end{lstlisting}

\begin{verbatim}
Constant values in the design matrix for the mean structure.
Coefficients "treat21" "treat21:visit2" relative to interactions "treat2:visit" have been removed.
\end{verbatim}


with the following coefficients:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
model.tables(eC3.lmm)
\end{lstlisting}

\begin{verbatim}
               estimate      se     df   lower   upper    p.value
(Intercept)     32.3167  3.4764 19.003 25.0407 39.5927 1.6802e-08
visit2          -2.7478  1.9950 19.007 -6.9232  1.4276 1.8441e-01
visit3          34.3703  8.6111 15.161 16.0331 52.7076 1.1573e-03
visit4          11.6559  7.5601 17.328 -4.2715 27.5833 1.4119e-01
treat21:visit3  21.6878 12.2967 13.748 -4.7316 48.1072 9.9982e-02
treat21:visit4  15.9549  9.6174 12.374 -4.9296 36.8395 1.2224e-01
\end{verbatim}


One can vizualize the baseline adjustment via the \texttt{plot} function:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
plot(eC3.lmm, color = "group", ci = FALSE, size.text = 20, obs.alpha = 0.1)
\end{lstlisting}

\begin{center}
\includegraphics[width=0.4\textwidth]{./figures/gg-baseAdj.pdf}
\end{center}

and retrieve the treatment at each timepoint using the \texttt{effects} method:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
effects(eC3.lmm, variable = "treat2", type = "difference")
\end{lstlisting}

\begin{verbatim}
	     Difference in average counterfactual outcome
	      w.r.t 'treat2' values 

                estimate     se   df  lower  upper p.value  
treat2=1-0(t=1)        0      0  Inf      0      0      NA  
treat2=1-0(t=2)        0      0  Inf      0      0      NA  
treat2=1-0(t=3)   21.688 12.297 13.7 -4.732 48.107   0.100 .
treat2=1-0(t=4)   15.955  9.617 12.4  -4.93  36.84   0.122
\end{verbatim}


\clearpage

\subsection{Predictions}
\label{sec:orgfdf09e2}

Two types of predictions can be performed with the \texttt{predict} method:
\begin{itemize}
\item \textbf{static predictions} that are only conditional on the covariates:
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
news <- gastricbypassL[gastricbypassL$id==2,]
news$glucagon <- 0
predict(eUN.lmm, newdata = news, se = TRUE)
\end{lstlisting}

\begin{verbatim}
  estimate     se     df  lower  upper
1   38.729 4.5765 18.003 29.114 48.344
2   33.995 4.1002 17.897 25.377 42.612
3   70.162 8.6491 17.695 51.968 88.356
4   43.250 6.1883 18.005 30.249 56.251
\end{verbatim}


which can be computing by creating a design matrix:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
X.12 <- model.matrix(formula(eUN.lmm), news)
X.12
\end{lstlisting}

\begin{verbatim}
   (Intercept) visit2 visit3 visit4 group1 visit2:group1 visit3:group1 visit4:group1
2            1      0      0      0      0             0             0             0
22           1      1      0      0      0             0             0             0
42           1      0      1      0      0             0             0             0
62           1      0      0      1      0             0             0             0
attr(,"assign")
[1] 0 1 1 1 2 3 3 3
attr(,"contrasts")
attr(,"contrasts")$visit
[1] "contr.treatment"

attr(,"contrasts")$group
[1] "contr.treatment"
\end{verbatim}

and then multiplying it with the regression coefficients:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
X.12 %*% coef(eUN.lmm)
\end{lstlisting}

\begin{verbatim}
     [,1]
2  38.729
22 33.995
42 70.162
62 43.250
\end{verbatim}


\clearpage

\begin{itemize}
\item \textbf{dynamic predictions} that are conditional on the covariates and the
outcome measured at other timepoints. Consider two subjects for who
we would like to predict the weight 1 week before the intervention
based on the weight 3 months before the intervention:
\end{itemize}

\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none,otherkeywords={}, deletekeywords={}}
\begin{lstlisting}
newd <- rbind(
  data.frame(id = 1, time = -13, visit = "1", group = 0, glucagonAUC = coef(eUN.lmm)["(Intercept)"]),
  data.frame(id = 1, time = 1, visit = "3", group = 0, glucagonAUC = NA),
  data.frame(id = 2, time = -13, visit = "1", group = 0, glucagonAUC = 50),
  data.frame(id = 2, time = 1, visit = "3", group = 0, glucagonAUC = NA)
)
predict(eUN.lmm, newdata = newd, type = "dynamic", keep.data = TRUE)
\end{lstlisting}

\begin{verbatim}
  id time visit group glucagonAUC estimate     se     df  lower  upper
1  1  -13     1     0      38.729       NA     NA     NA     NA     NA
2  1    1     3     0          NA   70.162 8.3308 17.592 52.630 87.694
3  2  -13     1     0      50.000       NA     NA     NA     NA     NA
4  2    1     3     0          NA   75.888 9.6360 12.711 55.022 96.753
\end{verbatim}


The first subjects starts with the average glucagon while the second
  starts with a much higher glucagon. The predicted glucagon after the
  operation for the first subject is then the average glucagon while
  it is predicted to be higher for the second subject due to the
  positive correlation over time. The predicted value is computed
  using the formula of the conditional mean for a Gaussian vector:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
mu1 <- coef(eUN.lmm)["(Intercept)"]
mu3 <- mu1 + coef(eUN.lmm)["visit3"]
Omega_11 <- sigma(eUN.lmm)[1,1]
Omega_31 <- sigma(eUN.lmm)[3,1]
as.double(mu3 + Omega_31 * (50 - mu1) / Omega_11)
\end{lstlisting}

\begin{verbatim}
[1] 75.888
\end{verbatim}



\clearpage

\section{Equivalence with other statistical methods}
\label{sec:orgba1321e}
\subsection{Welch two sample t-test}
\label{sec:orgfd9b890}

A two sample t-test:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
t.test(weight4 ~ group, data = gastricbypassW)
\end{lstlisting}

\begin{verbatim}

	Welch Two Sample t-test

data:  weight4 by group
t = 0.591, df = 17.7, p-value = 0.56
alternative hypothesis: true difference in means between group 0 and group 1 is not equal to 0
95 percent confidence interval:
 -11.736  20.916
sample estimates:
mean in group 0 mean in group 1 
         104.66          100.07
\end{verbatim}

is equivalent to an independent covariance pattern with a different
variable for each group:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.ttest4 <- lmm(weight4 ~ group, structure = IND(~group), 
               data = gastricbypassW, trace = FALSE)
model.tables(e.ttest4)
\end{lstlisting}

\begin{verbatim}
            estimate     se      df   lower   upper    p.value
(Intercept)   104.66 5.1045  9.0018  93.113 116.207 7.2710e-09
group          -4.59 7.7607 17.6824 -20.916  11.736 5.6171e-01
\end{verbatim}


\clearpage

\subsection{Paired t-test}
\label{sec:org3bb7378}

With complete data, a paired t-test:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
t.test(gastricbypassW$weight4, gastricbypassW$weight1, paired = TRUE)
\end{lstlisting}

\begin{verbatim}

	Paired t-test

data:  gastricbypassW$weight4 and gastricbypassW$weight1
t = -17.2, df = 19, p-value = 5e-13
alternative hypothesis: true mean difference is not equal to 0
95 percent confidence interval:
 -29.848 -23.362
sample estimates:
mean difference 
        -26.605
\end{verbatim}

is equivalent to a LMM with an unstructured covariate pattern:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.lmm2tt <- lmm(weight ~ visit, repetition = ~visit|id, structure = "UN",
                data = gastricbypassL)
model.tables(e.lmm2tt)["visit4",,drop=FALSE]
\end{lstlisting}

\begin{verbatim}
       estimate     se     df   lower   upper    p.value
visit4  -26.605 1.5494 18.964 -29.848 -23.362 5.1692e-13
\end{verbatim}


\clearpage

\subsection{Welch two sample t-test on the change}
\label{sec:orgebdafcb}

With complete data, a two sample t-test comparing the change from baseline:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
gastricbypassW.0 <- gastricbypassW[gastricbypassW$group==0,]
gastricbypassW.1 <- gastricbypassW[gastricbypassW$group==1,]
t.test(gastricbypassW.0$weight4-gastricbypassW.0$weight1,
       gastricbypassW.1$weight4-gastricbypassW.1$weight1)
\end{lstlisting}

\begin{verbatim}
	Welch Two Sample t-test

data:  gastricbypassW.0$weight4 - gastricbypassW.0$weight1 and gastricbypassW.1$weight4 - gastricbypassW.1$weight1
t = -2.11, df = 13, p-value = 0.055
alternative hypothesis: true difference in means is not equal to 0
95 percent confidence interval:
 -12.16771   0.14771
sample estimates:
mean of x mean of y 
   -29.61    -23.60
\end{verbatim}

is equivalent to a LMM with a stratified unstructured covariate pattern:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.lmm2tt2 <- lmm(weight ~ visit*group, repetition = ~visit|id, structure = UN(~group),
                 data = gastricbypassL)
model.tables(e.lmm2tt2)["visit4:group1",,drop=FALSE]
\end{lstlisting}

\begin{verbatim}
              estimate     se     df    lower  upper p.value
visit4:group1     6.01 2.8511 13.009 -0.14908 12.169   0.055
\end{verbatim}


\clearpage

\subsection{Multiple Student's t-test}
\label{sec:org4ce137a}


Multiple t-tests:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.ttest1 <- lmm(weight1 ~ group, structure = IND(~group), 
                data = gastricbypassW, trace = FALSE)
e.ttest2 <- lmm(weight2 ~ group, structure = IND(~group), 
                data = gastricbypassW, trace = FALSE)
e.ttest3 <- lmm(weight3 ~ group, structure = IND(~group), 
                data = gastricbypassW, trace = FALSE)
\end{lstlisting}

can be adjusted for multiple comparison by first using the \texttt{anova}
function to specify the parameter of interest and combining the
results using \texttt{rbind}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.mttest <- rbind(anova(e.ttest1, effects = "group=0"),
                  anova(e.ttest2, effects = "group=0"),
                  anova(e.ttest3, effects = "group=0"),
                  anova(e.ttest4, effects = "group=0"))
model.tables(e.mttest, method = "bonferroni")
\end{lstlisting}

\begin{verbatim}
               estimate     se     df   lower  upper p.value
weight1: group   -10.60 8.9717 17.965 -35.498 14.298       1
weight2: group    -9.50 8.3951 17.985 -32.795 13.795       1
weight3: group    -8.92 8.1295 17.959 -31.481 13.641       1
weight4: group    -4.59 7.7607 17.682 -26.165 16.985       1
\end{verbatim}


\Warning efficient adjustment for multiple comparisons (like
\texttt{"single-step"}) will not be valid as the correlation structure has
not be specified. To do so it is more conveniently to work with a the
long format:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.mttest2 <- mlmm(weight ~ group, structure = IND(~group),
                  data = gastricbypassL, trace = FALSE,
                  effects = "group1=0", by = "time", repetition = ~time|id)
model.tables(e.mttest2, method = "single-step2")
\end{lstlisting}

\begin{verbatim}
   by parameter estimate     se     df   lower   upper p.value
1 -13    group1   -10.60 8.9717 17.965 -30.989  9.7893 0.31768
2  -1    group1    -9.50 8.3951 17.985 -28.579  9.5789 0.34123
3   1    group1    -8.92 8.1295 17.959 -27.395  9.5551 0.35785
4  13    group1    -4.59 7.7607 17.682 -22.227 13.0470 0.66473
\end{verbatim}


or call the dedicated function \texttt{mt.test}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
mt.test(weight1+weight2+weight3+weight4~group, data = gastricbypassW)
\end{lstlisting}

\begin{verbatim}
       by parameter estimate     se     df   lower   upper p.value
1 weight1     group   -10.60 8.9717 17.965 -30.976  9.7758 0.31870
2 weight2     group    -9.50 8.3951 17.985 -28.566  9.5663 0.34115
3 weight3     group    -8.92 8.1295 17.959 -27.383  9.5429 0.35844
4 weight4     group    -4.59 7.7607 17.682 -22.215 13.0354 0.66272
\end{verbatim}


\clearpage

\subsection{Linear regression on the change}
\label{sec:orgba7076a}

A widely spread approach to analyze longitudinal data is to reduce the
number of repetitions to 1 by working on the change and then apply
'usual' statistical methods. For instance one could compare the pre-
and post- operation values using:

\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
gastricbypassW$changeG41 <- gastricbypassW$glucagonAUC4-gastricbypassW$glucagonAUC1
e.change41 <- lm(changeG41 ~ weight1, data = gastricbypassW)
summary(e.change41)$coef
\end{lstlisting}

\begin{verbatim}
            Estimate Std. Error t value Pr(>|t|)
(Intercept) 88.41370   41.01024  2.1559 0.044871
weight1     -0.53331    0.31432 -1.6967 0.106975
\end{verbatim}


This turns out to be equivalent to the following mixed model:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
gastricbypassL41 <- gastricbypassL[gastricbypassL$visit %in% c(1,4),]
gastricbypassL41$visit <- droplevels(gastricbypassL41$visit)
gastricbypassL41$weight1 <- gastricbypassW$weight1[gastricbypassL41$id]

e.lmm41 <- lmm(glucagonAUC ~ visit + visit*weight1,
               repetition =~ visit|id, structure = "UN",
               data = gastricbypassL41)
model.tables(e.lmm41)
\end{lstlisting}

\begin{verbatim}
                 estimate       se     df     lower     upper p.value
(Intercept)    31.7805917 23.58747 18.003 -17.77425  81.33543 0.19458
visit4         88.4137014 41.01024 18.001   2.25477 174.57264 0.04487
weight1         0.0041566  0.18078 18.003  -0.37565   0.38396 0.98191
visit4:weight1 -0.5333052  0.31432 18.001  -1.19366   0.12705 0.10697
\end{verbatim}


This equivalence only holds as there is no missing data.
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
index.missing41 <- which(is.na(gastricbypassW$changeG41))
index.missing41
\end{lstlisting}

\begin{verbatim}
integer(0)
\end{verbatim}


\clearpage

\subsection{Correlation between changes}
\label{sec:orga2e8f46}

In some studies, one is interested in studying the relation between
two evolutions. Say weight and glucagon before and after the
operation:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
gastricbypassW$changeG41 <- gastricbypassW$glucagonAUC4-gastricbypassW$glucagonAUC1
gastricbypassW$changeW41 <- gastricbypassW$weight4-gastricbypassW$weight1
\end{lstlisting}

\bigskip

One can evaluate their correlation:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
cor.test(gastricbypassW$changeW41, gastricbypassW$changeG41)
\end{lstlisting}

\begin{verbatim}

	Pearson's product-moment correlation

data:  gastricbypassW$changeW41 and gastricbypassW$changeG41
t = 1.89, df = 18, p-value = 0.075
alternative hypothesis: true correlation is not equal to 0
95 percent confidence interval:
 -0.043829  0.719624
sample estimates:
    cor 
0.40658
\end{verbatim}

or regress one against the other:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e2.change41 <- lm(changeG41 ~ changeW41, data = gastricbypassW)
summary(e2.change41)$coef
\end{lstlisting}

\begin{verbatim}
            Estimate Std. Error t value Pr(>|t|)
(Intercept)  65.0794   24.83368  2.6206 0.017331
changeW41     1.7082    0.90473  1.8881 0.075246
\end{verbatim}


This problem can be recast using all measurement as outcomes:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
keep.col <- c("id","weight1","weight4","glucagonAUC1","glucagonAUC4")
gastricbypassL4 <- reshape(gastricbypassW[,keep.col], direction = "long",
                           idvar = "id", varying = 2:5, timevar = "type", v.names = "value")
gastricbypassL4$type <- factor(gastricbypassL4$type, labels = keep.col[-1])
gastricbypassL4 <- gastricbypassL4[order(gastricbypassL4$id),]
head(gastricbypassL4)
\end{lstlisting}

\begin{verbatim}
    id         type   value
1.1  1      weight1 127.200
1.2  1      weight4 108.100
1.3  1 glucagonAUC1  20.690
1.4  1 glucagonAUC4  43.434
2.1  2      weight1 165.200
2.2  2      weight4 132.000
\end{verbatim}


fitting an unstructured mixed model:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.lmm4 <- lmm(value ~ type,
              repetition = ~type|id, structure = "UN",
              data = gastricbypassL4)
\end{lstlisting}

extract the residual covariance matrix:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
sigma.lmm4 <- sigma(e.lmm4)
sigma.lmm4
\end{lstlisting}

\begin{verbatim}
               weight1 weight4 glucagonAUC1 glucagonAUC4
weight1       410.8475  326.84       1.7077     -217.399
weight4       326.8357  290.84     -24.6003     -161.696
glucagonAUC1    1.7077  -24.60     241.7007      -81.649
glucagonAUC4 -217.3994 -161.70     -81.6493      442.464
\end{verbatim}


Deduce the residual covariance matrix for the change:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
Mcon <- cbind(c(-1,1,0,0),c(0,0,-1,1))
sigmeChange.lmm4 <- t(Mcon) %*% sigma.lmm4 %*% Mcon
dimnames(sigmeChange.lmm4) <- list(c("d.weight","d.glucagonAUC"),
                                   c("d.weight","d.glucagonAUC"))
sigmeChange.lmm4
\end{lstlisting}

\begin{verbatim}
              d.weight d.glucagonAUC
d.weight        48.011        82.011
d.glucagonAUC   82.011       847.464
\end{verbatim}


and the corrrelation or covariance:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
cov2cor(sigmeChange.lmm4)[1,2]
sigmeChange.lmm4[1,2]/sigmeChange.lmm4[1,1]
\end{lstlisting}

\begin{verbatim}
[1] 0.40658
[1] 1.7082
\end{verbatim}


The uncertainty can be quantified using a delta method:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
estimate(e.lmm4, function(p){
  Sigma.change <- t(Mcon) %*% sigma(e.lmm4, p = p) %*% Mcon
  c(cor = cov2cor(Sigma.change)[1,2],
    beta = Sigma.change[1,2]/Sigma.change[1,1])
})
\end{lstlisting}

\begin{verbatim}
     estimate      se     df    lower  upper p.value
cor   0.40658 0.19150 2.5925 -0.26078 1.0739 0.13791
beta  1.70818 0.88073 2.6876 -1.28836 4.7047 0.15837
\end{verbatim}


The standard errors and degrees of freedom do not match the univariate
analysis, suggesting poor small sample properties of this
technic.

\clearpage

\section{Missing values and imputation}
\label{sec:org3748bdb}

We reconsider the example of the previous section, but now in presence
of missing values. The \texttt{summarize} function can be used to describe
the amount of missing data at each repetition:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
sss <- summarize(glucagonAUC ~ time, data = gastricbypassL, na.rm = TRUE)
cbind(sss[,1:4], pc = paste0(100 * sss$missing / (sss$missing + sss$observed), "%"))
\end{lstlisting}

\begin{verbatim}
      outcome time observed missing pc
1 glucagonAUC  -13       20       0 0%
2 glucagonAUC   -1       19       1 5%
3 glucagonAUC    1       19       1 5%
4 glucagonAUC   13       20       0 0%
\end{verbatim}


For more detail about the missing data patters, see the \texttt{summarizeNA}
function:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
summarizeNA(data = gastricbypassL, repetition = ~ time|id)
\end{lstlisting}

\begin{verbatim}
    variable frequency missing.pattern n.missing id -13 -1 1 13
       visit        20           00000         0  0   0  0 0  0
      weight        20           00000         0  0   0  0 0  0
 glucagonAUC        18           00000         0  0   0  0 0  0
                     1           00010         1  0   0  0 1  0
                     1           00100         1  0   0  1 0  0
       group        20           00000         0  0   0  0 0  0
    baseline        20           00000         0  0   0  0 0  0
       treat        20           00000         0  0   0  0 0  0
      treat2        20           00000         0  0   0  0 0  0
  timeXtreat        20           00000         0  0   0  0 0  0
 visitXtreat        20           00000         0  0   0  0 0  0
      group2        20           00000         0  0   0  0 0  0
\end{verbatim}

To begin with we will only consider 1 week before and 1 week after
surgery:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
## long format
gastricbypassL32 <- gastricbypassL[gastricbypassL$visit %in% c(3,2),]
gastricbypassL32$visit <- droplevels(gastricbypassL32$visit)
gastricbypassL32$weight1 <- gastricbypassW$weight1[gastricbypassL32$id]
## wide format
gastricbypassW$changeG32 <- gastricbypassW$glucagonAUC3-gastricbypassW$glucagonAUC2
\end{lstlisting}

\clearpage

\subsection{Full information approach}
\label{sec:org9268723}

LMM uses a full information approach:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.lmm32 <- lmm(glucagonAUC ~ visit + visit*weight1,
               repetition =~ visit|id, structure = "UN",
               data = gastricbypassL32)
model.tables(e.lmm32)
\end{lstlisting}

\begin{verbatim}
                estimate       se     df     lower     upper    p.value
(Intercept)      9.24975 20.66248 17.011 -34.34202  52.84153 0.66004717
visit3         170.75489 39.66297 17.808  87.36171 254.14806 0.00043568
weight1          0.15750  0.15734 17.011  -0.17444   0.48945 0.33083625
visit3:weight1  -0.95238  0.30205 17.648  -1.58787  -0.31688 0.00560372
\end{verbatim}


whereas a linear model would perform a complete case approach:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.change32 <- lm(changeG32 ~ weight1, data = gastricbypassW)
summary(e.change32)$coef
\end{lstlisting}

\begin{verbatim}
             Estimate Std. Error t value   Pr(>|t|)
(Intercept) 173.46620   41.75201  4.1547 0.00074599
weight1      -0.96982    0.31589 -3.0701 0.00732363
\end{verbatim}


In the former the likelihood is evaluated using all observations, even
those from individuals with some (but not all) missing outcome values:
baseline is used even if follow-up is missing. In the later the
likelihood is only evaluated on individuals with no missing outcome
values: if follow-up is missing then baseline is not used. Indeed:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
coef(lm(changeG32 ~ weight1, data = gastricbypassW[-c(5,15),]))
\end{lstlisting}

\begin{verbatim}
(Intercept)     weight1 
  173.46620    -0.96982
\end{verbatim}


The estimates of the LMM can be retrived using a linear model where we
have imputed the conditional expectation of the missing values given
the observed value and the estimated model parameters: (see section
\ref{imputation} for a graphical representation)
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
gastricbypassWA <- fitted(e.lmm32, type = "outcome", format = "wide")
gastricbypassWA$change32 <- gastricbypassWA$glucagonAUC_3 - gastricbypassWA$glucagonAUC_2
gastricbypassWA$weight1 <- gastricbypassW$weight1[match(gastricbypassW$id,gastricbypassWA$id)]
coef(lm(change32 ~ weight1, data = gastricbypassWA))
\end{lstlisting}

\begin{verbatim}
(Intercept)     weight1 
  170.75489    -0.95238
\end{verbatim}



\Warning Standard errors, confidence intervals, and p-values from this
linear model should not be trusted as they do not account for the
uncertainty in the imputed values.

\subsection{Complete case approach}
\label{sec:org3af742a}

The \texttt{lmmCC} can be used to obtain the LMM that is equivalent to a
linear regression. In the case of the comparing the change between
groups, the \texttt{repetition} argument should indicate how the change has
been computed:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.lmmCC <- lmmCC(e.change32, repetition = changeG32 ~ glucagonAUC3-glucagonAUC2|id)
model.tables(e.lmmCC)
\end{lstlisting}

\begin{verbatim}
Remove 2 clusters (4 observations) 
 - 2 observations with missing data (2 clusters) 
 - 0 missing repetitions (0 clusters)
               estimate       se df      lower     upper    p.value
(Intercept)  -165.90910 55.22956 16 -282.99061 -48.82760 0.00840925
time          173.46620 41.75201 16   84.95611 261.97630 0.00074594
weight1         1.13813  0.41786 16    0.25231   2.02395 0.01502328
time:weight1   -0.96982  0.31589 16   -1.63948  -0.30017 0.00732343
\end{verbatim}


As output, the data from two clusters (i.e. 4 observations) has been
excluded before fitting the LMM (instead of just the 2 observations
with missing values for the full information approach). The
interaction term of the LMM matches the regression coefficient of the
linear model:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
summary(e.change32)$coef
\end{lstlisting}

\begin{verbatim}
             Estimate Std. Error t value   Pr(>|t|)
(Intercept) 173.46620   41.75201  4.1547 0.00074599
weight1      -0.96982    0.31589 -3.0701 0.00732363
\end{verbatim}


In the case of regressing two changes:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
gastricbypassW$changeW32 <- gastricbypassW$weight3 - gastricbypassW$weight2

e2g.change32 <- lm(changeG32 ~ changeW32 + group, data = gastricbypassW)
summary(e2g.change32)$coef
\end{lstlisting}

\begin{verbatim}
            Estimate Std. Error  t value Pr(>|t|)
(Intercept)   16.998    30.9485  0.54924  0.59093
changeW32     -3.288     5.0127 -0.65594  0.52180
group         26.361    15.7415  1.67463  0.11472
\end{verbatim}


the \texttt{repetition} argument should indicate how each change has
been computed:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e2.lmmCC <-  lmmCC(e2g.change32, repetition = list(changeG32 ~ glucagonAUC3-glucagonAUC2|id,
                                                   changeW32 ~ weight3-weight2|id))
model.tables(e2.lmmCC)
\end{lstlisting}

\begin{verbatim}
Remove 2 clusters (8 observations) 
 - 2 observations with missing data (2 clusters) 
 - 0 missing repetitions (0 clusters)
     estimate      se     df    lower   upper p.value
cor  -0.16699 0.24255 1.7257  -1.3868  1.0529 0.57192
beta -3.28804 4.83126 2.3131 -21.5987 15.0226 0.55791
\end{verbatim}


We retrieve the same estimate for the effect of change in weights but
the uncertainty (standard error, confidence intervals, p.value) do not
match. They should be asymptotically correct but may not have very
good small smaple properties.

\subsection{Imputation}
\label{imputation}
When fitting a linear mixed model on a dataset with missing values:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eUN.lmmNA <- lmm(glucagonAUC ~ time, repetition = ~time|id, data = gastricbypassL)
nobs(eUN.lmmNA)
\end{lstlisting}

\begin{verbatim}
obs         cluster     missing.obs missing.cluster 
 78              20               2               0
\end{verbatim}


It is possible to extract the most likely value for these missing
observations using the \texttt{fitted} function with argument \texttt{impute=TRUE}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eData <- fitted(eUN.lmmNA, type = "outcome", keep.data = TRUE)
eData <- eData[order(eData$id,eData$time),]
eData[eData$id %in% eData[eData$impute,"id"],c("id","visit","time","glucagonAUC","impute")]
\end{lstlisting}

\begin{verbatim}
   id visit time glucagonAUC impute
15 15     1  -13      22.244  FALSE
35 15     2   -1      32.544  FALSE
55 15     3    1      69.719   TRUE
75 15     4   13      85.222  FALSE
5   5     1  -13      29.151  FALSE
25  5     2   -1      26.270   TRUE
45  5     3    1      86.859  FALSE
65  5     4   13      57.970  FALSE
\end{verbatim}


Missing outcome values in the dataset have been replaced by its most
likely value (which is the same as the dynamic prediction, describedy
previously). A column \texttt{impute} has also been added to differentiate
between the the modeled and observed value. Visually:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
ggplot(eData, aes(x=time,y=glucagonAUC, group=id)) + geom_line() + geom_point(aes(color=impute))
\end{lstlisting}

\begin{center}
\includegraphics[trim={0 0 0 0},width=1\textwidth]{./figures/imputation.pdf}
\end{center}

It is possible to sample from the estimated distribution of the
missing value instead of using the most likely value, e.g. accounting
for residual variance and uncertainty related to parameter estimation:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
index.na <- which(is.na(gastricbypassL$glucagonAUC))
set.seed(1)
fitted(eUN.lmmNA, type = "impute", se = c(TRUE,TRUE))[index.na]
set.seed(2)
fitted(eUN.lmmNA, type = "impute", se = c(TRUE,TRUE))[index.na]
set.seed(3)
fitted(eUN.lmmNA, type = "impute", se = c(TRUE,TRUE))[index.na]
\end{lstlisting}

\begin{verbatim}
[1] 21.932 75.390
[1] 20.060 75.428
[1] 19.610 60.684
\end{verbatim}


\clearpage

\subsection{Multiple imputation}
\label{sec:org8ea84d4}

The \texttt{mlmm} function can used to perform stratify analyses, typically
useful when performing multiple imputations. Consider the wide format
of the dataset where a few values are missing:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
data(gastricbypassW, package = "LMMstar")
colSums(is.na(gastricbypassW))
\end{lstlisting}

\begin{verbatim}
          id      weight1      weight2      weight3      weight4 glucagonAUC1 glucagonAUC2 
           0            0            0            0            0            0            1 
glucagonAUC3 glucagonAUC4 
           1            0
\end{verbatim}


We use \texttt{mice} to generate a number of imputed datasets (here 5):
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
library(mice)
set.seed(10)
gastricbypassW.mice <- mice(gastricbypassW, m = 5, printFlag = FALSE)
gastricbypassW.NNA <- complete(gastricbypassW.mice, action = "long")
table(gastricbypassW.NNA$.imp)
\end{lstlisting}

\begin{verbatim}
Warning message:
Number of logged events: 108

 1  2  3  4  5 
20 20 20 20 20
\end{verbatim}


We can then use \texttt{mlmm} to perform a separate linear regression per dataset:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.mlmm <- mlmm(glucagonAUC3~glucagonAUC2+weight2, data=gastricbypassW.NNA,
               by = ".imp", effects = "weight2=0", trace = FALSE)
model.tables(e.mlmm)
\end{lstlisting}

\begin{verbatim}
  by parameter estimate      se     df   lower    upper   p.value
1  1   weight2 -0.79725 0.31970 17.003 -1.4717 -0.12276 0.0232403
2  2   weight2 -0.83352 0.29798 17.003 -1.4622 -0.20486 0.0123742
3  3   weight2 -0.90658 0.28187 17.003 -1.5013 -0.31189 0.0050657
4  4   weight2 -0.90648 0.28183 17.003 -1.5011 -0.31189 0.0050638
5  5   weight2 -0.82477 0.30247 17.003 -1.4629 -0.18663 0.0143469
\end{verbatim}


and pool the results using Rubin's rule:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
model.tables(e.mlmm, method = "pool.rubin")
\end{lstlisting}

\begin{verbatim}
        estimate     se     df   lower    upper  p.value
<1, 5> -0.85372 0.30212 14.741 -1.4987 -0.20878 0.012949
\end{verbatim}


\clearpage

This matches (almost exactly, only the degrees of freedom are a little
different) the results obtained with the mice package:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.mice <- with(data=gastricbypassW.mice,exp=lm(glucagonAUC3~glucagonAUC2+weight2))
summary(pool(e.mice))
\end{lstlisting}

\begin{verbatim}
          term   estimate std.error statistic     df    p.value
1  (Intercept) 178.988359  36.52589  4.900314 14.703 0.00020353
2 glucagonAUC2   0.027599   0.41848  0.065951 15.132 0.94828055
3      weight2  -0.853721   0.30212 -2.825775 14.737 0.01295073
\end{verbatim}


One can use the \texttt{plot} function to obtain a forest plot of the
individual estimates along with the pooled estimate:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
plot(e.mlmm, method = c("pool.rubin","none"))
\end{lstlisting}

\begin{center}
\includegraphics[trim={0 0 0 0},width=1\textwidth]{./figures/forestplot.pdf}
\end{center}

\clearpage

\section{Data generation}
\label{sec:orgb89efd3}
Simulate some data in the wide format:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
set.seed(10) ## ensure reproductibility
n.obs <- 100
n.times <- 4
mu <- rep(0,4)
gamma <- matrix(0, nrow = n.times, ncol = 10) ## add interaction
gamma[,6] <- c(0,1,1.5,1.5)
dW <- sampleRem(n.obs, n.times = n.times, mu = mu, gamma = gamma, format = "wide")
head(round(dW,3))
\end{lstlisting}

\begin{verbatim}
  id X1 X2 X3 X4 X5     X6     X7     X8    X9    X10     Y1     Y2     Y3     Y4
1  1  1  0  1  1  0 -0.367  1.534 -1.894 1.729  0.959  1.791  2.429  3.958  2.991
2  2  1  0  1  2  0 -0.410  2.065  1.766 0.761 -0.563  2.500  4.272  3.002  2.019
3  3  0  0  2  1  0 -1.720 -0.178  2.357 1.966  1.215 -3.208 -5.908 -4.277 -5.154
4  4  0  0  0  1  0  0.923 -2.089  0.233 1.307 -0.906 -2.062  0.397  1.757 -1.380
5  5  0  0  2  1  0  0.987  5.880  0.385 0.028  0.820  7.963  7.870  7.388  8.609
6  6  0  0  1  1  2 -1.075  0.479  2.202 0.900 -0.739  0.109 -1.602 -1.496 -1.841
\end{verbatim}


Simulate some data in the long format:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
set.seed(10) ## ensure reproductibility
dL <- sampleRem(n.obs, n.times = n.times, mu = mu, gamma = gamma, format = "long")
head(dL)
\end{lstlisting}

\begin{verbatim}
  id visit      Y X1 X2 X3 X4 X5       X6     X7      X8      X9      X10
1  1     1 1.7914  1  0  1  1  0 -0.36653 1.5338 -1.8944 1.72887  0.95925
2  1     2 2.4286  1  0  1  1  0 -0.36653 1.5338 -1.8944 1.72887  0.95925
3  1     3 3.9583  1  0  1  1  0 -0.36653 1.5338 -1.8944 1.72887  0.95925
4  1     4 2.9912  1  0  1  1  0 -0.36653 1.5338 -1.8944 1.72887  0.95925
5  2     1 2.5002  1  0  1  2  0 -0.40975 2.0654  1.7658 0.76133 -0.56302
6  2     2 4.2724  1  0  1  2  0 -0.40975 2.0654  1.7658 0.76133 -0.56302
\end{verbatim}


\clearpage

\section{Modifying default options}
\label{sec:org8d6fd6c}
The \texttt{LMMstar.options} method enable to get and set the default options
used by the package. For instance, the default option for the information matrix is:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
LMMstar.options("type.information")
\end{lstlisting}

\begin{verbatim}
$type.information
[1] "observed"
\end{verbatim}


To change the default option to "expected" (faster to compute but less accurate p-values and confidence intervals in small samples) use:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
LMMstar.options(type.information = "expected")
\end{lstlisting}

To restore the original default options do:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
LMMstar.options(reinitialise = TRUE)
\end{lstlisting}

\clearpage

\section{R session}
\label{sec:orgc2e79c0}
Details of the R session used to generate this document:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
sessionInfo()
\end{lstlisting}

\begin{verbatim}
R version 4.3.3 (2024-02-29)
Platform: x86_64-pc-linux-gnu (64-bit)
Running under: Ubuntu 22.04.4 LTS

Matrix products: default
BLAS:   /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.10.0 
LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.10.0

locale:
 [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C               LC_TIME=en_US.UTF-8       
 [4] LC_COLLATE=en_US.UTF-8     LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
 [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                  LC_ADDRESS=C              
[10] LC_TELEPHONE=C             LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       

time zone: Europe/Copenhagen
tzcode source: system (glibc)

attached base packages:
[1] grid      parallel  stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
 [1] mice_3.16.0         emmeans_1.10.0      rlang_1.1.3         numDeriv_2016.8-1.1
 [5] doParallel_1.0.17   iterators_1.0.14    foreach_1.5.2       copula_1.1-3       
 [9] multcomp_1.4-25     TH.data_1.1-2       MASS_7.3-60.0.1     survival_3.5-8     
[13] mvtnorm_1.2-4       lme4_1.1-35.2       Matrix_1.6-5        lava_1.8.0         
[17] nlme_3.1-163        LMMstar_1.1.0       ggpubr_0.6.0        ggplot2_3.5.1      

loaded via a namespace (and not attached):
 [1] pbapply_1.7-2       gridExtra_2.3       pspline_1.0-19      remotes_2.5.0      
 [5] sandwich_3.1-0      magrittr_2.0.3      butils.base_1.3     compiler_4.3.3     
 [9] mgcv_1.9-1          systemfonts_1.0.6   vctrs_0.6.5         gsl_2.1-8          
[13] stringr_1.5.1       profvis_0.3.8       shape_1.4.6.1       pkgconfig_2.0.3    
[17] fastmap_1.1.1       backports_1.4.1     ellipsis_0.3.2      labeling_0.4.3     
[21] utf8_1.2.4          promises_1.2.1      qqtest_1.2.0        sessioninfo_1.2.2  
[25] nloptr_2.0.3        ragg_1.3.0          purrr_1.0.2         jomo_2.7-6         
[29] glmnet_4.1-8        cachem_1.0.8        later_1.3.2         pan_1.9            
[33] broom_1.0.5         R6_2.5.1            stringi_1.8.3       rpart_4.1.23       
[37] parallelly_1.37.1   car_3.1-2           boot_1.3-30         pkgload_1.3.4      
[41] estimability_1.5    Rcpp_1.0.12         future.apply_1.11.2 zoo_1.8-12         
[45] usethis_2.2.3       nnet_7.3-19         httpuv_1.6.15       splines_4.3.3      
[49] tidyselect_1.2.1    abind_1.4-5         codetools_0.2-19    miniUI_0.1.1.1     
[53] listenv_0.9.1       pkgbuild_1.4.4      lattice_0.22-5      tibble_3.2.1       
[57] shiny_1.8.1.1       withr_3.0.0         coda_0.19-4.1       future_1.33.2      
[61] urlchecker_1.0.1    pillar_1.9.0        carData_3.0-5       stats4_4.3.3       
[65] pcaPP_2.0-4         generics_0.1.3      munsell_0.5.1       scales_1.3.0       
[69] minqa_1.2.6         globals_0.16.3      xtable_1.8-4        glue_1.7.0         
[73] ADGofTest_0.3       tools_4.3.3         data.table_1.15.4   ggsignif_0.6.4     
[77] fs_1.6.3            cowplot_1.1.3       tidyr_1.3.1         devtools_2.4.5     
[81] colorspace_2.1-0    cli_3.6.2           textshaping_0.3.7   fansi_1.0.6        
[85] dplyr_1.1.4         gtable_0.3.5        rstatix_0.7.2       stabledist_0.7-1   
[89] digest_0.6.35       pbkrtest_0.5.2      htmlwidgets_1.6.4   farver_2.1.1       
[93] memoise_2.0.1       htmltools_0.5.8.1   lifecycle_1.0.4     mitml_0.4-5        
[97] mime_0.12
\end{verbatim}

\clearpage

\section*{References}
\label{sec:orgc95564c}
\begingroup
\renewcommand{\section}[2]{}

\bibliographystyle{apalike}
\bibliography{bibliography}

\endgroup

\clearpage

\appendix
\titleformat{\section}
{\normalfont\Large\bfseries}{Appendix~\thesection}{1em}{}

\renewcommand{\thefigure}{\Alph{figure}}
\renewcommand{\thetable}{\Alph{table}}
\renewcommand{\theequation}{\Alph{equation}}

\setcounter{figure}{0}    
\setcounter{table}{0}    
\setcounter{equation}{0}    

\section{Likelihood in a linear mixed model}
\label{SM:likelihood}
Denote by \(\VY\) a vector of \(m\) outcomes, \(\VX\) a vector of
\(p\) covariates, \(\mu(\Vparam,\VX)\) the modeled mean, and
\(\Omega(\Vparam,\VX)\) the modeled residual variance-covariance. We
consider \(n\) replicates (i.e. \(\VY_1,\ldots,\VY_n)\) and
\(VX_1,\ldots,\VX_n\)) along with a vector of weights
\(\omega=(w_1,\ldots,w_n)\), which are by default all equal to 1.

\subsection{Log-likelihood}
\label{sec:org57dd27e}

The restricted log-likelihood in a linear mixed model can then be
written:
\begin{align}
\Likelihood(\Vparam|\VY,\VX) =& \textcolor{\darkred}{ \frac{p}{2} \log(2\pi)-\frac{1}{2} \log\left(\left|\sum_{i=1}^n w_i \VX_i \Omega_i^{-1}(\Vparam) \trans{\VX}_i\right|\right)} \notag \\
& + \sum_{i=1}^{n} w_i \left(\textcolor{\darkblue}{-\frac{m}{2} \log(2\pi) - \frac{1}{2} \log\left|\Omega_i(\Vparam)\right| - \frac{1}{2} (\VY_i-\mu(\Vparam,\VX_i)) \Omega_i(\Vparam)^{-1} \trans{(\VY_i-\mu(\Vparam,\VX_i))}} \right)  \label{eq:log-likelihood}
\end{align}

This is what the \texttt{logLik} method is computing for the REML
criteria. The red term is specific to the REML criteria and prevents
from computing individual contributions to the likelihood\footnote{The REML is the
likelihood of the observations divided by the prior on the estimated
mean parameters \(\VparamHat_{\mu} \sim \Gaus(\mu,\left(\VX
 \Omega^{-1}(\Vparam) \trans{\VX}\right)^{-1})\). This corresponds to
\(\frac{1}{\sqrt{2\pi}^p \left|\left(\sum_{i=1}^n \VX_i
 \Omega_i^{-1}(\Vparam) \trans{\VX}_i\right)^{-1}\right|}
 \exp\left(-(\VparamHat_{\mu}-\mu)\left(2\sum_{i=1}^n \VX_i
 \Omega_i^{-1}(\Vparam)
 \trans{\VX}_i\right)^{-1})\trans{(\VparamHat_{\mu}-\mu)}\right)\)
Since \(\mu\) will be estimated to be \(\Vparam_{\mu}\), the
exponential term equals 1 and thus does not contribute to the
log-likelihood. One divided by the other term gives \(\sqrt{2\pi}^p
 \left(\left|\sum_{i=1}^n \VX_i \Omega_i^{-1}(\Vparam)
 \trans{\VX}_i\right|\right)^{-1}\). The log of this term equals the red
term}. The blue term is what \texttt{logLik} outputs for the ML criteria
when setting the argument \texttt{indiv} to \texttt{TRUE}.

\bigskip

\subsection{Score}
\label{sec:orgd2dc89e}

 Using that \(\partial \log(\det(X))=tr(X^{-1}\partial(X))\), the
score is obtained by derivating once the log-likelihood, i.e., for
\(\theta \in \Vparam\):
\begin{align*}
   \Score(\theta) =& \dpartial[\Likelihood(\Vparam|\VY,\VX)][\theta]
= \textcolor{\darkred}{ \frac{1}{2} tr \left( \left(\sum_{i=1}^n w_i \VX_i \Omega_i^{-1}(\Vparam) \trans{\VX}_i\right)^{-1} \left(\sum_{i=1}^n w_i \VX_i \Omega_i^{-1}(\Vparam) \dpartial[\Omega_i(\Vparam)][\theta] \Omega_i(\Vparam)^{-1} \trans{\VX}_i\right)  \right) } \\
&+ \sum_{i=1}^n w_i \left( \textcolor{\darkblue}{ -\frac{1}{2} tr\left(\Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta]\right) + \dpartial[\mu(\Vparam,\VX_i)][\theta] \Omega_i(\Vparam)^{-1} \trans{(\VY_i-\mu(\Vparam,\VX_i))} } \right. \\
 & \qquad \qquad \left. \textcolor{\darkblue}{ + \frac{1}{2} (\VY_i-\mu(\Vparam,\VX_i)) \Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta] \Omega_i(\Vparam)^{-1} \trans{(\VY_i-\mu(\Vparam,\VX_i))} } \right).
\end{align*}

This is what the \texttt{score} method is computing for the REML
criteria. The red term is specific to the REML criteria and prevents
from computing the score relative to each cluster. The blue term is
what \texttt{score} outputs for the ML criteria when setting the argument
\texttt{indiv} to \texttt{TRUE}.

\bigskip

\clearpage

\subsection{Hessian}
\label{sec:org3e0d5d9}

Derivating a second time the log-likelihood gives the hessian, \(\Hessian(\Vparam)\), with element\footnote{if one is relative to the mean and the other to the variance then they are respectively \(\theta\) and \(\theta'\)}:
\begin{align*}
& \Hessian(\theta,\theta^{\prime}) = \ddpartial[\Likelihood(\Vparam|\VY,\VX)][\theta][\theta^{\prime}] = \dpartial[\Score(\theta)][\theta^{\prime}] \\
=& \textcolor{\darkred}{\frac{1}{2} tr \left( \left(\sum_{i=1}^n w_i \VX_i \Omega_i^{-1}(\Vparam) \trans{\VX}_i\right)^{-1} \left\{ \sum_{i=1}^n w_i \VX_i \Omega_i^{-1}(\Vparam) \left(\ddpartial[\Omega_i(\Vparam)][\theta][\theta^{\prime}] - 2 \dpartial[\Omega_i(\Vparam)][\theta] \Omega_i^{-1}(\Vparam) \dpartial[\Omega_i(\Vparam)][\theta^{\prime}]\right)\Omega_i(\Vparam)^{-1} \trans{\VX}_i \right.  \right.}  \\
& \textcolor{\darkred}{ \left. \left. + \left(\sum_{i=1}^n w_i \VX_i \Omega_i^{-1}(\Vparam) \dpartial[\Omega_i(\Vparam)][\theta] \Omega_i(\Vparam)^{-1} \trans{\VX}_i\right) \left(\sum_{i=1}^n w_i \VX_i\Omega_i^{-1}(\Vparam) \trans{\VX}_i \right)^{-1} \left(\sum_{i=1}^n w_i \VX_i \Omega_i^{-1}(\Vparam) \dpartial[\Omega_i(\Vparam)][\theta^{\prime}] \Omega_i(\Vparam)^{-1} \trans{\VX}_i\right) \right\} \right) } \\
& +\sum_{i=1}^n w_i \left( \textcolor{\darkblue}{ \frac{1}{2} tr\left(\Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta^{\prime}] \Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta] - \Omega_i(\Vparam)^{-1} \ddpartial[\Omega_i(\Vparam)][\theta][\theta^{\prime}] \right) } \right.\\
& \qquad \textcolor{\darkblue}{ -  \dpartial[\mu(\Vparam,\VX_i)][\theta] \Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta^{\prime}] \Omega_i(\Vparam)^{-1} \trans{\Vvarepsilon_i(\Vparam)} - \dpartial[\mu(\Vparam,\VX_i)][\theta] \Omega_i(\Vparam)^{-1} \trans{\dpartial[\mu(\Vparam,\VX_i)][\theta^{\prime}]} } \\
& \qquad \left. \textcolor{\darkblue}{ + \frac{1}{2} \Vvarepsilon_i(\Vparam) \Omega_i(\Vparam)^{-1} \left(\ddpartial[\Omega_i(\Vparam)][\theta][\theta^{\prime}] - \dpartial[\Omega_i(\Vparam)][\theta^{\prime}] \Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta] - \dpartial[\Omega_i(\Vparam)][\theta] \Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta^{\prime}] \right) \Omega_i(\Vparam)^{-1} \trans{\Vvarepsilon_i(\Vparam)} } \right).
\end{align*}
where \(\Vvarepsilon_i(\Vparam) = \VY_i-\mu(\Vparam,\VX_i)\).

\bigskip

The \texttt{information} method will (by default) return the (observed)
information which is the opposite of the hessian. So multiplying the
previous formula by -1 gives what \texttt{information} output for the REML
criteria. The red term is specific to the REML criteria and prevents
from computing the information relative to each cluster. The blue term
is what \texttt{information} outputs for the ML criteria (up to a factor -1)
when setting the argument \texttt{indiv} to \texttt{TRUE}.

\bigskip

A possible simplification is to use the expected hessian at the maximum likelihood. Indeed for
any deterministic matrix \(A\):
\begin{itemize}
\item \(\Esp[A \trans{(\VY_i-\mu(\Vparam,\VX_i))}|\VX_i] = 0\)
\item \(\Esp[(\VY_i-\mu(\Vparam,\VX_i)) A \trans{(\VY_i-\mu(\Vparam,\VX_i))}||\VX_i] = tr(A \Var(\VY_i-\mu(\Vparam,\VX_i)))\)
\end{itemize}
when \(\Esp[\VY_i-\mu(\Vparam,\VX_i)]=0\). This leads to:
\begin{align}
 & \Esp[\Hessian(\theta,\theta^{\prime})|\VX] \notag\\ 
 &= \textcolor{\darkred}{ \frac{1}{2} tr \left( \left(\sum_{i=1}^n w_i \VX_i \Omega_i^{-1}(\Vparam) \trans{\VX}_i\right)^{-1}  \left\{ \sum_{i=1}^n w_i \VX_i \Omega_i^{-1}(\Vparam) \left( \ddpartial[\Omega_i(\Vparam)][\theta][\theta^{\prime}] - 2 \dpartial[\Omega_i(\Vparam)][\theta]  \Omega_i^{-1}(\Vparam) \dpartial[\Omega_i(\Vparam)][\theta^{\prime}]\right) \Omega_i(\Vparam)^{-1} \trans{\VX}_i \right.  \right.} \notag \\
 & \textcolor{\darkred}{ \left. \left. +  \left(\sum_{i=1}^n w_i \VX_i \Omega_i^{-1}(\Vparam) \dpartial[\Omega_i(\Vparam)][\theta] \Omega_i(\Vparam)^{-1} \trans{\VX}_i\right) \left(\sum_{i=1}^n w_i \VX_i \Omega_i^{-1}(\Vparam) \trans{\VX}_i \right)^{-1} \left(\sum_{i=1}^n w_i \VX_i \Omega_i^{-1}(\Vparam) \dpartial[\Omega_i(\Vparam)][\theta^{\prime}] \Omega_i(\Vparam)^{-1} \trans{\VX}_i\right) \right\} \right) } \notag\\
 & + \sum_{i=1}^n w_i \left( \textcolor{\darkblue}{
- \frac{1}{2} tr\left(\Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta^{\prime}] \Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta]\right)
 - \dpartial[\mu(\Vparam,\VX_i)][\theta] \Omega_i(\Vparam)^{-1} \trans{\dpartial[\mu(\Vparam,\VX_i)][\theta^{\prime}]}
 } \right) \label{eq:expectedInfo}
\end{align}

This is what \texttt{information} output when the argument \texttt{type.information}
is set to \texttt{"expected"} (up to a factor -1).

\clearpage

\subsection{Degrees of freedom}
\label{sec:orgc8efa7b}

Degrees of freedom are computed using a Satterthwaite approximation,
i.e. for an estimate coefficient \(\widehat{\beta}\in\widehat{\Vparam}\) with standard
error \(\sigma_{\widehat{\beta}}\), the degree of freedom is:
\begin{align*}
df\left(\sigma_{\widehat{\beta}}\right) = \frac{2 \sigma^4_{\widehat{\beta}}}{\Var[\widehat{\sigma}_{\widehat{\beta}}]}
\end{align*}
Using a first order Taylor expansion we can approximate the variance term as:
\begin{align*}
\Var[\widehat{\sigma}_{\widehat{\beta}}] & \approx \dpartial[\widehat{\sigma}_{\widehat{\beta}}][\Vparam] \Sigma_{\Vparam}  \trans{\dpartial[\widehat{\sigma}_{\widehat{\beta}}][\Vparam]} \\
& \approx c_{\beta} \left(\widehat{\Information}_{\widehat{\Vparam}}\right)^{-1} \dpartial[\widehat{\Information}_{\widehat{\Vparam}}][\Vparam] \left(\widehat{\Information}_{\widehat{\Vparam}}\right)^{-1} \trans{c_{\beta}} \Sigma_{\Vparam} \trans{c_{\beta}} \left(\widehat{\Information}_{\widehat{\Vparam}}\right)^{-1} \trans{\dpartial[\widehat{\Information}_{\widehat{\Vparam}}][\Vparam]} \left(\widehat{\Information}_{\widehat{\Vparam}}\right)^{-1} c_{\beta}
\end{align*}

where \(\Sigma_{\Vparam}\) is the variance-covariance matrix of all
  model coefficients, \(\Information_{\Vparam}\) the information
  matrix for all model coefficients, \(c_{\beta}\) a matrix used to
  select the element relative to \(\beta\) in the first derivative of
  the information matrix, and \(\dpartial[.][\Vparam]\) denotes the
  vector of derivatives with respect to all model coefficients.

\bigskip

The derivative of the information matrix (i.e. negative hessian) can
then be computed using numerical derivatives or using analytical
formula. To obtain the later we first notice that:
\begin{align}
&\Hessian(\theta,\theta^{\prime}) = \Esp[\Hessian(\theta,\theta^{\prime})|\VX] \notag \\
& + \sum_{i=1}^n  w_i \left( \textcolor{\darkblue}{ tr\left(\Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta^{\prime}] \Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta] - \Omega_i(\Vparam)^{-1} \ddpartial[\Omega_i(\Vparam)][\theta][\theta^{\prime}] \right) } \right. \notag \\
& \qquad \textcolor{\darkblue}{ -  \dpartial[\mu(\Vparam,\VX_i)][\theta] \Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta^{\prime}] \Omega_i(\Vparam)^{-1} \trans{\Vvarepsilon_i(\Vparam)}} \notag \\
& \qquad \left. \textcolor{\darkblue}{ + \frac{1}{2} \Vvarepsilon_i(\Vparam) \Omega_i(\Vparam)^{-1} \left(\ddpartial[\Omega_i(\Vparam)][\theta][\theta^{\prime}] - \dpartial[\Omega_i(\Vparam)][\theta^{\prime}] \Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta] - \dpartial[\Omega_i(\Vparam)][\theta] \Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta^{\prime}] \right) \Omega_i(\Vparam)^{-1} \trans{\Vvarepsilon_i(\Vparam)} } \right) \label{eq:diffInfo}
\end{align}
where
\begin{align*}
\Esp[\Hessian(\theta,\theta^{\prime})|\VX] &=& \textcolor{\darkred}{
\frac{1}{2} tr \left(A(\Vparam)^{-1} \left(\sum_{i=1}^n w_i b_i(\Vparam) B_i(\Vparam) \trans{b}_i(\Vparam) + C(\Vparam)A(\Vparam)^{-1} \trans{C}(\Vparam) \right)\right)
}  + \sum_{i=1}^n w_i \textcolor{\darkblue}{E_i(\Vparam)} \\
\textcolor{\darkblue}{E_i(\Vparam)} &=& \textcolor{\darkblue}{\frac{1}{2} tr\left(\Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta^{\prime}] \Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta]\right)
                                        - \dpartial[\mu(\Vparam,\VX_i)][\theta] \Omega_i(\Vparam)^{-1} \trans{\dpartial[\mu(\Vparam,\VX_i)][\theta^{\prime}]}} \\
\textcolor{\darkred}{A(\Theta)} &=& \textcolor{\darkred}{\sum_{i=1}^n w_i \VX_i \Omega_i^{-1}(\Vparam) \trans{\VX}_i }\\
\textcolor{\darkred}{B(\Theta)} &=& \textcolor{\darkred}{\ddpartial[\Omega_i(\Vparam)][\theta][\theta^{\prime}] - 2 \dpartial[\Omega_i(\Vparam)][\theta]  \Omega_i^{-1}(\Vparam) \dpartial[\Omega_i(\Vparam)][\theta^{\prime}] }\\
\textcolor{\darkred}{b_i(\Theta)} &=& \textcolor{\darkred}{\VX_i \Omega_i^{-1} }\\
\textcolor{\darkred}{C(\Theta)} &=& \textcolor{\darkred}{\sum_{i=1}^n w_i \VX_i \Omega_i^{-1}(\Vparam) \dpartial[\Omega_i(\Vparam)][\theta] \Omega_i(\Vparam)^{-1} \trans{\VX}_i }
\end{align*}
So we will first derive the derivative of
\(\Esp[\Hessian(\theta,\theta^{\prime})|\VX]\) and then the one of the
blue term in \autoref{eq:diffInfo}.  To simplify the derivation of the
formula we will only derive them at the maximum likelihood, i.e. when
\(\Esp\left[\dpartial[\Hessian(\theta,\theta^{\prime}|\VX)][\theta^{\prime\prime}]\right]=\frac{\partial
\Esp[\Hessian(\theta,\theta^{\prime}|\VX)]}{\partial
\theta^{\prime\prime}}\) where the expectation is taken over
\(\VX\). We first notice that the derivative with respect to the mean
parameters is 0. So we just need to compute the derivative with
respect to a variance parameter \(\theta^{\prime\prime}\):
\begin{align*}
 & \frac{\partial \textcolor{\darkred}{ A(\Vparam)^{-1} \left(\sum_{i=1}^n w_i b_i(\Vparam) B_i(\Vparam) \trans{b}_i(\Vparam) + C(\Vparam)A(\Vparam)^{-1} \trans{C}(\Vparam) \right)}}{\partial \theta^{\prime\prime}} \\
 =& \textcolor{\darkred}{A(\Vparam)^{-1} \dpartial[A(\Vparam)][\theta^{\prime\prime}] A(\Vparam)^{-1} \left(\sum_{i=1}^n w_i b_i(\Vparam) B_i(\Vparam) \trans{b}_i(\Vparam) + C(\Vparam)A(\Vparam)^{-1} \trans{C}(\Vparam) \right)} \\
 & +\textcolor{\darkred}{A(\Vparam)^{-1} \left(\sum_{i=1}^n w_i \left(
 \dpartial[b_i(\Vparam)][\theta^{\prime\prime}]  B_i(\Vparam) \trans{b}_i(\Vparam)
 + b_i(\Vparam) \dpartial[B_i(\Vparam)][\theta^{\prime\prime}]   \trans{b}_i(\Vparam)
 + b_i(\Vparam) B_i(\Vparam) \dpartial[\trans{b}_i(\Vparam)][\theta^{\prime\prime}] \right. \right. } \\
& \qquad \qquad \qquad \qquad \quad + \textcolor{\darkred}{\left. \left.
 \dpartial[C(\Vparam)][\theta^{\prime\prime}]  A^{-1}(\Vparam) \trans{C}(\Vparam)
 + C(\Vparam) A^{-1}\dpartial[A(\Vparam)][\theta^{\prime\prime}]A^{-1}   \trans{C}(\Vparam)
 + C(\Vparam) A^{-1}(\Vparam) \dpartial[\trans{C}(\Vparam)][\theta^{\prime\prime}]
\right) \right)}
\end{align*}

and

\begin{align*}
 \dpartial[\textcolor{\darkblue}{E(\Vparam)}][\theta^{\prime\prime}]=&
 \sum_{i=1}^n w_i \left( \textcolor{\darkblue}{
- \frac{1}{2} tr\left(
-2\Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta^{\prime\prime}] \Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta^{\prime}] \Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta] \right. } \right. \\
& \qquad \qquad \textcolor{\darkblue}{\left. + \Omega_i(\Vparam)^{-1} \ddpartial[\Omega_i(\Vparam)][\theta^{\prime}][\theta^{\prime\prime}] \Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta]
+ \Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta^{\prime}] \Omega_i(\Vparam)^{-1} \ddpartial[\Omega_i(\Vparam)][\theta][\theta^{\prime\prime}]
\right)} \\
& \qquad \qquad  \textcolor{\darkblue}{\left. + \dpartial[\mu(\Vparam,\VX_i)][\theta] \Omega_i(\Vparam)^{-1} \dpartial[\Omega_i(\Vparam)][\theta^{\prime\prime}] \Omega_i(\Vparam)^{-1}   \trans{\dpartial[\mu(\Vparam,\VX_i)][\theta^{\prime}]}
 \right)}
\end{align*}

where:
\begin{align*}
\textcolor{\darkred}{\dpartial[A(\Vparam)][\theta^{\prime\prime}]} &= \textcolor{\darkred}{\sum_{i=1}^n w_i \VX_i \Omega^{-1}_i(\Vparam) \dpartial[\Omega_i(\Vparam)][\theta^{\prime\prime}]\Omega^{-1}_i(\Vparam) \trans{\VX}_i} \\
\textcolor{\darkred}{\dpartial[b_i(\Vparam)][\theta^{\prime\prime}]} &= \textcolor{\darkred}{\VX_i \Omega^{-1}_i(\Vparam) \dpartial[\Omega_i(\Vparam)][\theta^{\prime\prime}]\Omega^{-1}_i(\Vparam)} \\
\textcolor{\darkred}{\dpartial[B_i(\Vparam)][\theta^{\prime\prime}]} &= \textcolor{\darkred}{
  \frac{\partial^3 \Omega_i(\Vparam)}{\theta\theta^{\prime}\theta^{\prime\prime}} } \\
  & \textcolor{\darkred}{ - 2 \left(
  \ddpartial[\Omega_i(\Vparam)][\theta][\theta^{\prime\prime}]\Omega^{-1}_i(\Vparam)\dpartial[\Omega_i(\Vparam)][\theta^{\prime}]
+ \dpartial[\Omega_i(\Vparam)][\theta]\Omega^{-1}_i(\Vparam)\dpartial[\Omega_i(\Vparam)][\theta^{\prime\prime}]\Omega^{-1}_i(\Vparam)\dpartial[\Omega_i(\Vparam)][\theta^{\prime}]
+ \dpartial[\Omega_i(\Vparam)][\theta]\Omega^{-1}_i(\Vparam)\ddpartial[\Omega_i(\Vparam)][\theta^{\prime}][\theta^{\prime\prime}]
\right)
  } \\
\textcolor{\darkred}{\dpartial[C(\Vparam)][\theta^{\prime\prime}]} &= \textcolor{\darkred}{\sum_{i=1}^n w_i \VX_i \Omega^{-1}_i(\Vparam) \left(
\dpartial[\Omega_i(\Vparam)][\theta^{\prime\prime}] \Omega^{-1}_i(\Vparam) \dpartial[\Omega_i(\Vparam)][\theta]
+ \ddpartial[\Omega_i(\Vparam)][\theta][\theta^{\prime\prime}]
+ \dpartial[\Omega_i(\Vparam)][\theta] \Omega^{-1}_i(\Vparam) \dpartial[\Omega_i(\Vparam)][\theta^{\prime\prime}]
\right) \Omega^{-1}_i(\Vparam) \trans{\VX}_i} 
\end{align*}



\clearpage

\section{Likelihood ratio test with the REML criterion}
\label{SM:LRT-REML}
The blue term of \autoref{eq:log-likelihood} in the log-likelihood is
invariant to re-parameterisation while the red term is not. This means
that a re-parametrisation of \(X\) into \(\tilde{X} = B X\) with \(B\)
invertible would not change the likelihood when using ML but would
decrease the log-likelihood by \(\log(|B|)\) when using REML. \newline
Let's take an example:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
## data(dfL, package = "LMMstar")
dfTest <- gastricbypassL[!is.na(gastricbypassL$glucagonAUC),]
dfTest$gluc <- dfTest$glucagonAUC
dfTest$gluc2 <- dfTest$glucagonAUC*2
\end{lstlisting}

\noindent where we multiply one column of the design matrix by 2. As mentionned
previously this does not affect the log-likelihood when using ML:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eML.UN <- lmm(weight ~ time+gluc, data = dfTest, repetition = ~time|id, method = "ML")
eML.UN2 <- lmm(weight ~ time+gluc, data = dfTest, repetition = ~time|id, method = "ML")
c(logLik(eML.UN), logLik(eML.UN2), logLik(eML.UN) - logLik(eML.UN2))
\end{lstlisting}

\begin{verbatim}
[1] -230.62 -230.62    0.00
\end{verbatim}


but it does when using REML:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eREML.UN <- lmm(weight ~ time + gluc, data = dfTest, repetition = ~time|id, method = "REML")
eREML.UN2 <- lmm(weight ~ time + gluc2, data = dfTest, repetition = ~time|id, method = "REML")
c(logLik(eREML.UN), logLik(eREML.UN2), logLik(eREML.UN) - logLik(eREML.UN2), log(2))
\end{lstlisting}

\begin{verbatim}
[1] -235.23462 -235.92777    0.69315    0.69315
\end{verbatim}



Therefore, when comparing models with different mean effects there is
a risk that the difference (or part of it) in log-likelihood is due to
a new parametrisation and no only to a difference in model fit. This
would typically be the case when adding an interaction where we can
have a smaller restricted log-likehood when considering a more complex
model:

\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
set.seed(5) 
dfTest$ff <- rbinom(NROW(dfTest), size = 1, prob = 0.5)
logLik(lmm(weight ~ time+gluc, data = dfTest, repetition = ~time|id, method = "REML"))
logLik(lmm(weight ~ time+gluc*ff, data = dfTest, repetition = ~time|id, method = "REML"))
\end{lstlisting}

\begin{verbatim}
[1] -235.23
[1] -238.93
\end{verbatim}


This is quite counter-intuitive as more complex model should lead to
better fit and would never happen when using ML:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
logLik(lmm(weight ~ time + gluc, data = dfTest, repetition = ~time|id, method = "ML"))
logLik(lmm(weight ~ time + gluc*ff, data = dfTest, repetition = ~time|id, method = "ML"))
\end{lstlisting}

\begin{verbatim}
[1] -230.62
[1] -230.44
\end{verbatim}


This is why, unless one knows what he/she is doing, it is not
recommanded to use likelihood ratio test to assess relevance of mean
parameters in mixed models estimated with REML.

\clearpage

\section{Sum of squares in a linear mixed model}
\label{SM:sumSquares}
All mixed models implemented in LMMstar can be written as:
\[ Y_{it} = X_{it}\beta + \varepsilon_{it} \text{ where } \varepsilon_{i} \sim \Gaus\left(0,\Omega\right)\]
where \(Y\) denote the outcome repeteadly measured within each cluster
\(i\) where \(t\) indexes the repetitions. \(X\) denotes the
covariates, \(\beta\) the mean parameters, \(\varepsilon\) the
residuals, and \(\Omega\) the residual variance-covariance matrix.
\(\Omega\) must be positive definite so there must exist a square
postive definite matrix \(\Omega^{1/2}\) such that
\(\Omega^{1/2}\Omega^{1/2} = \Omega\). Therefore the previous model is
equivalent to:
\[ Y^*_{it} = X^*_{it}\beta + \varepsilon^*_{it} \text{ where } \varepsilon_{i} \sim \Gaus\left(0,I_T\right)\]
where \(Y^*_{i} = \Omega^{-1/2} Y_{i}\), \(X^*_{i} = \Omega^{-1/2}
X_{i}\), \(\varepsilon^*_{i} = \Omega^{-1/2} \varepsilon_{i}\), and
\(I_x\) is the identity matrix with \(x\) rows and columns. One can
then introduce the projectors \(H= X \left(\trans{X}\Omega^{-1}
X\right)^{-1}\trans{X} \Omega^{-1}\) and \(H^*= X^*
\left(\trans{X^*}X^*\right)^{-1}\trans{X^*}\) onto the space spanned
by \(X\) and \(X^*\) respectively. We can now define the "normalized"
residual sum of squares as the squared sum of the normalized
residuals:
\begin{align*}
SSE^* = \trans{\varepsilon^*} \varepsilon^* &= \trans{Y^*} (I_{nT}-H^*) Y^* \\
&= \trans{Y} \Omega^{-1} Y - \trans{Y} \Omega^{-1} X \left(\trans{X}\Omega^{-1} X\right)^{-1} \trans{X} \Omega^{-1} Y \\
&= \trans{Y} (I_{nT}-\trans{H}) \Omega^{-1} (I_{nT}-H) Y 
\end{align*}
The previous to last line uses that: \((I_{nT}-\trans{H}) \Omega^{-1}
(I_{nT}-H)= \Omega^{-1} - \trans{H} \Omega^{-1} - \Omega^{-1}H +
\trans{H} \Omega^{-1} H = \Omega^{-1} - \trans{H}\Omega^{-1}\) as
\(\trans{H} \Omega^{-1} H = \Omega^{-1}HH=\Omega^{-1}H\) since \(H\)
is a projector. Note that compared to the "traditional" SSE defined
for linear regression and random effect models (e.g. see
\cite{christensen2002plane} section 2.7), \(SSE=\delta SSE^{*}\) where
\(\delta\) is the residual variance conditional on any random effects,
i.e. \(SSE^{*}\) are the residual degrees of freedom. This is because
the same definition for the sum of squares is used except that
\(\varepsilon_{i} \sim \Gaus\left(0,\delta\Omega\right)\).

\bigskip

We can also define the "normalized" regression sum of squares:
\begin{align*}
SSR^* = \trans{(X^*\beta)}X^*\beta &= \trans{\left(H^* Y^*\right)} H^* Y^* = \trans{Y^*} H^* Y^* \\
&= \trans{Y} \trans{H} \Omega^{-1} Y^* = \trans{Y} \trans{H} \trans{H} \Omega^{-1} Y^* = \trans{Y} \trans{H} \Omega^{-1} H Y^* \\
&= \widehat{\beta} \trans{X} \Omega^{-1} X \widehat{\beta}
\end{align*}
where \(\widehat{\beta}= \left(\trans{X}\Omega^{-1}
X\right)^{-1}\trans{X} \Omega^{-1} Y\). Note that when using the
expected information \(SSR^* = \widehat{\beta}
\Sigma^{-1}_{\widehat{\beta}} \widehat{\beta}\), i.e. it is the
F-statistics times the number of parameters. Again the "traditional"
SSR defined for linear regression and random effect models is
proportional to this normalized SSR: \(SSR=\delta SSR^{*}\).

\bigskip

The proportion of explained variance of \(p\) parameters can thus be
re-expressed as:
\begin{align*}
R^2 &= \frac{SSR}{SSR+SSE} = \frac{SSR^*}{SSR^*+SSE^*}= \frac{Fp}{Fp+df}
\end{align*}

where \(df\) denotes the residual degrees of freedom, typically
\(n-p\) in a univariate linear model fitted with \(n\)
observations. \newline \Warning In practice \(df\) is estimated using the
Satterthwaite approximation of the degrees of freedom of the
regression coefficient. This is only equivalent to the "SSR/SSE"
formula in univariate linear regression.

\bigskip
\bigskip

\textbf{Illustration for a univariate linear model:}

\bigskip

Data without missing values:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
df.aov <- gastricbypassL[!is.na(gastricbypassL$glucagon),]
\end{lstlisting}

Traditional anova decomposition:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.lm <- lm(weight ~ visit + glucagonAUC, data = df.aov)
car::Anova(e.lm, type = "II")
\end{lstlisting}

\begin{verbatim}
Anova Table (Type II tests)

Response: weight
            Sum Sq Df F value Pr(>F)   
visit         5837  3    5.94 0.0011 **
glucagonAUC   2133  1    6.51 0.0128 * 
Residuals    23925 73                  
---
Signif. codes:  0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
\end{verbatim}


Fit \texttt{lmm}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.lmm <- lmm(weight ~ visit + glucagonAUC, data = df.aov)
\end{lstlisting}

Residual sum of squares (SSE):
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
SSEstar <- crossprod(residuals(e.lmm, type = "normalized"))
c(SSEstar = SSEstar, SSE = SSEstar * sigma(e.lmm))
\end{lstlisting}

\begin{verbatim}
SSEstar     SSE 
     73   23925
\end{verbatim}


The normalized SSE can also be obtained using the \texttt{df.residual} method:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
df.residual(e.lmm)
\end{lstlisting}

\begin{verbatim}
[1] 73
\end{verbatim}


Regression sum of squares (SSR):
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eBeta.lmm <- coef(e.lmm)
eVcov.lmm <- vcov(e.lmm, type.information = "expected")

SSRstar.glucagon <- eBeta.lmm[5] %*% solve(eVcov.lmm[5,5]) %*% eBeta.lmm[5] 
SSRstar.time <- eBeta.lmm[2:4] %*% solve(eVcov.lmm[2:4,2:4]) %*% eBeta.lmm[2:4] 
c(SSR.glucagon = SSRstar.glucagon * sigma(e.lmm),
  SSR.time = SSRstar.time * sigma(e.lmm),
  F.glucagon = SSRstar.glucagon,
  F.time = SSRstar.time/3)
\end{lstlisting}

\begin{verbatim}
SSR.glucagon     SSR.time   F.glucagon       F.time 
    2132.629     5837.410        6.507        5.937
\end{verbatim}


So the proportion of explained variance is:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
R2.glucagon <- SSRstar.glucagon/(SSRstar.glucagon+SSEstar)
R2.glucagon
\end{lstlisting}

\begin{verbatim}
         [,1]
[1,] 0.081842
\end{verbatim}


and the corresponding partial correlation is:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
sign(coef(e.lmm)["glucagonAUC"])*sqrt(R2.glucagon)
\end{lstlisting}

\begin{verbatim}
         [,1]
[1,] -0.28608
\end{verbatim}


which matches the output of \texttt{partialCor}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
summary(partialCor(e.lmm, R2 = TRUE))
\end{lstlisting}

\begin{verbatim}

		Partial correlation 

               estimate    se df  lower  upper p.value
   visit2        -0.151 0.113 73 -0.377  0.074 0.18450
   visit3        -0.013 0.117 73 -0.246   0.22 0.91230
   visit4        -0.381 0.092 73 -0.565 -0.197 < 1e-04
   glucagonAUC   -0.286 0.103 73 -0.491 -0.081 0.00695
   --------------------------------------------------- 
  Columns lower and upper contain 95% pointwise confidence intervals for each coefficient.
  Degrees of freedom were computed using a Satterthwaite approximation (column df). 

		Coefficient of determination (R2)

               estimate    se df  lower upper  p.value
   visit          0.196 0.075 73  0.047 0.345 0.010548
   glucagonAUC    0.082 0.059 73 -0.036 0.199 0.169016
   global          0.29 0.075 73   0.14  0.44 0.000257
   --------------------------------------------------- 
  Columns lower and upper contain 95% pointwise confidence intervals for each coefficient.
  Degrees of freedom were computed using a Satterthwaite approximation (column df).
\end{verbatim}

\clearpage

\section{Equivalence with other R packages}
\label{sec:org9f6e752}

\subsection{nlme package}
\label{sec:orgf646217}

The model class obtained with the \texttt{lmm} function overlaps the model
class of the \texttt{lme} and \texttt{gls} functions from the nlme package.
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
library(nlme)
\end{lstlisting}

For instance, the compound symmetry is equivalent to \texttt{corCompSymm}
correlation structure, or to a random intercept model (when the within
subject correlation is positive):
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eRI.lmm <- lmm(weight ~ visit*group, structure = "RE",
               data = gastricbypassL, repetition = ~visit|id)
eCS.gls <- gls(weight ~ visit*group, correlation = corCompSymm(form=~visit|id),
               data = gastricbypassL, na.action = na.omit)
eCS.lme <- lme(weight ~ visit*group, random = ~1|id,
               data = gastricbypassL, na.action = na.omit)
logLik(eRI.lmm)
logLik(eCS.lme)
logLik(eCS.gls)
\end{lstlisting}

\begin{verbatim}
[1] -236.21
'log Lik.' -236.21 (df=10)
'log Lik.' -236.21 (df=10)
\end{verbatim}


The estimated random effect also match:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
range(ranef(eRI.lmm)-ranef(eCS.lme))
\end{lstlisting}

\begin{verbatim}
[1] -1.7303e-08  2.6979e-08
\end{verbatim}


Unstructured residual covariance matrix can also be obtained with
\texttt{gls}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eUN.gls <- gls(glucagonAUC ~ visit*group,
               correlation = corSymm(form=~as.numeric(visit)|id),
               weights = varIdent(form=~1|visit),
               data = gastricbypassL, na.action = na.omit)
logLik(eUN.gls)
logLik(eUN.lmm)
\end{lstlisting}

\begin{verbatim}
'log Lik.' -295.31 (df=18)
[1] -295.31
\end{verbatim}


\clearpage

\subsection{lme4 package}
\label{sec:org818c0f2}

The model class obtained with the \texttt{lmm} function overlaps the model
class of the \texttt{lmer} function from the lme4 package.
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
library(lme4)
library(lmerTest)
\end{lstlisting}

For instance, the compound symmetry is equivalent to a random
intercept model (when the within subject correlation is positive):
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eRI.lmer <- lmer(weight ~ visit*group + (1|id),
                 data = gastricbypassL)
logLik(eRI.lmer)
logLik(eRI.lmm)
\end{lstlisting}

\begin{verbatim}
'log Lik.' -236.21 (df=10)
[1] -236.21
\end{verbatim}


The estimated random effects match:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
range(ranef(eRI.lmm)-ranef(eRI.lmer)$id)
\end{lstlisting}

\begin{verbatim}
[1] -1.5513e-08  2.4171e-08
\end{verbatim}


Nested random effects correspond to block unstructured:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eNRI.lmm <- lmm(weight ~ visit*group, structure = RE(~(1|id/baseline)),
               data = gastricbypassL, repetition = ~visit|id)
eNRI.lmer <- lmer(weight ~ visit*group + (1|id/baseline),
                  data = gastricbypassL)
logLik(eNRI.lmer)
logLik(eNRI.lmm)
\end{lstlisting}

\begin{verbatim}
'log Lik.' -234.97 (df=11)
[1] -234.97
\end{verbatim}


And the estimated random effects still match:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eRanefNRI.lmm <- ranef(eNRI.lmm, format = "wide")
eRanefNRI.lmer <- ranef(eNRI.lmer)
## id
range(eRanefNRI.lmm$estimate-eRanefNRI.lmer$id)
## baseline
range(c(eRanefNRI.lmm$estimate.FALSE,eRanefNRI.lmm$estimate.TRUE)-ranef(eNRI.lmer)$`baseline:id`)
\end{lstlisting}

\begin{verbatim}
[1] -5.8317e-06  9.0913e-06
[1] -8.5850e-05  7.8971e-05
\end{verbatim}


\clearpage

An unstructure residual covariance matrix can also be obtained using
random slopes:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eUN.lmer <- lmer(glucagonAUC ~ visit*group + (0 + visit|id),
                 data = gastricbypassL,
                 control = lmerControl(check.nobs.vs.nRE = "ignore"))
logLik(eUN.lmer)
logLik(eUN.lmm)
\end{lstlisting}

\begin{verbatim}
Warning message:
In checkConv(attr(opt, "derivs"), opt$par, ctrl = control$checkConv,  :
  Model failed to converge with max|grad| = 0.00203036 (tol = 0.002, component 1)
'log Lik.' -295.31 (df=19)
[1] -295.31
\end{verbatim}


The uncertainty is quantified in a slightly different way, e.g.:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
anova(eUN.lmm)
\end{lstlisting}

\begin{verbatim}
	     Multivariate Wald test 

                  F-statistic       df p.value   
mean: visit             5.803 (3,16.9) 0.00647 **
    : group             3.926 (1,18.0) 0.06302  .
    : visit:group       2.762 (3,17.3) 0.07332  .
\end{verbatim}


is very similar but not identical to:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
## only the last line is comparable
anova(eUN.lmer)
\end{lstlisting}

\begin{verbatim}
Type III Analysis of Variance Table with Satterthwaite's method
            Sum Sq Mean Sq NumDF DenDF F value  Pr(>F)    
visit         1339     446     3  17.4   18.29 1.3e-05 ***
group            5       5     1  18.1    0.22   0.647    
visit:group    203      68     3  17.4    2.77   0.073 .  
---
Signif. codes:  0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
\end{verbatim}


It is also possible to fit cross-random effects such as:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
data("Penicillin")
eCRI.lmer <- lmer(diameter ~ 1 + (1|plate) + (1|sample), Penicillin)
logLik(eCRI.lmer)
\end{lstlisting}

\begin{verbatim}
'log Lik.' -165.43 (df=4)
\end{verbatim}



using \texttt{lmm}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
Penicillin$index <- paste(Penicillin$sample,Penicillin$plate,sep=".")
Penicillin$id <- 1

eCRI.lmm <- lmm(diameter ~ 1 + (1|plate) + (1|sample), data = Penicillin)
logLik(eCRI.lmm)
\end{lstlisting}

\begin{verbatim}
[1] -165.43
\end{verbatim}


Despite being significantly slower, the loglikelihood and random
effect still match:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
range(ranef(eCRI.lmm)$estimate-rbind(ranef(eCRI.lmer)$plate,ranef(eCRI.lmer)$sample))
\end{lstlisting}

\begin{verbatim}
[1] -4.3812e-07  6.0172e-07
\end{verbatim}

\subsection{mmrm package}
\label{sec:orga77de21}

The package \texttt{mmrm} is an alternative implementation of mixed models
specified via covariance structures:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
library(mmrm)
e.mmrm <- mmrm(
  formula = FEV1 ~ RACE + SEX + ARMCD * AVISIT + us(AVISIT | USUBJID),
  data = fev_data
)
\end{lstlisting}

It leads nearly identical results compared to \texttt{lmm}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
e.lmm <- lmm(
  formula = FEV1 ~ RACE + SEX + ARMCD * AVISIT,
  repetition = ~ AVISIT | USUBJID, structure = "UN",
  data = fev_data, type.information = "expected"
)
\end{lstlisting}
\begin{verbatim}
Warning message:
In .lmmNormalizeData(as.data.frame(data)[unique(stats::na.omit(var.all))],  :
    3 clusters have been removed.
\end{verbatim}


\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
logLik(e.mmrm) - logLik(e.lmm)
range(coef(e.mmrm) - coef(e.lmm))
range(vcov(e.mmrm) - vcov(e.lmm))
\end{lstlisting}

\begin{verbatim}
[1] -2.5413e-06
[1] -0.00018301  0.00016268
[1] -0.00039710  0.00020479
\end{verbatim}


The main differences are:
\begin{itemize}
\item \texttt{mmrm} uses the expected information matrix to quantify uncertainty
instead of the observed information matrix.
\item \texttt{mmrm} implements the Kenward and Roger method for computing the degrees of
freedom and not only the Satterthwaite approximation
\item \texttt{mmrm} implements different covariance patterns
\item \texttt{mmrm} is faster and probably more memorry efficient
\item \texttt{mmrm} has currently fewer post-processing methods (e.g. adjustment
multiple comparisons when testing several model parameters). This
being said, the latest version of the package (0.3.7) included
several additional extractor of model feature so this may be
improved in the future.
\end{itemize}

\subsection{emmeans package}
\label{sec:org3063712}

To illustrate a key difference between the emmeans package and the
\texttt{effects.lmm} function we consider an informative and unbalanced group
variable:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
gastricbypassLB$group2 <- gastricbypassLB$weight1>150
\end{lstlisting}

Since \texttt{lmm}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eCS.lmm_2 <- lmm(glucagonAUC ~ visit*group2, repetition =~visit|id, structure = "CS", data = gastricbypassLB)
logLik(eCS.lmm_2)
\end{lstlisting}

\begin{verbatim}
[1] -315.2
\end{verbatim}


we will use the equivalent with the random effect specification:

\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eRI.lmer_2 <- lmer(glucagonAUC ~ visit*group2 + (1|id), data = gastricbypassLB)
logLik(eRI.lmer_2)
\end{lstlisting}

\begin{verbatim}
'log Lik.' -315.2 (df=10)
\end{verbatim}


While the two models are equivalent, the average outcome output by
\texttt{effects}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
effects(eCS.lmm_2, variable = NULL)
\end{lstlisting}

\begin{verbatim}
	     Average counterfactual outcome

      estimate    se   df  lower  upper
(t=1)   32.317 4.426 64.3 23.476 41.158
(t=2)   29.653 4.535 65.2 20.598 38.709
(t=3)   77.308 4.535 65.1  68.25 86.366
(t=4)    51.95 4.426 64.3 43.109 60.791
\end{verbatim}


substantially differ from the one of emmeans:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
library(emmeans)
emmeans(eRI.lmer_2, specs=~visit)
\end{lstlisting}

\begin{verbatim}
NOTE: Results may be misleading due to involvement in interactions
 visit emmean   SE   df lower.CL upper.CL
 1       33.6 5.53 64.2     22.6     44.7
 2       32.0 5.57 64.4     20.9     43.2
 3       70.0 5.57 64.4     58.9     81.1
 4       47.2 5.53 64.2     36.1     58.2

Results are averaged over the levels of: group2 
Degrees-of-freedom method: kenward-roger 
Confidence level used: 0.95
\end{verbatim}

This is because when averaging over the level of a covariate, emmeans
considers \emph{balanced groups}. In the example, the groups are not
balanced:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
table(gastricbypassLB$group2)/NROW(gastricbypassLB)
\end{lstlisting}

\begin{verbatim}

FALSE  TRUE 
  0.8   0.2
\end{verbatim}


Based on the group and timepoint specific means:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eCS.elmm_2 <- model.tables(effects(eCS.lmm_2, variable = "group2"))
eCS.elmm_2
\end{lstlisting}

\begin{verbatim}
  group2 visit estimate     se     df  lower  upper    p.value
1  FALSE     1   31.430 4.9484 64.349 21.545 41.314 2.4688e-08
2  FALSE     2   28.067 5.0996 65.383 17.884 38.251 6.6737e-07
3  FALSE     3   82.173 5.1008 65.211 71.986 92.359 0.0000e+00
4  FALSE     4   55.126 4.9484 64.349 45.241 65.010 0.0000e+00
5   TRUE     1   35.864 9.8967 64.349 16.095 55.633 5.7374e-04
6   TRUE     2   35.997 9.8967 64.349 16.228 55.766 5.4953e-04
7   TRUE     3   57.848 9.8967 64.349 38.079 77.617 1.8339e-07
8   TRUE     4   39.246 9.8967 64.349 19.477 59.015 1.8651e-04
\end{verbatim}


We illustrate the difference:
\begin{itemize}
\item emmeans:
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
0.5*eCS.elmm_2[eCS.elmm_2$group2==FALSE,"estimate"]+0.5*eCS.elmm_2[eCS.elmm_2$group2==TRUE,"estimate"]
\end{lstlisting}

\begin{verbatim}
[1] 33.647 32.032 70.010 47.186
\end{verbatim}


\begin{itemize}
\item effects:
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
0.8*eCS.elmm_2[eCS.elmm_2$group2==FALSE,"estimate"]+0.2*eCS.elmm_2[eCS.elmm_2$group2==TRUE,"estimate"]
\end{lstlisting}

\begin{verbatim}
[1] 32.317 29.653 77.308 51.950
\end{verbatim}


The "emmeans" approach gives equal "weight" to the expected value of
both group:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
mu.group1 <-  as.double(coef(e.group)["(Intercept)"])
mu.group2 <-  as.double(coef(e.group)["(Intercept)"] + coef(e.group)["group2TRUE"])
p.group1 <- 14/20          ; p.group2 <- 6/20
c(emmeans = (mu.group1+mu.group2)/2, predict = mu.group1 * p.group1 + mu.group2 * p.group2)
\end{lstlisting}

\begin{verbatim}
 emmeans  predict 
4.450435 4.514352
\end{verbatim}


\clearpage

\subsection{effectsize package (\(R^2\) or \(\eta^2\))}
\label{sec:org682f7fe}

Partial \(\eta^2\) can be computed based on \texttt{lmer} using the effectsize package:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
library(effectsize)
eta_squared(eCS.lmer)
cat("\n")
\end{lstlisting}

\begin{verbatim}
# Effect Size for ANOVA (Type III)

Parameter   | Eta2 (partial) |       95% CI
-------------------------------------------
visit       |           0.64 | [0.50, 1.00]
group       |           0.01 | [0.00, 1.00]
visit:group |           0.19 | [0.03, 1.00]

- One-sided CIs: upper bound fixed at
\end{verbatim}


and are approximately equal to what one can compute "manually":
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eCS.Wald <- anova(eCS.lmm)$multivariate
eCS.Wald$df.num*eCS.Wald$statistic/(eCS.Wald$df.num*eCS.Wald$statistic+eCS.Wald$df.denom)
\end{lstlisting}

\begin{verbatim}
[1] 0.335374 0.033811 0.186290
\end{verbatim}


The will not be true for heteroschedastic models:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eUN.Wald <- anova(eUN.lmm)$multivariate
eUN.Wald$df.num*eUN.Wald$statistic/(eUN.Wald$df.num*eUN.Wald$statistic+eUN.Wald$df.denom)
\end{lstlisting}

\begin{verbatim}
[1] 0.50787 0.17905 0.32380
\end{verbatim}


compared to:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eta_squared(eUN.lmer)
cat("\n")
\end{lstlisting}

\begin{verbatim}
# Effect Size for ANOVA (Type III)

Parameter   | Eta2 (partial) |       95% CI
-------------------------------------------
visit       |           0.76 | [0.54, 1.00]
group       |           0.01 | [0.00, 1.00]
visit:group |           0.32 | [0.00, 1.00]

- One-sided CIs: upper bound fixed at
\end{verbatim}


But in that case both may be misleading as the proportion of explained
variance is not clearly defined.

\subsection{MuMIn package (\(R^2\))}
\label{sec:org69c173e}

\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
library(MuMIn)
r.squaredGLMM(eCS.lmer)
cat("\n")
\end{lstlisting}

\begin{verbatim}
         R2m     R2c
[1,] 0.51728 0.62222
\end{verbatim}


To reproduce these R2, we extract from the random intercept model:
\begin{itemize}
\item the residual variance
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
sigmaW <- sigma(eCS.lmm)[1,1]-sigma(eCS.lmm)[1,2]
\end{lstlisting}

\begin{itemize}
\item the variance of the random effect
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
sigmaB <- sigma(eCS.lmm)[1,2]
\end{lstlisting}

\begin{itemize}
\item the variance of the fitted values:
\end{itemize}
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
sigma2_XB <- var(fitted(eCS.lmm))
\end{lstlisting}

and evalutae the ratios:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
c(R2m = sigma2_XB/(sigmaW + sigmaB + sigma2_XB),
  R2c = (sigma2_XB + sigmaB)/(sigmaW + sigmaB + sigma2_XB))
\end{lstlisting}

\begin{verbatim}
    R2m     R2c 
0.52549 0.62865
\end{verbatim}

\subsection{stats package (partial residuals)}
\label{sec:org54e828b}

The function \texttt{residuals.lm} can be used to extract partial residuals
from \texttt{lm} objects. For instance:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
gastricbypassW$group <- as.factor(as.numeric(gastricbypassW$id)%%2)
eIID.lm <- lm(weight4 ~ group + weight1, data = gastricbypassW)
pRes.lm <- residuals(eIID.lm, type = "partial")
head(pRes.lm)
\end{lstlisting}

\begin{verbatim}
      group  weight1
1   7.19282   3.6648
2  -0.20504  31.7052
3   0.60631 -17.3352
4   6.44389  22.7052
5  -1.59403 -16.7352
6 -18.23382   8.4052
\end{verbatim}


Those generally differ (by a constant) from the one provided by
\texttt{residuals.lmm}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
eIID.lmm <- lmm(weight4 ~ group + weight1, data = gastricbypassW)
(residuals(eIID.lmm, type = "partial", variable = "group") - pRes.lm[,"group"])
(residuals(eIID.lmm, type = "partial", variable = "weight1") - pRes.lm[,"weight1"])
\end{lstlisting}

\begin{verbatim}
     1      2      3      4      5      6      7      8      9     10     11     12     13     14 
2.0702 2.0702 2.0702 2.0702 2.0702 2.0702 2.0702 2.0702 2.0702 2.0702 2.0702 2.0702 2.0702 2.0702 
    15     16     17     18     19     20 
2.0702 2.0702 2.0702 2.0702 2.0702 2.0702
     1      2      3      4      5      6      7      8      9     10     11     12     13     14 
106.22 106.22 106.22 106.22 106.22 106.22 106.22 106.22 106.22 106.22 106.22 106.22 106.22 106.22 
    15     16     17     18     19     20 
106.22 106.22 106.22 106.22 106.22 106.22
\end{verbatim}


Indeed, \texttt{residuals.lm} centers the design matrix of the variable
relative to which the partial residuals are computed:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
coef(eIID.lm)["group1"] * mean(gastricbypassW$group=="1")
coef(eIID.lm)["weight1"] * mean(gastricbypassW$weight1)
\end{lstlisting}

\begin{verbatim}
group1 
2.0702
weight1 
 106.22
\end{verbatim}


For continuous variable with a linear effect, these residuals can be
obtained by setting the \texttt{type} argument to \texttt{"partial-center"}:
\lstset{language=r,label= ,caption= ,captionpos=b,numbers=none}
\begin{lstlisting}
(residuals(eIID.lmm, type = "partial-center", variable = "weight1") - pRes.lm[,"weight1"])
\end{lstlisting}

\begin{verbatim}
          1           2           3           4           5           6           7           8 
 1.7675e-13  6.7502e-14 -6.3949e-14  5.6843e-14 -3.9080e-14  8.1712e-14 -3.7303e-14  5.9508e-14 
          9          10          11          12          13          14          15          16 
-4.2633e-14  4.4409e-14 -2.9310e-14  5.5123e-14 -4.6185e-14  4.4409e-14 -4.2633e-14  4.6185e-14 
         17          18          19          20 
-3.9968e-14  5.3291e-14 -1.4211e-14  3.5527e-14
\end{verbatim}


\Warning When evaluating the partial residuals relative to categorical
variables, interactions, or non-linear terms, the output obtained with
\texttt{partial-center} will not match the one of \texttt{residuals.lm}. Indeed
\texttt{partial-center} will, when numeric, center the original variable
whereas \texttt{residuals.lm} will center the column relative to the
coefficient in the design matrix.
\end{document}