Difference between revisions of "The Linear Mixed Models Toolbox"

From Linear Mixed Models Toolbox
Jump to navigation Jump to search
 
(99 intermediate revisions by 2 users not shown)
Line 2: Line 2:


The <b>L</b>inear mixed <b>M</b>odels <b>T</b>oolbox ({{lmt}}) is a stand-alone single executable software for for large scale linear mixed model analysis.
The <b>L</b>inear mixed <b>M</b>odels <b>T</b>oolbox ({{lmt}}) is a stand-alone single executable software for for large scale linear mixed model analysis.
It is the successor of DMU, the well-known and
widely used software package for linear mixed model analysis developed and maintained
by Per Madsen and Just Jensen.


Since the early days of software development in statistics and quantitative genetics
{{lmt}} supports all models commonly used in genetic evaluation and has various options to handle genomic markers.
time has moved on in terms of what programming languages are capable of and therefore
DMU has been given a thorough overhaul.


One result of the overhaul is the new name, {{lmt}}, resulting from the difficulty to translate
{{lmt}} has been used successfully for genetic evaluation data sets with >>200k genotyped animals, >>15m animals, >>500m equations.
the acronym DMU into something which is generally meaningful throughout time. For
those who prefer the acronym DMU, they may refer to {{lmt}} as <b>DMU-next</b>.


The second area of the overhaul is the parameter file interface. {{lmt}} now comes with
{{lmt}} is only available for 64 bit Linux operation systems, is run from the Linux command line, and uses an [https://www.w3schools.com/xml/ xml] style parameter file which is supposed to allow for an easy understanding by the user. Further using [https://www.w3schools.com/xml/ xml] comes with support for automated commenting, uncommenting, indentation, code-folding and syntax highlighting by almost every editor,
an xml style parameter file which is supposed to allow for a much easier understanding
thus easing to follow the structure of the parameter file even if it spans several tens of lines of code.
by the user. Further using xml comes with support for automated commenting, un-
commenting, indentation, code-folding and syntax highlighting by almost every editor,
thus easing to follow the structure of the parameter file even if it spans several tens of
lines of code.


The third area of the overhaul is the program structure. DMU was structured into
== Conditions of use ==
several programs (<i>DMU1, DMU4, DMU5, DMUAI, RJMC</i>). In contrast, {{lmt}} is meant
{{lmt}} can be used by the scientific community free of charge, but users must credit {{lmt}}
to provide the functionalities all those programs via a single parameter file and a single
in any publications.
executable.
Commercial users must obtain the explicit approval of the author before using {{lmt}} and must credit {{lmt}} in any publication in scientific journals.
 
If {{lmt}} cannot be credited via citation the author must become a co-author.
While {{lmt}} is finally meant to be a full scale successor of DMU, it does not yet provide
all its functionalities in some areas, in others it already provides more. More specifi-
cally, there no REML facilities available yet, but large scale linear mixed model solving
provides Single-Step-T-BLUP facilities, uploading of genotypes and building of genomic
relationship matrices on the fly etc etc.
 
==Supported features ==
 
=== Supported operations ===
 
Currently {{lmt}} support the following operations on linear mixed models:
 
*Solving for BLUP and BLUE solutions conditional on supplied variances for random and fixed factor, respectively;
*Gibbs sampling of variance components in single pass and blocked mode;
*MC-EM-REML estimation of variance components
*Sampling elements of the inverse of the mixed model coefficient matrix
 
=== Supported factors and variables ===
{{lmt}} supports
*fixed
*random factors
*classification variables
*continuous co-variables, which can be nested. For continuous co-variables {{lmt}} support user-defined polynomials and hard coded [https://en.wikipedia.org/wiki/Legendre_polynomials Legendre polynomials] up to order 6.
*genetic group co-variables
 
All classification and co-variables can be associated to a fixed or random factor.
 
=== Supported variance structures ===
For random factor {{lmt}} supports variance structures of
*structure [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Sigma$$ is an dense symmetric positive definite matrix, and
*$$\Theta_L(\Gamma\otimes I_{\Sigma})\Theta_L^{'}$$, where $$\Theta$$ is symmetric positive definite [https://en.wikipedia.org/wiki/Block_matrix#Block_diagonal_matrices block-diagonal matrix] of $$n$$ symmetric positive definite martices $$\Sigma_i, i=1,..,n$$, $$\Theta_L$$ is the lower [https://en.wikipedia.org/wiki/Cholesky_decomposition Cholesky factor] of $$\Theta$$ and $$I_{\Sigma}$$ is an identity matrix of dimension $$\Sigma_i$$.
 
When solving linear mixed models $$\Sigma$$ and $$\Gamma$$ are user determined constants, whereas when estimating variances $$\Gamma$$ is a user determined constant and $$\Sigma$$ is a function of the data.
 
Supported type for $$\Gamma$$ are
*an [https://en.wikipedia.org/wiki/Identity_matrix identity matrix]
*an arbitrary positive definite [https://en.wikipedia.org/wiki/Diagonal_matrix diagonal matrix]
*a pedigree-based numerator relationship matrix $$A$$ which may contain meta-founders
*a pedigree- and genotype-based relationship matrix $$H$$ which may contain meta-founders
*a user-defined(u.d.) symmetric, positive definite matrix of which inverse is supplied
**as a sparse upper-triangular matrix stored in [https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_row_(CSR,_CRS_or_Yale_format) csr format]
**as a dense matrix
*a co-variance matrix of a selected auto-regressive process
 
=== Supported linear mixed model solvers ===
{{lmt}} supports
 
*a direct solver requiring to explicitly build the linear mixed model equations left-hand-side coefficient matrix($$C$$)
*an iteration-on-data pre-conditioned gradient solver which '''does not''' require $$C$$
 
=== Supported features related to genomic data ===
*direct use of genomic marker data
*building of genomic relationship matrices($$G$$) from supplied genomic data
*uploading of a u.d. $$G$$
*adjustment of $$G$$ to $$A_{gg}$$
*solving Single-Step-G-BLUP models
*sampling variances for Single-Step-G-BLUP models
*solving Single-Step-T-BLUP models
*solving Single-Step-SNP-BLUP models
*all Single-Step models can be run from "bottom-up", that is the user supplies the genotypes and all necessary ingredients(e.g. $$G$$) are built on the fly.


=== Supported pedigree types===
== How to get it ==
*ordinary pedigrees
*probabilistic pedigrees with an unlimited number of parent pairs per individual
*genetic group pedigrees
*meta-founders


== Linear mixed model terminology ==
{{lmt}} can be obtained '''on request''' from the [mailto:vinzent.boerner@qgg.au.dk author].
 
The general linear mixed model supported by {{lmt}} may be written as
 
$$
\left(
\begin{array}{c}
y_1 \\
y_i \\
y_n
\end{array}
\right)
=
\left(
\begin{array}{ccc}
X_1 & 0 & 0 \\
0 & X_i & 0 \\
. & . & X_n
\end{array}
\right)
\left(
\begin{array}{c}
b_1 \\
b_i \\
b_n
\end{array}
\right)
+
\left(
\begin{array}{ccc}
Z_1 & 0 & 0\\
0 & Z_i & 0\\
0 & 0 & Z_n
\end{array}
\right)
\left(
\begin{array}{c}
u_1 \\
u_i \\
u_n
\end{array}
\right)
+
\left(
\begin{array}{ccc}
W_1 & 0 & 0\\
0 & W_i & 0\\
0 & 0 & W_n
\end{array}
\right)
\left(
\begin{array}{c}
a_1 \\
a_i \\
a_n
\end{array}
\right)
+
\left(
\begin{array}{ccc}
I_1 & 0 & 0\\
0 & I_i & 0\\
0 & 0 & I_n
\end{array}
\right)
\left(
\begin{array}{c}
e_1 \\
e_i \\
e_n
\end{array}
\right)
$$
 
== Disclaimer ==
{{lmt}} is under ongoing development and many of its features have been tested only a few
times on a limited number of models and data sets. Thus, the users uses {{lmt}} completely
on his/her own risk. This also applies to any decisions made based on the results provided
by {{lmt}}.
 
== Conditions of use ==
{{lmt}} can be used by the scientific community free of charge, but users must credit {{lmt}}
in any publications. Commercial users must obtain the explicit approval of the author
before using {{lmt}} and must credit {{lmt}} in any publication in scientific journals.


== Feedback and support ==
== Feedback and support ==
Line 183: Line 25:
However, the author appreciates feedback about the program functionality, possible aborts (segmentation faults), usability of output and comprehensiveness of the manual.
However, the author appreciates feedback about the program functionality, possible aborts (segmentation faults), usability of output and comprehensiveness of the manual.


For feedback, wish list, questions and support contact [mailto:vinzent.boerner@qgg.au.dk vinzent.boerner@qgg.au.dk](infrequently checked) or [mailto:vinzent.boerner@gmx.de vinzent.boerner@gmx.de](frequently checked).


 
== [[supported features| Supported features]] ==
* [http://localhost/mediawiki/index.php/Run_It Run It]
== [[Algorithms|Algorithms]] ==
* [http://localhost/mediawiki/index.php/Inputfileformats Input file formats]
== [[Parameterfile1| Parameter file terminology]] ==
* [http://localhost/mediawiki/index.php/Parameterfile1 Parameter file terminology part 1]
== [[linear mixed models in lmt| Linear mixed models in lmt]] ==
* [http://localhost/mediawiki/index.php/Jump_Start Jump Start]
== [[Genomic data in lmt| Genomic data lmt]] ==
== [[File formats|File formats]] ==
== [[Input files|Input files]] ==
== [[Output files|Output files]] ==
== [[Run_It|How to run it]] ==
== [[Examples|Examples]] ==
== [[Parameter file elements| Parameter file elements]] ==

Latest revision as of 00:58, 12 May 2022

Introduction

The Linear mixed Models Toolbox (lmt) is a stand-alone single executable software for for large scale linear mixed model analysis.

lmt supports all models commonly used in genetic evaluation and has various options to handle genomic markers.

lmt has been used successfully for genetic evaluation data sets with >>200k genotyped animals, >>15m animals, >>500m equations.

lmt is only available for 64 bit Linux operation systems, is run from the Linux command line, and uses an xml style parameter file which is supposed to allow for an easy understanding by the user. Further using xml comes with support for automated commenting, uncommenting, indentation, code-folding and syntax highlighting by almost every editor, thus easing to follow the structure of the parameter file even if it spans several tens of lines of code.

Conditions of use

lmt can be used by the scientific community free of charge, but users must credit lmt in any publications. Commercial users must obtain the explicit approval of the author before using lmt and must credit lmt in any publication in scientific journals. If lmt cannot be credited via citation the author must become a co-author.

How to get it

lmt can be obtained on request from the author.

Feedback and support

lmt comes without any guaranteed support and the user is strongly advised to study the manual thoroughly. However, the author appreciates feedback about the program functionality, possible aborts (segmentation faults), usability of output and comprehensiveness of the manual.

For feedback, wish list, questions and support contact vinzent.boerner@qgg.au.dk(infrequently checked) or vinzent.boerner@gmx.de(frequently checked).

Supported features

Algorithms

Parameter file terminology

Linear mixed models in lmt

Genomic data lmt

File formats

Input files

Output files

How to run it

Examples

Parameter file elements