Linear Mixed Models Toolbox - User contributions [en]

Algorithms

2022-11-04T00:35:30Z

127.0.0.1: /* Solving */

==Solving Linear Mixed model Equations==
{{lmt}} supports two types of solver for solving MME's: a direct solver and an iterative solver
===Iterative solver===
The iterative solver uses the [https://en.wikipedia.org/wiki/Conjugate_gradient_method#The_preconditioned_conjugate_gradient_method preconditioned conjugate gradient method] and is {{lmt}}'s default solver. It does not require the explicit construction of any mixed model equation, and is therefore less resource demanding than the direct solver. That is, many models which cannot be solved using the direct solver can still be solved using the iterative solver. Even for small models the iterative solver usually outperforms the direct solver in terms of total processing time.

Whether the iterative solver has converged in round $$i$$ can be evaluated with convergence criterions $$log_e\left(\sqrt{\frac{||(Cx_i-b)||}{||b||}}\right)<t$$ or $$log_e\left(\sqrt{\frac{||(x_{i}-x_{i-1})||'}{||x_{i-1}||}}\right)<t$$, where $$C$$ is the mixed-model coefficient matrix, $$x_i$$ is the solution vector in round $$i$$, $$b$$ is the right-hand side and $$t$$ is the convergence threshold which defaults to -18.42, which is $$log_e(10^{-9})$$.

===Direct solver===
The direct solver requires the mixed model coefficient matrix to be build and all Kronecker products to be resolved. This can be quite memory demanding and should therefore be used carefully. The direct solver uses a [https://en.wikipedia.org/wiki/Cholesky_decomposition Cholesky decomposition] and [https://en.wikipedia.org/wiki/Triangular_matrix#Forward_and_back_substitution forward-backward-substitution] to solve the mixed model equation system, where especially the decomposition step can be very resource demanding and time consuming.

==Variance component estimation==
For random factors {{lmt}} supports variance of structure [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Sigma$$ is an dense symmetric positive definite matrix to be estimated. For residuals {{lmt}} supports variance structures $$I\otimes\Sigma$$ and $$\Theta_L(I_{n_{observations}})\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_{n_{observations}}$$ is an identity matrix of dimensions equal to the total number of observations across all traits. Note that the number of records associated to a particular $$\Sigma_i$$ should be sufficient to facilitate its estimation.

===Gibbs sampling===
====Single pass Gibbs sampling====
{{lmt}}'s single pass Gibbs sampling algorithm is described in <ref name="Sorensen2002" />. In short, all location parameters are drawn from their joint conditional posterior distribution. Note that this requires solving the mixed model equation system once per iteration which usually leads to a substantial increase in processing time. Note that ssSNBPLUP models are not supported.

====Blocked Gibbs sampling====
For random factors {{lmt}}'s blocked Gibbs sampler draws correlated location parameters within factor level from their joint conditional posterior distribution. Location parameters of fixed factors are drawn in scalar mode from their fully conditional posterior. Note that ssGTBLUP and ssSNPBLUP models are not supported.
===Restricted Maximum Likelyhood===
====MC-EM-REML====
{{lmt}} provides a monte-carlo expectation-maximisation REML algorithms which uses the preconditioned gradient solver for solving the mixed model equations and a blocked Gibbs sampler to sample the necessary traces<ref name="Harville2004" />. Note that ssSNPBLUP and ssGTBLUP models are not supported.

The MC-EM-REML convergence criterion is $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.

====Average information (AI)-REML====
{{lmt}} provides the calculation of variance components using average information REML <ref name="Johnson1995" />, <ref name="Gilmour1995" /> and <ref name="Jensen1997" />.
REML estimates of co-variance matrices can be derived using the phenotypic co-variance matrix $$V$$ or the mixed-model equations system coefficient matrix C.

{{lmt}} provides three different AI-REML convergence criterions:

* the relative change of the log-likelihood calculated as $$log_e\left(\sqrt{\frac{||(l_{i}-l_{i-1})||}{||l_{i-1}||}}\right)$$ where $$l$$ is the log-likelihood and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{||g_{i}||}\right)$$ where $$g$$ is the gradient vector and $$i$$ is the iteration counter.

=====AI-REML Iteration mechanism=====

For finding the next parameter vector {{lmt}} use a mixture of the [https://en.wikipedia.org/wiki/Levenberg%E2%80%93Marquardt_algorithm Levenberg–Marquardt algorithm] and ordinary step length down scaling, which can be described as $$\zeta_i=\zeta_{i-1}+\alpha(\Omega_i+I\beta)^{-1}\xi_i$$, where $$\zeta_i$$ and $$\zeta_{i-1}$$ are parameter vector is round $$i$$ and $$i-1$$, respectively, $$\alpha$$ is the step length, $$\Omega$$ is the AI matrix, $$\xi$$ is the Jacobian and $$\beta$$ is an arbitrary real number $$\geq$$0.

Once $$\Omega_i$$ and $$\xi_i$$ are derived {{lmt}} will calculate $$\zeta_i$$ using $$\alpha=1$$ and $$\beta=0$$. If $$\zeta_i$$ is not valid(i.e. the $$\Sigma$$ matrices are not positive definite), it will use the Levenberg-Marquardt algorithm to find a valid $$\zeta_i$$ by setting $$\beta$$ to an ever increasing number. {{lmt}} will try this for 10000 iterations. If $$\zeta_i$$ is still not valid {{lmt}} will return to $$\Omega_{i-1}$$ and $$\xi_{i-1}$$ and set $$\alpha=\alpha*0.5$$.

This can lead to a situation where {{lmt}} down-scales $$\alpha$$ to near zero and the convergence criterion appears to report convergence. It is therefore crucial to check the iteration output. True convergence is only achieved if $$\alpha=1$$ and $$\beta=0$$.

=====AI-REML-C=====
{{lmt}} supports AI-REML-C, which relies on the construction and factorization of the mixed-model equations system coefficient matrix C.

Note that ssSNPBLUP and ssGTBLUP models are not supported. Further, it is not advisable to use airemlc for ssGBLUP models with several correlated genetic effects.

===Fixation of Sigma matrix elements===
Elements of $$\Sigma$$ matrices can be exempted from re-estimation in two ways:
#providing a boolean [[Parameter_file_elements#<sigma>|mask matrix]] $$B$$ where elements set to "T" are related to elements in $$\Sigma$$ which should be regarded as fixed, or by
#setting a diagonal element in $$\Sigma$$ desired to be fixed to 1.0 to 1.0, or by
#setting an off-diagonal element in $$\Sigma$$ desired to be fixed to 0.0 to 0.0.

Note that in case exemption is communicated via options 2 and 3 the $$\Sigma$$ matrix provided at start must still be positive definite. Further note that using option 1 overrides all information contained in $$\Sigma$$. That is if $$\Sigma[1,1]$$ is set to 1.0 but $$B$$[1,1] is set to false, $$\Sigma$$[1,1] is not exempt.

==Elements of the inverse of the mixed model coefficient matrix==
In principle {{lmt}} can generate any element of the inverse mixed model coefficient matrix. However, the user interface is currently limited to the diagonal elements for fixed factors and the diagonal blocks for random factors. These elements can either be sampled or obtained accurately via solving.
===Gibbs Sampling===
Following the approach of Harville(1999)<ref name="Harville1999" /> {{lmt}} can sample for fixed factors the diagonal elements of the inverse of the mixed model coefficient matrix, for random factors the diagonal blocks of the inverse of the coefficient matrix where the block size is determined by the dimension of the related $$\Sigma$$ matrix. The blocks are the prediction error co-variance matrices of the factor levels of correlated sub-factors. When sampling prediction error variances {{lmt}} can run many Gibbs chains in parallel allowing to exploit multi-core hardware architecture. However, it is recommended to specify not more chains than the number of available '''real''' cores excluding hyper-threading technology.
===Solving===
{{lmt}} can obtain elements of the inverse of the coefficient matrix via solving the mixed model equations. This method is currently only supported for the diagonal prediction error co-variance blocks of random factors, where the block size is determined by the dimension of the related $$\Sigma$$ matrix. For this algorithm {{lmt}} can utilize either the [[#Iterative solver|iterative solver]] or the [[#Direct solver|direct solver]].

==Iterative inbreeding==
{{lmt}} supports the iterative calculation of inbreeding coefficients as described in VanRaden(1992)<ref name="VanRaden1992" />.

==References==
<references>
<ref name="Sorensen2002">D. Sorensen and D. Gianola; Likelihood, Bayesian, and MCMC Methods in Quantitative Genetics; 2002; 584-588</ref>
<ref name="Harville1999">David A. Harville; Use of the Gibbs sampler to invert large, possibly sparse, positive definite matrices; Linear Algebra and its Applications; 1999</ref>
<ref name="Harville2004">David A. Harville; Making REML computationally feasible for large data sets: use of the Gibbs sampler; Journal of Statistical Computation & Simulation; 2004</ref>
<ref name="Jensen1997">J. Jensen et. al.; Residual maximum likelihood estimation of (co) variance components in multivariate mixed linear models using average information; Indian Society of Agricultural Statistics; 1997</ref>
<ref name="Gilmour1995">A. Gilmour et. al.; Average information REML: an efficient algorithm for variance parameter estimation in linear mixed models; Biometrics; 1995</ref>
<ref name="Johnson1995">D.L. Johnson and R. Thompson; Restricted maximum likelihood estimation of variance components for univariate animal models using sparse matrix techniques and average information; Journal of Dairy Science; 1995</ref>
<ref name="VanRaden1992">PM VanRanden; Accounting for Inbreeding and Crossbreeding in Genetic Evaluation of Large Populations; Journal of Dairy Science; 1992</ref>
</references>

Algorithms

2022-11-04T00:34:41Z

127.0.0.1: /* Average information (AI)-REML */

==Solving Linear Mixed model Equations==
{{lmt}} supports two types of solver for solving MME's: a direct solver and an iterative solver
===Iterative solver===
The iterative solver uses the [https://en.wikipedia.org/wiki/Conjugate_gradient_method#The_preconditioned_conjugate_gradient_method preconditioned conjugate gradient method] and is {{lmt}}'s default solver. It does not require the explicit construction of any mixed model equation, and is therefore less resource demanding than the direct solver. That is, many models which cannot be solved using the direct solver can still be solved using the iterative solver. Even for small models the iterative solver usually outperforms the direct solver in terms of total processing time.

Whether the iterative solver has converged in round $$i$$ can be evaluated with convergence criterions $$log_e\left(\sqrt{\frac{||(Cx_i-b)||}{||b||}}\right)<t$$ or $$log_e\left(\sqrt{\frac{||(x_{i}-x_{i-1})||'}{||x_{i-1}||}}\right)<t$$, where $$C$$ is the mixed-model coefficient matrix, $$x_i$$ is the solution vector in round $$i$$, $$b$$ is the right-hand side and $$t$$ is the convergence threshold which defaults to -18.42, which is $$log_e(10^{-9})$$.

===Direct solver===
The direct solver requires the mixed model coefficient matrix to be build and all Kronecker products to be resolved. This can be quite memory demanding and should therefore be used carefully. The direct solver uses a [https://en.wikipedia.org/wiki/Cholesky_decomposition Cholesky decomposition] and [https://en.wikipedia.org/wiki/Triangular_matrix#Forward_and_back_substitution forward-backward-substitution] to solve the mixed model equation system, where especially the decomposition step can be very resource demanding and time consuming.

==Variance component estimation==
For random factors {{lmt}} supports variance of structure [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Sigma$$ is an dense symmetric positive definite matrix to be estimated. For residuals {{lmt}} supports variance structures $$I\otimes\Sigma$$ and $$\Theta_L(I_{n_{observations}})\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_{n_{observations}}$$ is an identity matrix of dimensions equal to the total number of observations across all traits. Note that the number of records associated to a particular $$\Sigma_i$$ should be sufficient to facilitate its estimation.

===Gibbs sampling===
====Single pass Gibbs sampling====
{{lmt}}'s single pass Gibbs sampling algorithm is described in <ref name="Sorensen2002" />. In short, all location parameters are drawn from their joint conditional posterior distribution. Note that this requires solving the mixed model equation system once per iteration which usually leads to a substantial increase in processing time. Note that ssSNBPLUP models are not supported.

====Blocked Gibbs sampling====
For random factors {{lmt}}'s blocked Gibbs sampler draws correlated location parameters within factor level from their joint conditional posterior distribution. Location parameters of fixed factors are drawn in scalar mode from their fully conditional posterior. Note that ssGTBLUP and ssSNPBLUP models are not supported.
===Restricted Maximum Likelyhood===
====MC-EM-REML====
{{lmt}} provides a monte-carlo expectation-maximisation REML algorithms which uses the preconditioned gradient solver for solving the mixed model equations and a blocked Gibbs sampler to sample the necessary traces<ref name="Harville2004" />. Note that ssSNPBLUP and ssGTBLUP models are not supported.

The MC-EM-REML convergence criterion is $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.

====Average information (AI)-REML====
{{lmt}} provides the calculation of variance components using average information REML <ref name="Johnson1995" />, <ref name="Gilmour1995" /> and <ref name="Jensen1997" />.
REML estimates of co-variance matrices can be derived using the phenotypic co-variance matrix $$V$$ or the mixed-model equations system coefficient matrix C.

{{lmt}} provides three different AI-REML convergence criterions:

* the relative change of the log-likelihood calculated as $$log_e\left(\sqrt{\frac{||(l_{i}-l_{i-1})||}{||l_{i-1}||}}\right)$$ where $$l$$ is the log-likelihood and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{||g_{i}||}\right)$$ where $$g$$ is the gradient vector and $$i$$ is the iteration counter.

=====AI-REML Iteration mechanism=====

For finding the next parameter vector {{lmt}} use a mixture of the [https://en.wikipedia.org/wiki/Levenberg%E2%80%93Marquardt_algorithm Levenberg–Marquardt algorithm] and ordinary step length down scaling, which can be described as $$\zeta_i=\zeta_{i-1}+\alpha(\Omega_i+I\beta)^{-1}\xi_i$$, where $$\zeta_i$$ and $$\zeta_{i-1}$$ are parameter vector is round $$i$$ and $$i-1$$, respectively, $$\alpha$$ is the step length, $$\Omega$$ is the AI matrix, $$\xi$$ is the Jacobian and $$\beta$$ is an arbitrary real number $$\geq$$0.

Once $$\Omega_i$$ and $$\xi_i$$ are derived {{lmt}} will calculate $$\zeta_i$$ using $$\alpha=1$$ and $$\beta=0$$. If $$\zeta_i$$ is not valid(i.e. the $$\Sigma$$ matrices are not positive definite), it will use the Levenberg-Marquardt algorithm to find a valid $$\zeta_i$$ by setting $$\beta$$ to an ever increasing number. {{lmt}} will try this for 10000 iterations. If $$\zeta_i$$ is still not valid {{lmt}} will return to $$\Omega_{i-1}$$ and $$\xi_{i-1}$$ and set $$\alpha=\alpha*0.5$$.

This can lead to a situation where {{lmt}} down-scales $$\alpha$$ to near zero and the convergence criterion appears to report convergence. It is therefore crucial to check the iteration output. True convergence is only achieved if $$\alpha=1$$ and $$\beta=0$$.

=====AI-REML-C=====
{{lmt}} supports AI-REML-C, which relies on the construction and factorization of the mixed-model equations system coefficient matrix C.

Note that ssSNPBLUP and ssGTBLUP models are not supported. Further, it is not advisable to use airemlc for ssGBLUP models with several correlated genetic effects.

===Fixation of Sigma matrix elements===
Elements of $$\Sigma$$ matrices can be exempted from re-estimation in two ways:
#providing a boolean [[Parameter_file_elements#<sigma>|mask matrix]] $$B$$ where elements set to "T" are related to elements in $$\Sigma$$ which should be regarded as fixed, or by
#setting a diagonal element in $$\Sigma$$ desired to be fixed to 1.0 to 1.0, or by
#setting an off-diagonal element in $$\Sigma$$ desired to be fixed to 0.0 to 0.0.

Note that in case exemption is communicated via options 2 and 3 the $$\Sigma$$ matrix provided at start must still be positive definite. Further note that using option 1 overrides all information contained in $$\Sigma$$. That is if $$\Sigma[1,1]$$ is set to 1.0 but $$B$$[1,1] is set to false, $$\Sigma$$[1,1] is not exempt.

==Elements of the inverse of the mixed model coefficient matrix==
In principle {{lmt}} can generate any element of the inverse mixed model coefficient matrix. However, the user interface is currently limited to the diagonal elements for fixed factors and the diagonal blocks for random factors. These elements can either be sampled or obtained accurately via solving.
===Gibbs Sampling===
Following the approach of Harville(1999)<ref name="Harville1999" /> {{lmt}} can sample for fixed factors the diagonal elements of the inverse of the mixed model coefficient matrix, for random factors the diagonal blocks of the inverse of the coefficient matrix where the block size is determined by the dimension of the related $$\Sigma$$ matrix. The blocks are the prediction error co-variance matrices of the factor levels of correlated sub-factors. When sampling prediction error variances {{lmt}} can run many Gibbs chains in parallel allowing to exploit multi-core hardware architecture. However, it is recommended to specify not more chains than the number of available '''real''' cores excluding hyper-threading technology.
===Solving===
{{lmt}} can obtain elements of the inverse of the coefficient matrix via solving the mixed model equations. This method is currently only supported for the diagonal prediction error co-variance blocks of random factors, where the block size is determined by the dimension of the related $$\Sigma$$ matrix. For this algorithm {{lmt}} can utilize either the [[#Iterative solver]] or the [[#Direct solver]].

==Iterative inbreeding==
{{lmt}} supports the iterative calculation of inbreeding coefficients as described in VanRaden(1992)<ref name="VanRaden1992" />.

==References==
<references>
<ref name="Sorensen2002">D. Sorensen and D. Gianola; Likelihood, Bayesian, and MCMC Methods in Quantitative Genetics; 2002; 584-588</ref>
<ref name="Harville1999">David A. Harville; Use of the Gibbs sampler to invert large, possibly sparse, positive definite matrices; Linear Algebra and its Applications; 1999</ref>
<ref name="Harville2004">David A. Harville; Making REML computationally feasible for large data sets: use of the Gibbs sampler; Journal of Statistical Computation & Simulation; 2004</ref>
<ref name="Jensen1997">J. Jensen et. al.; Residual maximum likelihood estimation of (co) variance components in multivariate mixed linear models using average information; Indian Society of Agricultural Statistics; 1997</ref>
<ref name="Gilmour1995">A. Gilmour et. al.; Average information REML: an efficient algorithm for variance parameter estimation in linear mixed models; Biometrics; 1995</ref>
<ref name="Johnson1995">D.L. Johnson and R. Thompson; Restricted maximum likelihood estimation of variance components for univariate animal models using sparse matrix techniques and average information; Journal of Dairy Science; 1995</ref>
<ref name="VanRaden1992">PM VanRanden; Accounting for Inbreeding and Crossbreeding in Genetic Evaluation of Large Populations; Journal of Dairy Science; 1992</ref>
</references>

Algorithms

2022-11-04T00:34:11Z

127.0.0.1: /* REML Iteration mechanism */

==Solving Linear Mixed model Equations==
{{lmt}} supports two types of solver for solving MME's: a direct solver and an iterative solver
===Iterative solver===
The iterative solver uses the [https://en.wikipedia.org/wiki/Conjugate_gradient_method#The_preconditioned_conjugate_gradient_method preconditioned conjugate gradient method] and is {{lmt}}'s default solver. It does not require the explicit construction of any mixed model equation, and is therefore less resource demanding than the direct solver. That is, many models which cannot be solved using the direct solver can still be solved using the iterative solver. Even for small models the iterative solver usually outperforms the direct solver in terms of total processing time.

Whether the iterative solver has converged in round $$i$$ can be evaluated with convergence criterions $$log_e\left(\sqrt{\frac{||(Cx_i-b)||}{||b||}}\right)<t$$ or $$log_e\left(\sqrt{\frac{||(x_{i}-x_{i-1})||'}{||x_{i-1}||}}\right)<t$$, where $$C$$ is the mixed-model coefficient matrix, $$x_i$$ is the solution vector in round $$i$$, $$b$$ is the right-hand side and $$t$$ is the convergence threshold which defaults to -18.42, which is $$log_e(10^{-9})$$.

===Direct solver===
The direct solver requires the mixed model coefficient matrix to be build and all Kronecker products to be resolved. This can be quite memory demanding and should therefore be used carefully. The direct solver uses a [https://en.wikipedia.org/wiki/Cholesky_decomposition Cholesky decomposition] and [https://en.wikipedia.org/wiki/Triangular_matrix#Forward_and_back_substitution forward-backward-substitution] to solve the mixed model equation system, where especially the decomposition step can be very resource demanding and time consuming.

==Variance component estimation==
For random factors {{lmt}} supports variance of structure [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Sigma$$ is an dense symmetric positive definite matrix to be estimated. For residuals {{lmt}} supports variance structures $$I\otimes\Sigma$$ and $$\Theta_L(I_{n_{observations}})\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_{n_{observations}}$$ is an identity matrix of dimensions equal to the total number of observations across all traits. Note that the number of records associated to a particular $$\Sigma_i$$ should be sufficient to facilitate its estimation.

===Gibbs sampling===
====Single pass Gibbs sampling====
{{lmt}}'s single pass Gibbs sampling algorithm is described in <ref name="Sorensen2002" />. In short, all location parameters are drawn from their joint conditional posterior distribution. Note that this requires solving the mixed model equation system once per iteration which usually leads to a substantial increase in processing time. Note that ssSNBPLUP models are not supported.

====Blocked Gibbs sampling====
For random factors {{lmt}}'s blocked Gibbs sampler draws correlated location parameters within factor level from their joint conditional posterior distribution. Location parameters of fixed factors are drawn in scalar mode from their fully conditional posterior. Note that ssGTBLUP and ssSNPBLUP models are not supported.
===Restricted Maximum Likelyhood===
====MC-EM-REML====
{{lmt}} provides a monte-carlo expectation-maximisation REML algorithms which uses the preconditioned gradient solver for solving the mixed model equations and a blocked Gibbs sampler to sample the necessary traces<ref name="Harville2004" />. Note that ssSNPBLUP and ssGTBLUP models are not supported.

The MC-EM-REML convergence criterion is $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.

====Average information (AI)-REML====
{{lmt}} provides the calculation of variance components using average information REML <ref name="Johnson1995" />, <ref name="Gilmour1995" /> and <ref name="Jensen1997" />.
REML estimates of co-variance matrices can be derived using the phenotypic co-variance matrix $$V$$ or the mixed-model equations system coefficient matrix C.

{{lmt}} provides three different AI-REML convergence criterions:

* the relative change of the log-likelihood calculated as $$log_e\left(\sqrt{\frac{||(l_{i}-l_{i-1})||}{||l_{i-1}||}}\right)$$ where $$l$$ is the log-likelihood and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{||g_{i}||}\right)$$ where $$g$$ is the gradient vector and $$i$$ is the iteration counter.

=====REML Iteration mechanism=====

For finding the next parameter vector {{lmt}} use a mixture of the [https://en.wikipedia.org/wiki/Levenberg%E2%80%93Marquardt_algorithm Levenberg–Marquardt algorithm] and ordinary step length down scaling, which can be described as $$\zeta_i=\zeta_{i-1}+\alpha(\Omega_i+I\beta)^{-1}\xi_i$$, where $$\zeta_i$$ and $$\zeta_{i-1}$$ are parameter vector is round $$i$$ and $$i-1$$, respectively, $$\alpha$$ is the step length, $$\Omega$$ is the AI matrix, $$\xi$$ is the Jacobian and $$\beta$$ is an arbitrary real number $$\geq$$0.

Once $$\Omega_i$$ and $$\xi_i$$ are derived {{lmt}} will calculate $$\zeta_i$$ using $$\alpha=1$$ and $$\beta=0$$. If $$\zeta_i$$ is not valid(i.e. the $$\Sigma$$ matrices are not positive definite), it will use the Levenberg-Marquardt algorithm to find a valid $$\zeta_i$$ by setting $$\beta$$ to an ever increasing number. {{lmt}} will try this for 10000 iterations. If $$\zeta_i$$ is still not valid {{lmt}} will return to $$\Omega_{i-1}$$ and $$\xi_{i-1}$$ and set $$\alpha=\alpha*0.5$$.

This can lead to a situation where {{lmt}} down-scales $$\alpha$$ to near zero and the convergence criterion appears to report convergence. It is therefore crucial to check the iteration output. True convergence is only achieved if $$\alpha=1$$ and $$\beta=0$$.

=====AI-REML-C=====
{{lmt}} supports AI-REML-C, which relies on the construction and factorization of the mixed-model equations system coefficient matrix C.

Note that ssSNPBLUP and ssGTBLUP models are not supported. Further, it is not advisable to use airemlc for ssGBLUP models with several correlated genetic effects.

===Fixation of Sigma matrix elements===
Elements of $$\Sigma$$ matrices can be exempted from re-estimation in two ways:
#providing a boolean [[Parameter_file_elements#<sigma>|mask matrix]] $$B$$ where elements set to "T" are related to elements in $$\Sigma$$ which should be regarded as fixed, or by
#setting a diagonal element in $$\Sigma$$ desired to be fixed to 1.0 to 1.0, or by
#setting an off-diagonal element in $$\Sigma$$ desired to be fixed to 0.0 to 0.0.

Note that in case exemption is communicated via options 2 and 3 the $$\Sigma$$ matrix provided at start must still be positive definite. Further note that using option 1 overrides all information contained in $$\Sigma$$. That is if $$\Sigma[1,1]$$ is set to 1.0 but $$B$$[1,1] is set to false, $$\Sigma$$[1,1] is not exempt.

==Elements of the inverse of the mixed model coefficient matrix==
In principle {{lmt}} can generate any element of the inverse mixed model coefficient matrix. However, the user interface is currently limited to the diagonal elements for fixed factors and the diagonal blocks for random factors. These elements can either be sampled or obtained accurately via solving.
===Gibbs Sampling===
Following the approach of Harville(1999)<ref name="Harville1999" /> {{lmt}} can sample for fixed factors the diagonal elements of the inverse of the mixed model coefficient matrix, for random factors the diagonal blocks of the inverse of the coefficient matrix where the block size is determined by the dimension of the related $$\Sigma$$ matrix. The blocks are the prediction error co-variance matrices of the factor levels of correlated sub-factors. When sampling prediction error variances {{lmt}} can run many Gibbs chains in parallel allowing to exploit multi-core hardware architecture. However, it is recommended to specify not more chains than the number of available '''real''' cores excluding hyper-threading technology.
===Solving===
{{lmt}} can obtain elements of the inverse of the coefficient matrix via solving the mixed model equations. This method is currently only supported for the diagonal prediction error co-variance blocks of random factors, where the block size is determined by the dimension of the related $$\Sigma$$ matrix. For this algorithm {{lmt}} can utilize either the [[#Iterative solver]] or the [[#Direct solver]].

==Iterative inbreeding==
{{lmt}} supports the iterative calculation of inbreeding coefficients as described in VanRaden(1992)<ref name="VanRaden1992" />.

==References==
<references>
<ref name="Sorensen2002">D. Sorensen and D. Gianola; Likelihood, Bayesian, and MCMC Methods in Quantitative Genetics; 2002; 584-588</ref>
<ref name="Harville1999">David A. Harville; Use of the Gibbs sampler to invert large, possibly sparse, positive definite matrices; Linear Algebra and its Applications; 1999</ref>
<ref name="Harville2004">David A. Harville; Making REML computationally feasible for large data sets: use of the Gibbs sampler; Journal of Statistical Computation & Simulation; 2004</ref>
<ref name="Jensen1997">J. Jensen et. al.; Residual maximum likelihood estimation of (co) variance components in multivariate mixed linear models using average information; Indian Society of Agricultural Statistics; 1997</ref>
<ref name="Gilmour1995">A. Gilmour et. al.; Average information REML: an efficient algorithm for variance parameter estimation in linear mixed models; Biometrics; 1995</ref>
<ref name="Johnson1995">D.L. Johnson and R. Thompson; Restricted maximum likelihood estimation of variance components for univariate animal models using sparse matrix techniques and average information; Journal of Dairy Science; 1995</ref>
<ref name="VanRaden1992">PM VanRanden; Accounting for Inbreeding and Crossbreeding in Genetic Evaluation of Large Populations; Journal of Dairy Science; 1992</ref>
</references>

Algorithms

2022-11-04T00:30:11Z

127.0.0.1: /* REML Iteration mechanism */

==Solving Linear Mixed model Equations==
{{lmt}} supports two types of solver for solving MME's: a direct solver and an iterative solver
===Iterative solver===
The iterative solver uses the [https://en.wikipedia.org/wiki/Conjugate_gradient_method#The_preconditioned_conjugate_gradient_method preconditioned conjugate gradient method] and is {{lmt}}'s default solver. It does not require the explicit construction of any mixed model equation, and is therefore less resource demanding than the direct solver. That is, many models which cannot be solved using the direct solver can still be solved using the iterative solver. Even for small models the iterative solver usually outperforms the direct solver in terms of total processing time.

Whether the iterative solver has converged in round $$i$$ can be evaluated with convergence criterions $$log_e\left(\sqrt{\frac{||(Cx_i-b)||}{||b||}}\right)<t$$ or $$log_e\left(\sqrt{\frac{||(x_{i}-x_{i-1})||'}{||x_{i-1}||}}\right)<t$$, where $$C$$ is the mixed-model coefficient matrix, $$x_i$$ is the solution vector in round $$i$$, $$b$$ is the right-hand side and $$t$$ is the convergence threshold which defaults to -18.42, which is $$log_e(10^{-9})$$.

===Direct solver===
The direct solver requires the mixed model coefficient matrix to be build and all Kronecker products to be resolved. This can be quite memory demanding and should therefore be used carefully. The direct solver uses a [https://en.wikipedia.org/wiki/Cholesky_decomposition Cholesky decomposition] and [https://en.wikipedia.org/wiki/Triangular_matrix#Forward_and_back_substitution forward-backward-substitution] to solve the mixed model equation system, where especially the decomposition step can be very resource demanding and time consuming.

==Variance component estimation==
For random factors {{lmt}} supports variance of structure [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Sigma$$ is an dense symmetric positive definite matrix to be estimated. For residuals {{lmt}} supports variance structures $$I\otimes\Sigma$$ and $$\Theta_L(I_{n_{observations}})\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_{n_{observations}}$$ is an identity matrix of dimensions equal to the total number of observations across all traits. Note that the number of records associated to a particular $$\Sigma_i$$ should be sufficient to facilitate its estimation.

===Gibbs sampling===
====Single pass Gibbs sampling====
{{lmt}}'s single pass Gibbs sampling algorithm is described in <ref name="Sorensen2002" />. In short, all location parameters are drawn from their joint conditional posterior distribution. Note that this requires solving the mixed model equation system once per iteration which usually leads to a substantial increase in processing time. Note that ssSNBPLUP models are not supported.

====Blocked Gibbs sampling====
For random factors {{lmt}}'s blocked Gibbs sampler draws correlated location parameters within factor level from their joint conditional posterior distribution. Location parameters of fixed factors are drawn in scalar mode from their fully conditional posterior. Note that ssGTBLUP and ssSNPBLUP models are not supported.
===Restricted Maximum Likelyhood===
====MC-EM-REML====
{{lmt}} provides a monte-carlo expectation-maximisation REML algorithms which uses the preconditioned gradient solver for solving the mixed model equations and a blocked Gibbs sampler to sample the necessary traces<ref name="Harville2004" />. Note that ssSNPBLUP and ssGTBLUP models are not supported.

The MC-EM-REML convergence criterion is $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.

====Average information (AI)-REML====
{{lmt}} provides the calculation of variance components using average information REML <ref name="Johnson1995" />, <ref name="Gilmour1995" /> and <ref name="Jensen1997" />.
REML estimates of co-variance matrices can be derived using the phenotypic co-variance matrix $$V$$ or the mixed-model equations system coefficient matrix C.

{{lmt}} provides three different AI-REML convergence criterions:

* the relative change of the log-likelihood calculated as $$log_e\left(\sqrt{\frac{||(l_{i}-l_{i-1})||}{||l_{i-1}||}}\right)$$ where $$l$$ is the log-likelihood and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{||g_{i}||}\right)$$ where $$g$$ is the gradient vector and $$i$$ is the iteration counter.

=====REML Iteration mechanism=====

For finding the next parameter vector {{lmt}} use a mixture of the [https://en.wikipedia.org/wiki/Levenberg%E2%80%93Marquardt_algorithm Levenberg–Marquardt algorithm] and ordinary step length down scaling, which can be described as $$y_i=y_{i-1}+\alpha(A_i+I\beta)^{-1}j_i$$, where $$y_i$$ and $$y_{i-1}$$ are parameter vector is round $$i$$ and $$i-1$$, respectively, $$\alpha$$ is the step length, $$A$$ is the AI matrix, $$j$$ is the Jacobian and $$\beta$$ is an arbitrary real number $$\geq$$0.

Once $$A_i$$ and $$j_i$$ are derived {{lmt}} will calculate $$y_i$$ using $$\alpha=1$$ and $$\beta=0$$. If $$y_i$$ is not valid(i.e. the $$\Sigma$$ matrices are not positive definite), it will use the Levenberg-Marquardt algorithm to find a valid $$y_i$$ by setting $$\beta$$ to an ever increasing number. {{lmt}} will try this for 10000 iterations. If $$y_i$$ is still not valid {{lmt}} will return to $$A_{i-1}$$ and $$j_{i-1}$$ and set $$\alpha=\alpha*0.5$$.

This can lead to a situation where {{lmt}} down-scales $$\alpha$$ to near zero and the convergence criterion appear to have converged. It is there crucial to check the iteration output. True convergence is only achieved if $$\alpha=1$$ and $$\beta=0$$.

=====AI-REML-C=====
{{lmt}} supports AI-REML-C, which relies on the construction and factorization of the mixed-model equations system coefficient matrix C.

Note that ssSNPBLUP and ssGTBLUP models are not supported. Further, it is not advisable to use airemlc for ssGBLUP models with several correlated genetic effects.

===Fixation of Sigma matrix elements===
Elements of $$\Sigma$$ matrices can be exempted from re-estimation in two ways:
#providing a boolean [[Parameter_file_elements#<sigma>|mask matrix]] $$B$$ where elements set to "T" are related to elements in $$\Sigma$$ which should be regarded as fixed, or by
#setting a diagonal element in $$\Sigma$$ desired to be fixed to 1.0 to 1.0, or by
#setting an off-diagonal element in $$\Sigma$$ desired to be fixed to 0.0 to 0.0.

Note that in case exemption is communicated via options 2 and 3 the $$\Sigma$$ matrix provided at start must still be positive definite. Further note that using option 1 overrides all information contained in $$\Sigma$$. That is if $$\Sigma[1,1]$$ is set to 1.0 but $$B$$[1,1] is set to false, $$\Sigma$$[1,1] is not exempt.

==Elements of the inverse of the mixed model coefficient matrix==
In principle {{lmt}} can generate any element of the inverse mixed model coefficient matrix. However, the user interface is currently limited to the diagonal elements for fixed factors and the diagonal blocks for random factors. These elements can either be sampled or obtained accurately via solving.
===Gibbs Sampling===
Following the approach of Harville(1999)<ref name="Harville1999" /> {{lmt}} can sample for fixed factors the diagonal elements of the inverse of the mixed model coefficient matrix, for random factors the diagonal blocks of the inverse of the coefficient matrix where the block size is determined by the dimension of the related $$\Sigma$$ matrix. The blocks are the prediction error co-variance matrices of the factor levels of correlated sub-factors. When sampling prediction error variances {{lmt}} can run many Gibbs chains in parallel allowing to exploit multi-core hardware architecture. However, it is recommended to specify not more chains than the number of available '''real''' cores excluding hyper-threading technology.
===Solving===
{{lmt}} can obtain elements of the inverse of the coefficient matrix via solving the mixed model equations. This method is currently only supported for the diagonal prediction error co-variance blocks of random factors, where the block size is determined by the dimension of the related $$\Sigma$$ matrix. For this algorithm {{lmt}} can utilize either the [[#Iterative solver]] or the [[#Direct solver]].

==Iterative inbreeding==
{{lmt}} supports the iterative calculation of inbreeding coefficients as described in VanRaden(1992)<ref name="VanRaden1992" />.

==References==
<references>
<ref name="Sorensen2002">D. Sorensen and D. Gianola; Likelihood, Bayesian, and MCMC Methods in Quantitative Genetics; 2002; 584-588</ref>
<ref name="Harville1999">David A. Harville; Use of the Gibbs sampler to invert large, possibly sparse, positive definite matrices; Linear Algebra and its Applications; 1999</ref>
<ref name="Harville2004">David A. Harville; Making REML computationally feasible for large data sets: use of the Gibbs sampler; Journal of Statistical Computation & Simulation; 2004</ref>
<ref name="Jensen1997">J. Jensen et. al.; Residual maximum likelihood estimation of (co) variance components in multivariate mixed linear models using average information; Indian Society of Agricultural Statistics; 1997</ref>
<ref name="Gilmour1995">A. Gilmour et. al.; Average information REML: an efficient algorithm for variance parameter estimation in linear mixed models; Biometrics; 1995</ref>
<ref name="Johnson1995">D.L. Johnson and R. Thompson; Restricted maximum likelihood estimation of variance components for univariate animal models using sparse matrix techniques and average information; Journal of Dairy Science; 1995</ref>
<ref name="VanRaden1992">PM VanRanden; Accounting for Inbreeding and Crossbreeding in Genetic Evaluation of Large Populations; Journal of Dairy Science; 1992</ref>
</references>

Output files

2022-11-04T00:23:47Z

127.0.0.1: /* results.csv */

==Default output files==
===General output files===
====lmt.log====
General log file always generated. Provides information of the current state of operation.
===Operation dependent output files===
====Solving the mixed model equation system====
=====results.csv=====
The file contains the solutions for the mixed model equation system. The file has four columns:
*factor name,
*sub-factor name,
*factor level id, and
*solution.

Note that {{cc|factor name}}s are derived according to the lmt factor naming convention, and {{cc|sub-factor name}}s are user-defined and are extracted from the equation system. Further, the {{cc|factor level id}} is the original as provided by the data, pedigree, etc. For variables undergoing polynomial expansions, e.g. sub-factor {{cc|c}} in

y=x*b+age(t(co(p(1,2))))*c+id*u(v(my_var(1)))

the sub-factor name will be expanded as well to {{cc|sub-factor name_id}}, where "id" is the polynomial id. For the above example {{cc|c}} would be expanded to {{cc|c_1}} and {{cc|c_2}}.

The file has as many records the system has equations. Fixed factor levels which have been omitted due to rank deficiencies are not printed.

For a random factor with user-defined name {{cc|a}} with several correlated sub-factors one can recover the factor level effect matrices with the R code

<syntaxhighlight lang="R" line>
results<-as.matrix(fread("results.csv")))
data<-matrix(results$V4[results$V1=="a"],ncol=length(unique(results$V2[results$V1=="a")),byrow=F)
</syntaxhighlight>

=====PCG solver output files=====
======so_conv.csv======
Contains the iteration statistics with columns
*iteration number
*alpha
*beta
*$$||r_i M r_i||$$, where $$M$$ is the preconditioner matrix and $$r_i=Cx_i-b$$ for a system $$Cx=b$$
*convergence criterion CD
*convergence criterion CR
*second per iteration

====Variance component estimation using Gibbs sampling====

=====<u.d. variance name>_sigma_SA.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as MC-EM-REML iterations.
Estimates for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}}, assuming 10,000 samples, a burn-in of 1,000 samples and a thinning of 50 samples, can be obtained by

<syntaxhighlight lang="R" line>
d<-as.matrix(fread("g_sigma_SA.csv")))
n<-floor(sqrt(ncol(d)*2))
gMean<-matrix(0,n,n);gSd<-gMean
gMean[upper.tri(g,diag=TRUE)]<-colMeans(d[seq(1000,nrow(d),20),]);
gSd[upper.tri(g,diag=TRUE)]<-apply(d[seq(1000,nrow(d),20),],2,sd);
</syntaxhighlight>

====Variance component estimation using MC-EM-REML====

=====mcemreml_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*seconds for the last MC-Em iteration
*seconds for solving the equation system
*seconds for sampling the traces
*convergence criterion '''cd'''

=====<u.d. variance name>_sigma_SA.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as MC-EM-REML iterations. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_SA.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d),];
</syntaxhighlight>

====Variance component estimation using AI-REML-C====

=====aic_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*iteration number
*convergence criterion '''ng'''
*convergence criterion '''cd'''
*convergence criterion '''ll'''
*log-likelihood
*[[Algorithms#REML_Iteration_mechanism|$$\beta$$]]
*[[Algorithms#REML_Iteration_mechanism|number of Levenber-Marquardt iterations]]
*seconds for the last AI-REML iteration
*[[Algorithms#REML_Iteration_mechanism|$$\alpha$$]]

=====<u.d. variance name>_sigma_UPDATE.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as AI-REML-C iterations plus one. The row before the last contains the co-variance estimates at convergence. The last row contains the approximate standard errors of the parameter estimates. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_UPDATE.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d)-1,];
</syntaxhighlight>

Note that when restarting {{lmt}} will not overwrite this file. Instead it will append records.

===Intermediate output files===
====Files from processing pedigrees====
====="u.d. pedigree name"_sorted.csv=====
File contains a 3(ordinary pedigree) or 4(probabilistic pedigree) column matrix containing the sorted and renumbered pedigree generated from the original pedigree.
====="u.d. pedigree name"_crossref.csv=====
File contains a vector of original ids of individuals in '''"u.d. pedigree name"_sorted.csv'''. That is, the original id of individual #1 in '''"u.d. pedigree name"_sorted.csv''' is located in record 1 of this file, etc.

====="u.d. pedigree name".bin=====
Block file in binary format containing for blocks:
*a: real vector of diagonal elements of $$A$$
*ai: real vector of diagonal elements of $$A^{-1}$$
*m: real vector of mendelian sampling terms
*pe: 3 column integer matrix of the sorted and renumbered pedigree underlying $$A$$
==Requested output files==
===Files from processing pedigrees===
====Genetic group regression matrix====
lmt can write the genetic group regression matrix(aka $$Q$$) of a pedigree containing phantom parents to a user-defined file. For the necessary key string see [[Parameter_file_elements#<pedigree_name>|here]].

A $$Q$$ matrix written to {{cc|Q.coocsv}} format maybe read into R

<syntaxhighlight lang="R" line>
dim<-scan("Q.coocsv",n=2,sep=",")
Q<-matrix(0,d[1],d[2])
dat<-fread("Q.coocsv",skip=1)
Q[cbind(d$V1,d$V2)]<-d$V3
</syntaxhighlight>

===Files from building GRMs===
====Genomic relationship matrix====
lmt can write a genomic relationship matrix to a user-nominated file after it has been constructed. Supported output file formats are {{cc|csc}} and {{cc|bin}} where the latter nominates a block file in binary format. In both cases only the upper triangular in column major order is written out. The matrix maybe reconstructed in R

<syntaxhighlight lang="R" line>
d<-scan("mygrm.csv")
n<-floor(sqrt(length(d)*2))
G<-matrix(0,n,n)
G[upper.tri(G,diag=T)]<-d
</syntaxhighlight>

===Files from running AI-REML jobs===
====AI matrix, gradient vector and parameter vector====
Upon provision of the respective [[parameter_file_elements#airemlc|switch]] in the instruction file {{lmt}} writes the AI matrix, gradient vector and parameter vector to files {{cc|ai_ai.csv}}, {{cc|ai_ja.csv}} and {{cc|ai_pa.csv}}, respectively. Files {{cc|ai_ai.csv}} and {{cc|ai_ja.csv}} contain as many records as AI-REML iterations. File {{cc|ai_pa.csv}} contains contains as many records as AI-REML iterations + 1, where the first record is the parameter vector at the start.

Each row of file {{cc|ai_ai.csv}} contains the upper-triangular of the AI in column-major order. The AI matrix of say iteration 2 can be reconstructed by

<syntaxhighlight lang="R" line>
d<-fread("ai_ai.csv"))
n<-floor(sqrt(ncol(d)*2))
ai<-matrix(0,n,n);ai[upper.tri(ai,diag=TRUE)]<-d[2,];
</syntaxhighlight>

Algorithms

2022-11-03T23:42:13Z

127.0.0.1: /* Average information (AI)-REML */

==Solving Linear Mixed model Equations==
{{lmt}} supports two types of solver for solving MME's: a direct solver and an iterative solver
===Iterative solver===
The iterative solver uses the [https://en.wikipedia.org/wiki/Conjugate_gradient_method#The_preconditioned_conjugate_gradient_method preconditioned conjugate gradient method] and is {{lmt}}'s default solver. It does not require the explicit construction of any mixed model equation, and is therefore less resource demanding than the direct solver. That is, many models which cannot be solved using the direct solver can still be solved using the iterative solver. Even for small models the iterative solver usually outperforms the direct solver in terms of total processing time.

Whether the iterative solver has converged in round $$i$$ can be evaluated with convergence criterions $$log_e\left(\sqrt{\frac{||(Cx_i-b)||}{||b||}}\right)<t$$ or $$log_e\left(\sqrt{\frac{||(x_{i}-x_{i-1})||'}{||x_{i-1}||}}\right)<t$$, where $$C$$ is the mixed-model coefficient matrix, $$x_i$$ is the solution vector in round $$i$$, $$b$$ is the right-hand side and $$t$$ is the convergence threshold which defaults to -18.42, which is $$log_e(10^{-9})$$.

===Direct solver===
The direct solver requires the mixed model coefficient matrix to be build and all Kronecker products to be resolved. This can be quite memory demanding and should therefore be used carefully. The direct solver uses a [https://en.wikipedia.org/wiki/Cholesky_decomposition Cholesky decomposition] and [https://en.wikipedia.org/wiki/Triangular_matrix#Forward_and_back_substitution forward-backward-substitution] to solve the mixed model equation system, where especially the decomposition step can be very resource demanding and time consuming.

==Variance component estimation==
For random factors {{lmt}} supports variance of structure [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Sigma$$ is an dense symmetric positive definite matrix to be estimated. For residuals {{lmt}} supports variance structures $$I\otimes\Sigma$$ and $$\Theta_L(I_{n_{observations}})\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_{n_{observations}}$$ is an identity matrix of dimensions equal to the total number of observations across all traits. Note that the number of records associated to a particular $$\Sigma_i$$ should be sufficient to facilitate its estimation.

===Gibbs sampling===
====Single pass Gibbs sampling====
{{lmt}}'s single pass Gibbs sampling algorithm is described in <ref name="Sorensen2002" />. In short, all location parameters are drawn from their joint conditional posterior distribution. Note that this requires solving the mixed model equation system once per iteration which usually leads to a substantial increase in processing time. Note that ssSNBPLUP models are not supported.

====Blocked Gibbs sampling====
For random factors {{lmt}}'s blocked Gibbs sampler draws correlated location parameters within factor level from their joint conditional posterior distribution. Location parameters of fixed factors are drawn in scalar mode from their fully conditional posterior. Note that ssGTBLUP and ssSNPBLUP models are not supported.
===Restricted Maximum Likelyhood===
====MC-EM-REML====
{{lmt}} provides a monte-carlo expectation-maximisation REML algorithms which uses the preconditioned gradient solver for solving the mixed model equations and a blocked Gibbs sampler to sample the necessary traces<ref name="Harville2004" />. Note that ssSNPBLUP and ssGTBLUP models are not supported.

The MC-EM-REML convergence criterion is $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.

====Average information (AI)-REML====
{{lmt}} provides the calculation of variance components using average information REML <ref name="Johnson1995" />, <ref name="Gilmour1995" /> and <ref name="Jensen1997" />.
REML estimates of co-variance matrices can be derived using the phenotypic co-variance matrix $$V$$ or the mixed-model equations system coefficient matrix C.

{{lmt}} provides three different AI-REML convergence criterions:

* the relative change of the log-likelihood calculated as $$log_e\left(\sqrt{\frac{||(l_{i}-l_{i-1})||}{||l_{i-1}||}}\right)$$ where $$l$$ is the log-likelihood and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{||g_{i}||}\right)$$ where $$g$$ is the gradient vector and $$i$$ is the iteration counter.

=====REML Iteration mechanism=====

For finding the next parameter vector {{lmt}} use a mixture of the [https://en.wikipedia.org/wiki/Levenberg%E2%80%93Marquardt_algorithm Levenberg–Marquardt algorithm] and ordinary step length down scaling, which can be described as $$y_i=y_{i-1}+\alpha(A_i+I\beta)^{-1}j_i$$, where $$y_i$$ and $$y_{i-1}$$ are parameter vector is round $$i$$ and $$i-1$$, respectively, $$\alpha$$ is the step length, $$A$$ is the AI matrix, $$j$$ is the Jacobian and $$\beta$$ is an arbitrary positive number.

Once $$A_i$$ and $$j_i$$ are derived {{lmt}} will calculate $$y_i$$ using $$\alpha=1$$ and $$\beta=0$$. If $$y_i$$ is not valid(i.e. the $$\Sigma$$ matrices are not positive definite), it will use the Levenberg-Marquardt algorithm to find a valid $$y_i$$ by setting $$\beta$$ to an ever increasing number. {{lmt}} will try this for 10000 iterations. If $$y_i$$ is still not valid {{lmt}} will return to $$A_{i-1}$$ and $$j_{i-1}$$ and set $$\alpha=\alpha*0.5$$.

This can lead to a situation where {{lmt}} down-scales $$\alpha$$ to near zero and the convergence criterion appear to have converged. It is there crucial to check the iteration output. True convergence is only achieved if $$\alpha=1$$ and $$\beta=0$$.

=====AI-REML-C=====
{{lmt}} supports AI-REML-C, which relies on the construction and factorization of the mixed-model equations system coefficient matrix C.

Note that ssSNPBLUP and ssGTBLUP models are not supported. Further, it is not advisable to use airemlc for ssGBLUP models with several correlated genetic effects.

===Fixation of Sigma matrix elements===
Elements of $$\Sigma$$ matrices can be exempted from re-estimation in two ways:
#providing a boolean [[Parameter_file_elements#<sigma>|mask matrix]] $$B$$ where elements set to "T" are related to elements in $$\Sigma$$ which should be regarded as fixed, or by
#setting a diagonal element in $$\Sigma$$ desired to be fixed to 1.0 to 1.0, or by
#setting an off-diagonal element in $$\Sigma$$ desired to be fixed to 0.0 to 0.0.

Note that in case exemption is communicated via options 2 and 3 the $$\Sigma$$ matrix provided at start must still be positive definite. Further note that using option 1 overrides all information contained in $$\Sigma$$. That is if $$\Sigma[1,1]$$ is set to 1.0 but $$B$$[1,1] is set to false, $$\Sigma$$[1,1] is not exempt.

==Elements of the inverse of the mixed model coefficient matrix==
In principle {{lmt}} can generate any element of the inverse mixed model coefficient matrix. However, the user interface is currently limited to the diagonal elements for fixed factors and the diagonal blocks for random factors. These elements can either be sampled or obtained accurately via solving.
===Gibbs Sampling===
Following the approach of Harville(1999)<ref name="Harville1999" /> {{lmt}} can sample for fixed factors the diagonal elements of the inverse of the mixed model coefficient matrix, for random factors the diagonal blocks of the inverse of the coefficient matrix where the block size is determined by the dimension of the related $$\Sigma$$ matrix. The blocks are the prediction error co-variance matrices of the factor levels of correlated sub-factors. When sampling prediction error variances {{lmt}} can run many Gibbs chains in parallel allowing to exploit multi-core hardware architecture. However, it is recommended to specify not more chains than the number of available '''real''' cores excluding hyper-threading technology.
===Solving===
{{lmt}} can obtain elements of the inverse of the coefficient matrix via solving the mixed model equations. This method is currently only supported for the diagonal prediction error co-variance blocks of random factors, where the block size is determined by the dimension of the related $$\Sigma$$ matrix. For this algorithm {{lmt}} can utilize either the [[#Iterative solver]] or the [[#Direct solver]].

==Iterative inbreeding==
{{lmt}} supports the iterative calculation of inbreeding coefficients as described in VanRaden(1992)<ref name="VanRaden1992" />.

==References==
<references>
<ref name="Sorensen2002">D. Sorensen and D. Gianola; Likelihood, Bayesian, and MCMC Methods in Quantitative Genetics; 2002; 584-588</ref>
<ref name="Harville1999">David A. Harville; Use of the Gibbs sampler to invert large, possibly sparse, positive definite matrices; Linear Algebra and its Applications; 1999</ref>
<ref name="Harville2004">David A. Harville; Making REML computationally feasible for large data sets: use of the Gibbs sampler; Journal of Statistical Computation & Simulation; 2004</ref>
<ref name="Jensen1997">J. Jensen et. al.; Residual maximum likelihood estimation of (co) variance components in multivariate mixed linear models using average information; Indian Society of Agricultural Statistics; 1997</ref>
<ref name="Gilmour1995">A. Gilmour et. al.; Average information REML: an efficient algorithm for variance parameter estimation in linear mixed models; Biometrics; 1995</ref>
<ref name="Johnson1995">D.L. Johnson and R. Thompson; Restricted maximum likelihood estimation of variance components for univariate animal models using sparse matrix techniques and average information; Journal of Dairy Science; 1995</ref>
<ref name="VanRaden1992">PM VanRanden; Accounting for Inbreeding and Crossbreeding in Genetic Evaluation of Large Populations; Journal of Dairy Science; 1992</ref>
</references>

Output files

2022-11-03T23:37:26Z

127.0.0.1: /* aic_conv.csv */

==Default output files==
===General output files===
====lmt.log====
General log file always generated. Provides information of the current state of operation.
===Operation dependent output files===
====Solving the mixed model equation system====
=====results.csv=====
The file contains the solutions for the mixed model equation system. The file has four columns:
*factor name,
*sub-factor name,
*factor level id, and
*solution.

Note that {{cc|factor name}}s are derived according to the lmt factor naming convention, and {{cc|sub-factor name}}s are user-defined and are extracted from the equation system. Further, the {{cc|factor level id}} is the original as provided by the data, pedigree, etc. For variables undergoing polynomial expansions, e.g. sub-factor {{cc|c}} in

y=x*b+age(t(co(p(1,2))))*c+id*u(v(my_var(1)))

the sub-factor name will be expanded as well to {{cc|sub-factor name_id}}, where "id" is the polynomial id. For the above example {{cc|c}} would be expanded to {{cc|c_1}} and {{cc|c_2}}.

The file has as many records the system has equations. Fixed factor levels which have been omitted due to rank deficiencies are not printed.
=====PCG solver output files=====
======so_conv.csv======
Contains the iteration statistics with columns
*iteration number
*alpha
*beta
*$$||r_i M r_i||$$, where $$M$$ is the preconditioner matrix and $$r_i=Cx_i-b$$ for a system $$Cx=b$$
*convergence criterion CD
*convergence criterion CR
*second per iteration

====Variance component estimation using Gibbs sampling====

=====<u.d. variance name>_sigma_SA.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as MC-EM-REML iterations.
Estimates for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}}, assuming 10,000 samples, a burn-in of 1,000 samples and a thinning of 50 samples, can be obtained by

<syntaxhighlight lang="R" line>
d<-as.matrix(fread("g_sigma_SA.csv")))
n<-floor(sqrt(ncol(d)*2))
gMean<-matrix(0,n,n);gSd<-gMean
gMean[upper.tri(g,diag=TRUE)]<-colMeans(d[seq(1000,nrow(d),20),]);
gSd[upper.tri(g,diag=TRUE)]<-apply(d[seq(1000,nrow(d),20),],2,sd);
</syntaxhighlight>

====Variance component estimation using MC-EM-REML====

=====mcemreml_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*seconds for the last MC-Em iteration
*seconds for solving the equation system
*seconds for sampling the traces
*convergence criterion '''cd'''

=====<u.d. variance name>_sigma_SA.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as MC-EM-REML iterations. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_SA.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d),];
</syntaxhighlight>

====Variance component estimation using AI-REML-C====

=====aic_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*iteration number
*convergence criterion '''ng'''
*convergence criterion '''cd'''
*convergence criterion '''ll'''
*log-likelihood
*[[Algorithms#REML_Iteration_mechanism|$$\beta$$]]
*[[Algorithms#REML_Iteration_mechanism|number of Levenber-Marquardt iterations]]
*seconds for the last AI-REML iteration
*[[Algorithms#REML_Iteration_mechanism|$$\alpha$$]]

=====<u.d. variance name>_sigma_UPDATE.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as AI-REML-C iterations plus one. The row before the last contains the co-variance estimates at convergence. The last row contains the approximate standard errors of the parameter estimates. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_UPDATE.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d)-1,];
</syntaxhighlight>

Note that when restarting {{lmt}} will not overwrite this file. Instead it will append records.

===Intermediate output files===
====Files from processing pedigrees====
====="u.d. pedigree name"_sorted.csv=====
File contains a 3(ordinary pedigree) or 4(probabilistic pedigree) column matrix containing the sorted and renumbered pedigree generated from the original pedigree.
====="u.d. pedigree name"_crossref.csv=====
File contains a vector of original ids of individuals in '''"u.d. pedigree name"_sorted.csv'''. That is, the original id of individual #1 in '''"u.d. pedigree name"_sorted.csv''' is located in record 1 of this file, etc.

====="u.d. pedigree name".bin=====
Block file in binary format containing for blocks:
*a: real vector of diagonal elements of $$A$$
*ai: real vector of diagonal elements of $$A^{-1}$$
*m: real vector of mendelian sampling terms
*pe: 3 column integer matrix of the sorted and renumbered pedigree underlying $$A$$
==Requested output files==
===Files from processing pedigrees===
====Genetic group regression matrix====
lmt can write the genetic group regression matrix(aka $$Q$$) of a pedigree containing phantom parents to a user-defined file. For the necessary key string see [[Parameter_file_elements#<pedigree_name>|here]].

A $$Q$$ matrix written to {{cc|Q.coocsv}} format maybe read into R

<syntaxhighlight lang="R" line>
dim<-scan("Q.coocsv",n=2,sep=",")
Q<-matrix(0,d[1],d[2])
dat<-fread("Q.coocsv",skip=1)
Q[cbind(d$V1,d$V2)]<-d$V3
</syntaxhighlight>

===Files from building GRMs===
====Genomic relationship matrix====
lmt can write a genomic relationship matrix to a user-nominated file after it has been constructed. Supported output file formats are {{cc|csc}} and {{cc|bin}} where the latter nominates a block file in binary format. In both cases only the upper triangular in column major order is written out. The matrix maybe reconstructed in R

<syntaxhighlight lang="R" line>
d<-scan("mygrm.csv")
n<-floor(sqrt(length(d)*2))
G<-matrix(0,n,n)
G[upper.tri(G,diag=T)]<-d
</syntaxhighlight>

===Files from running AI-REML jobs===
====AI matrix, gradient vector and parameter vector====
Upon provision of the respective [[parameter_file_elements#airemlc|switch]] in the instruction file {{lmt}} writes the AI matrix, gradient vector and parameter vector to files {{cc|ai_ai.csv}}, {{cc|ai_ja.csv}} and {{cc|ai_pa.csv}}, respectively. Files {{cc|ai_ai.csv}} and {{cc|ai_ja.csv}} contain as many records as AI-REML iterations. File {{cc|ai_pa.csv}} contains contains as many records as AI-REML iterations + 1, where the first record is the parameter vector at the start.

Each row of file {{cc|ai_ai.csv}} contains the upper-triangular of the AI in column-major order. The AI matrix of say iteration 2 can be reconstructed by

<syntaxhighlight lang="R" line>
d<-fread("ai_ai.csv"))
n<-floor(sqrt(ncol(d)*2))
ai<-matrix(0,n,n);ai[upper.tri(ai,diag=TRUE)]<-d[2,];
</syntaxhighlight>

Output files

2022-11-03T23:36:29Z

127.0.0.1: /* aic_conv.csv */

==Default output files==
===General output files===
====lmt.log====
General log file always generated. Provides information of the current state of operation.
===Operation dependent output files===
====Solving the mixed model equation system====
=====results.csv=====
The file contains the solutions for the mixed model equation system. The file has four columns:
*factor name,
*sub-factor name,
*factor level id, and
*solution.

Note that {{cc|factor name}}s are derived according to the lmt factor naming convention, and {{cc|sub-factor name}}s are user-defined and are extracted from the equation system. Further, the {{cc|factor level id}} is the original as provided by the data, pedigree, etc. For variables undergoing polynomial expansions, e.g. sub-factor {{cc|c}} in

y=x*b+age(t(co(p(1,2))))*c+id*u(v(my_var(1)))

the sub-factor name will be expanded as well to {{cc|sub-factor name_id}}, where "id" is the polynomial id. For the above example {{cc|c}} would be expanded to {{cc|c_1}} and {{cc|c_2}}.

The file has as many records the system has equations. Fixed factor levels which have been omitted due to rank deficiencies are not printed.
=====PCG solver output files=====
======so_conv.csv======
Contains the iteration statistics with columns
*iteration number
*alpha
*beta
*$$||r_i M r_i||$$, where $$M$$ is the preconditioner matrix and $$r_i=Cx_i-b$$ for a system $$Cx=b$$
*convergence criterion CD
*convergence criterion CR
*second per iteration

====Variance component estimation using Gibbs sampling====

=====<u.d. variance name>_sigma_SA.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as MC-EM-REML iterations.
Estimates for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}}, assuming 10,000 samples, a burn-in of 1,000 samples and a thinning of 50 samples, can be obtained by

<syntaxhighlight lang="R" line>
d<-as.matrix(fread("g_sigma_SA.csv")))
n<-floor(sqrt(ncol(d)*2))
gMean<-matrix(0,n,n);gSd<-gMean
gMean[upper.tri(g,diag=TRUE)]<-colMeans(d[seq(1000,nrow(d),20),]);
gSd[upper.tri(g,diag=TRUE)]<-apply(d[seq(1000,nrow(d),20),],2,sd);
</syntaxhighlight>

====Variance component estimation using MC-EM-REML====

=====mcemreml_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*seconds for the last MC-Em iteration
*seconds for solving the equation system
*seconds for sampling the traces
*convergence criterion '''cd'''

=====<u.d. variance name>_sigma_SA.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as MC-EM-REML iterations. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_SA.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d),];
</syntaxhighlight>

====Variance component estimation using AI-REML-C====

=====aic_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*iteration number
*convergence criterion '''ng'''
*convergence criterion '''cd'''
*convergence criterion '''ll'''
*log-likelihood
*[[Algorithms#REML_Iteration_mechanism|$$\beta$$]]
*[[Algorithms#REML_Iteration_mechanism|number of Levenber-Marquardt iterations]]
*seconds for the last AI-REML iteration

=====<u.d. variance name>_sigma_UPDATE.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as AI-REML-C iterations plus one. The row before the last contains the co-variance estimates at convergence. The last row contains the approximate standard errors of the parameter estimates. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_UPDATE.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d)-1,];
</syntaxhighlight>

Note that when restarting {{lmt}} will not overwrite this file. Instead it will append records.

===Intermediate output files===
====Files from processing pedigrees====
====="u.d. pedigree name"_sorted.csv=====
File contains a 3(ordinary pedigree) or 4(probabilistic pedigree) column matrix containing the sorted and renumbered pedigree generated from the original pedigree.
====="u.d. pedigree name"_crossref.csv=====
File contains a vector of original ids of individuals in '''"u.d. pedigree name"_sorted.csv'''. That is, the original id of individual #1 in '''"u.d. pedigree name"_sorted.csv''' is located in record 1 of this file, etc.

====="u.d. pedigree name".bin=====
Block file in binary format containing for blocks:
*a: real vector of diagonal elements of $$A$$
*ai: real vector of diagonal elements of $$A^{-1}$$
*m: real vector of mendelian sampling terms
*pe: 3 column integer matrix of the sorted and renumbered pedigree underlying $$A$$
==Requested output files==
===Files from processing pedigrees===
====Genetic group regression matrix====
lmt can write the genetic group regression matrix(aka $$Q$$) of a pedigree containing phantom parents to a user-defined file. For the necessary key string see [[Parameter_file_elements#<pedigree_name>|here]].

A $$Q$$ matrix written to {{cc|Q.coocsv}} format maybe read into R

<syntaxhighlight lang="R" line>
dim<-scan("Q.coocsv",n=2,sep=",")
Q<-matrix(0,d[1],d[2])
dat<-fread("Q.coocsv",skip=1)
Q[cbind(d$V1,d$V2)]<-d$V3
</syntaxhighlight>

===Files from building GRMs===
====Genomic relationship matrix====
lmt can write a genomic relationship matrix to a user-nominated file after it has been constructed. Supported output file formats are {{cc|csc}} and {{cc|bin}} where the latter nominates a block file in binary format. In both cases only the upper triangular in column major order is written out. The matrix maybe reconstructed in R

<syntaxhighlight lang="R" line>
d<-scan("mygrm.csv")
n<-floor(sqrt(length(d)*2))
G<-matrix(0,n,n)
G[upper.tri(G,diag=T)]<-d
</syntaxhighlight>

===Files from running AI-REML jobs===
====AI matrix, gradient vector and parameter vector====
Upon provision of the respective [[parameter_file_elements#airemlc|switch]] in the instruction file {{lmt}} writes the AI matrix, gradient vector and parameter vector to files {{cc|ai_ai.csv}}, {{cc|ai_ja.csv}} and {{cc|ai_pa.csv}}, respectively. Files {{cc|ai_ai.csv}} and {{cc|ai_ja.csv}} contain as many records as AI-REML iterations. File {{cc|ai_pa.csv}} contains contains as many records as AI-REML iterations + 1, where the first record is the parameter vector at the start.

Each row of file {{cc|ai_ai.csv}} contains the upper-triangular of the AI in column-major order. The AI matrix of say iteration 2 can be reconstructed by

<syntaxhighlight lang="R" line>
d<-fread("ai_ai.csv"))
n<-floor(sqrt(ncol(d)*2))
ai<-matrix(0,n,n);ai[upper.tri(ai,diag=TRUE)]<-d[2,];
</syntaxhighlight>

Output files

2022-11-03T23:35:22Z

127.0.0.1: /* aic_conv.csv */

==Default output files==
===General output files===
====lmt.log====
General log file always generated. Provides information of the current state of operation.
===Operation dependent output files===
====Solving the mixed model equation system====
=====results.csv=====
The file contains the solutions for the mixed model equation system. The file has four columns:
*factor name,
*sub-factor name,
*factor level id, and
*solution.

Note that {{cc|factor name}}s are derived according to the lmt factor naming convention, and {{cc|sub-factor name}}s are user-defined and are extracted from the equation system. Further, the {{cc|factor level id}} is the original as provided by the data, pedigree, etc. For variables undergoing polynomial expansions, e.g. sub-factor {{cc|c}} in

y=x*b+age(t(co(p(1,2))))*c+id*u(v(my_var(1)))

the sub-factor name will be expanded as well to {{cc|sub-factor name_id}}, where "id" is the polynomial id. For the above example {{cc|c}} would be expanded to {{cc|c_1}} and {{cc|c_2}}.

The file has as many records the system has equations. Fixed factor levels which have been omitted due to rank deficiencies are not printed.
=====PCG solver output files=====
======so_conv.csv======
Contains the iteration statistics with columns
*iteration number
*alpha
*beta
*$$||r_i M r_i||$$, where $$M$$ is the preconditioner matrix and $$r_i=Cx_i-b$$ for a system $$Cx=b$$
*convergence criterion CD
*convergence criterion CR
*second per iteration

====Variance component estimation using Gibbs sampling====

=====<u.d. variance name>_sigma_SA.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as MC-EM-REML iterations.
Estimates for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}}, assuming 10,000 samples, a burn-in of 1,000 samples and a thinning of 50 samples, can be obtained by

<syntaxhighlight lang="R" line>
d<-as.matrix(fread("g_sigma_SA.csv")))
n<-floor(sqrt(ncol(d)*2))
gMean<-matrix(0,n,n);gSd<-gMean
gMean[upper.tri(g,diag=TRUE)]<-colMeans(d[seq(1000,nrow(d),20),]);
gSd[upper.tri(g,diag=TRUE)]<-apply(d[seq(1000,nrow(d),20),],2,sd);
</syntaxhighlight>

====Variance component estimation using MC-EM-REML====

=====mcemreml_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*seconds for the last MC-Em iteration
*seconds for solving the equation system
*seconds for sampling the traces
*convergence criterion '''cd'''

=====<u.d. variance name>_sigma_SA.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as MC-EM-REML iterations. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_SA.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d),];
</syntaxhighlight>

====Variance component estimation using AI-REML-C====

=====aic_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*iteration number
*convergence criterion '''ng'''
*convergence criterion '''cd'''
*convergence criterion '''ll'''
*log-likelihood
*[[Algorithms#REML_Iteration_mechanism|$$\beta$$]]
*number of Newton over-relaxation iterations
*seconds for the last AI-REML iteration

=====<u.d. variance name>_sigma_UPDATE.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as AI-REML-C iterations plus one. The row before the last contains the co-variance estimates at convergence. The last row contains the approximate standard errors of the parameter estimates. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_UPDATE.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d)-1,];
</syntaxhighlight>

Note that when restarting {{lmt}} will not overwrite this file. Instead it will append records.

===Intermediate output files===
====Files from processing pedigrees====
====="u.d. pedigree name"_sorted.csv=====
File contains a 3(ordinary pedigree) or 4(probabilistic pedigree) column matrix containing the sorted and renumbered pedigree generated from the original pedigree.
====="u.d. pedigree name"_crossref.csv=====
File contains a vector of original ids of individuals in '''"u.d. pedigree name"_sorted.csv'''. That is, the original id of individual #1 in '''"u.d. pedigree name"_sorted.csv''' is located in record 1 of this file, etc.

====="u.d. pedigree name".bin=====
Block file in binary format containing for blocks:
*a: real vector of diagonal elements of $$A$$
*ai: real vector of diagonal elements of $$A^{-1}$$
*m: real vector of mendelian sampling terms
*pe: 3 column integer matrix of the sorted and renumbered pedigree underlying $$A$$
==Requested output files==
===Files from processing pedigrees===
====Genetic group regression matrix====
lmt can write the genetic group regression matrix(aka $$Q$$) of a pedigree containing phantom parents to a user-defined file. For the necessary key string see [[Parameter_file_elements#<pedigree_name>|here]].

A $$Q$$ matrix written to {{cc|Q.coocsv}} format maybe read into R

<syntaxhighlight lang="R" line>
dim<-scan("Q.coocsv",n=2,sep=",")
Q<-matrix(0,d[1],d[2])
dat<-fread("Q.coocsv",skip=1)
Q[cbind(d$V1,d$V2)]<-d$V3
</syntaxhighlight>

===Files from building GRMs===
====Genomic relationship matrix====
lmt can write a genomic relationship matrix to a user-nominated file after it has been constructed. Supported output file formats are {{cc|csc}} and {{cc|bin}} where the latter nominates a block file in binary format. In both cases only the upper triangular in column major order is written out. The matrix maybe reconstructed in R

<syntaxhighlight lang="R" line>
d<-scan("mygrm.csv")
n<-floor(sqrt(length(d)*2))
G<-matrix(0,n,n)
G[upper.tri(G,diag=T)]<-d
</syntaxhighlight>

===Files from running AI-REML jobs===
====AI matrix, gradient vector and parameter vector====
Upon provision of the respective [[parameter_file_elements#airemlc|switch]] in the instruction file {{lmt}} writes the AI matrix, gradient vector and parameter vector to files {{cc|ai_ai.csv}}, {{cc|ai_ja.csv}} and {{cc|ai_pa.csv}}, respectively. Files {{cc|ai_ai.csv}} and {{cc|ai_ja.csv}} contain as many records as AI-REML iterations. File {{cc|ai_pa.csv}} contains contains as many records as AI-REML iterations + 1, where the first record is the parameter vector at the start.

Each row of file {{cc|ai_ai.csv}} contains the upper-triangular of the AI in column-major order. The AI matrix of say iteration 2 can be reconstructed by

<syntaxhighlight lang="R" line>
d<-fread("ai_ai.csv"))
n<-floor(sqrt(ncol(d)*2))
ai<-matrix(0,n,n);ai[upper.tri(ai,diag=TRUE)]<-d[2,];
</syntaxhighlight>

Algorithms

2022-11-03T23:29:42Z

127.0.0.1: /* REML Iteration mechanism */

==Solving Linear Mixed model Equations==
{{lmt}} supports two types of solver for solving MME's: a direct solver and an iterative solver
===Iterative solver===
The iterative solver uses the [https://en.wikipedia.org/wiki/Conjugate_gradient_method#The_preconditioned_conjugate_gradient_method preconditioned conjugate gradient method] and is {{lmt}}'s default solver. It does not require the explicit construction of any mixed model equation, and is therefore less resource demanding than the direct solver. That is, many models which cannot be solved using the direct solver can still be solved using the iterative solver. Even for small models the iterative solver usually outperforms the direct solver in terms of total processing time.

Whether the iterative solver has converged in round $$i$$ can be evaluated with convergence criterions $$log_e\left(\sqrt{\frac{||(Cx_i-b)||}{||b||}}\right)<t$$ or $$log_e\left(\sqrt{\frac{||(x_{i}-x_{i-1})||'}{||x_{i-1}||}}\right)<t$$, where $$C$$ is the mixed-model coefficient matrix, $$x_i$$ is the solution vector in round $$i$$, $$b$$ is the right-hand side and $$t$$ is the convergence threshold which defaults to -18.42, which is $$log_e(10^{-9})$$.

===Direct solver===
The direct solver requires the mixed model coefficient matrix to be build and all Kronecker products to be resolved. This can be quite memory demanding and should therefore be used carefully. The direct solver uses a [https://en.wikipedia.org/wiki/Cholesky_decomposition Cholesky decomposition] and [https://en.wikipedia.org/wiki/Triangular_matrix#Forward_and_back_substitution forward-backward-substitution] to solve the mixed model equation system, where especially the decomposition step can be very resource demanding and time consuming.

==Variance component estimation==
For random factors {{lmt}} supports variance of structure [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Sigma$$ is an dense symmetric positive definite matrix to be estimated. For residuals {{lmt}} supports variance structures $$I\otimes\Sigma$$ and $$\Theta_L(I_{n_{observations}})\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_{n_{observations}}$$ is an identity matrix of dimensions equal to the total number of observations across all traits. Note that the number of records associated to a particular $$\Sigma_i$$ should be sufficient to facilitate its estimation.

===Gibbs sampling===
====Single pass Gibbs sampling====
{{lmt}}'s single pass Gibbs sampling algorithm is described in <ref name="Sorensen2002" />. In short, all location parameters are drawn from their joint conditional posterior distribution. Note that this requires solving the mixed model equation system once per iteration which usually leads to a substantial increase in processing time. Note that ssSNBPLUP models are not supported.

====Blocked Gibbs sampling====
For random factors {{lmt}}'s blocked Gibbs sampler draws correlated location parameters within factor level from their joint conditional posterior distribution. Location parameters of fixed factors are drawn in scalar mode from their fully conditional posterior. Note that ssGTBLUP and ssSNPBLUP models are not supported.
===Restricted Maximum Likelyhood===
====MC-EM-REML====
{{lmt}} provides a monte-carlo expectation-maximisation REML algorithms which uses the preconditioned gradient solver for solving the mixed model equations and a blocked Gibbs sampler to sample the necessary traces<ref name="Harville2004" />. Note that ssSNPBLUP and ssGTBLUP models are not supported.

The MC-EM-REML convergence criterion is $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.

====Average information (AI)-REML====
{{lmt}} provides the calculation of variance components using average information REML <ref name="Johnson1995" />, <ref name="Gilmour1995" /> and <ref name="Jensen1997" />.
REML estimates of co-variance matrices can be derived using the phenotypic co-variance matrix $$V$$ or the mixed-model equations system coefficient matrix C.

{{lmt}} provides three different AI-REML convergence criterions:

* the relative change of the log-likelihood calculated as $$log_e\left(\sqrt{\frac{||(l_{i}-l_{i-1})||}{||l_{i-1}||}}\right)$$ where $$l$$ is the log-likelihood and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{||g_{i}||}\right)$$ where $$g$$ is the gradient vector and $$i$$ is the iteration counter.

=====AI-REML-C=====
{{lmt}} supports AI-REML-C, which relies on the construction and factorization of the mixed-model equations system coefficient matrix C.

Note that ssSNPBLUP and ssGTBLUP models are not supported. Further, it is not advisable to use airemlc for ssGBLUP models with several correlated genetic effects.

======REML Iteration mechanism======

For finding the next parameter vector {{lmt}} use a mixture of the [https://en.wikipedia.org/wiki/Levenberg%E2%80%93Marquardt_algorithm Levenberg–Marquardt algorithm] and ordinary step length down scaling, which can be described as $$y_i=y_{i-1}+\alpha(A_i+I\beta)^{-1}j_i$$, where $$y_i$$ and $$y_{i-1}$$ are parameter vector is round $$i$$ and $$i-1$$, respectively, $$\alpha$$ is the step length, $$A$$ is the AI matrix, $$j$$ is the Jacobian and $$\beta$$ is an arbitrary positive number.

Once $$A_i$$ and $$j_i$$ are derived {{lmt}} will calculate $$y_i$$ using $$\alpha=1$$ and $$\beta=0$$. If $$y_i$$ is not valid(i.e. the $$\Sigma$$ matrices are not positive definite), it will use the Levenberg-Marquardt algorithm to find a valid $$y_i$$ by setting $$\beta$$ to an ever increasing number. {{lmt}} will try this for 10000 iterations. If $$y_i$$ is still not valid {{lmt}} will return to $$A_{i-1}$$ and $$j_{i-1}$$ and set $$\alpha=\alpha*0.5$$.

This can lead to a situation where {{lmt}} down-scales $$\alpha$$ to near zero and the convergence criterion appear to have converged. It is there crucial to check the iteration output. True convergence is only achieved if $$\alpha=1$$ and $$\beta=0$$.

===Fixation of Sigma matrix elements===
Elements of $$\Sigma$$ matrices can be exempted from re-estimation in two ways:
#providing a boolean [[Parameter_file_elements#<sigma>|mask matrix]] $$B$$ where elements set to "T" are related to elements in $$\Sigma$$ which should be regarded as fixed, or by
#setting a diagonal element in $$\Sigma$$ desired to be fixed to 1.0 to 1.0, or by
#setting an off-diagonal element in $$\Sigma$$ desired to be fixed to 0.0 to 0.0.

Note that in case exemption is communicated via options 2 and 3 the $$\Sigma$$ matrix provided at start must still be positive definite. Further note that using option 1 overrides all information contained in $$\Sigma$$. That is if $$\Sigma[1,1]$$ is set to 1.0 but $$B$$[1,1] is set to false, $$\Sigma$$[1,1] is not exempt.

==Elements of the inverse of the mixed model coefficient matrix==
In principle {{lmt}} can generate any element of the inverse mixed model coefficient matrix. However, the user interface is currently limited to the diagonal elements for fixed factors and the diagonal blocks for random factors. These elements can either be sampled or obtained accurately via solving.
===Gibbs Sampling===
Following the approach of Harville(1999)<ref name="Harville1999" /> {{lmt}} can sample for fixed factors the diagonal elements of the inverse of the mixed model coefficient matrix, for random factors the diagonal blocks of the inverse of the coefficient matrix where the block size is determined by the dimension of the related $$\Sigma$$ matrix. The blocks are the prediction error co-variance matrices of the factor levels of correlated sub-factors. When sampling prediction error variances {{lmt}} can run many Gibbs chains in parallel allowing to exploit multi-core hardware architecture. However, it is recommended to specify not more chains than the number of available '''real''' cores excluding hyper-threading technology.
===Solving===
{{lmt}} can obtain elements of the inverse of the coefficient matrix via solving the mixed model equations. This method is currently only supported for the diagonal prediction error co-variance blocks of random factors, where the block size is determined by the dimension of the related $$\Sigma$$ matrix. For this algorithm {{lmt}} can utilize either the [[#Iterative solver]] or the [[#Direct solver]].

==Iterative inbreeding==
{{lmt}} supports the iterative calculation of inbreeding coefficients as described in VanRaden(1992)<ref name="VanRaden1992" />.

==References==
<references>
<ref name="Sorensen2002">D. Sorensen and D. Gianola; Likelihood, Bayesian, and MCMC Methods in Quantitative Genetics; 2002; 584-588</ref>
<ref name="Harville1999">David A. Harville; Use of the Gibbs sampler to invert large, possibly sparse, positive definite matrices; Linear Algebra and its Applications; 1999</ref>
<ref name="Harville2004">David A. Harville; Making REML computationally feasible for large data sets: use of the Gibbs sampler; Journal of Statistical Computation & Simulation; 2004</ref>
<ref name="Jensen1997">J. Jensen et. al.; Residual maximum likelihood estimation of (co) variance components in multivariate mixed linear models using average information; Indian Society of Agricultural Statistics; 1997</ref>
<ref name="Gilmour1995">A. Gilmour et. al.; Average information REML: an efficient algorithm for variance parameter estimation in linear mixed models; Biometrics; 1995</ref>
<ref name="Johnson1995">D.L. Johnson and R. Thompson; Restricted maximum likelihood estimation of variance components for univariate animal models using sparse matrix techniques and average information; Journal of Dairy Science; 1995</ref>
<ref name="VanRaden1992">PM VanRanden; Accounting for Inbreeding and Crossbreeding in Genetic Evaluation of Large Populations; Journal of Dairy Science; 1992</ref>
</references>

Algorithms

2022-11-03T23:08:49Z

127.0.0.1: /* AI-REML-C */

==Solving Linear Mixed model Equations==
{{lmt}} supports two types of solver for solving MME's: a direct solver and an iterative solver
===Iterative solver===
The iterative solver uses the [https://en.wikipedia.org/wiki/Conjugate_gradient_method#The_preconditioned_conjugate_gradient_method preconditioned conjugate gradient method] and is {{lmt}}'s default solver. It does not require the explicit construction of any mixed model equation, and is therefore less resource demanding than the direct solver. That is, many models which cannot be solved using the direct solver can still be solved using the iterative solver. Even for small models the iterative solver usually outperforms the direct solver in terms of total processing time.

Whether the iterative solver has converged in round $$i$$ can be evaluated with convergence criterions $$log_e\left(\sqrt{\frac{||(Cx_i-b)||}{||b||}}\right)<t$$ or $$log_e\left(\sqrt{\frac{||(x_{i}-x_{i-1})||'}{||x_{i-1}||}}\right)<t$$, where $$C$$ is the mixed-model coefficient matrix, $$x_i$$ is the solution vector in round $$i$$, $$b$$ is the right-hand side and $$t$$ is the convergence threshold which defaults to -18.42, which is $$log_e(10^{-9})$$.

===Direct solver===
The direct solver requires the mixed model coefficient matrix to be build and all Kronecker products to be resolved. This can be quite memory demanding and should therefore be used carefully. The direct solver uses a [https://en.wikipedia.org/wiki/Cholesky_decomposition Cholesky decomposition] and [https://en.wikipedia.org/wiki/Triangular_matrix#Forward_and_back_substitution forward-backward-substitution] to solve the mixed model equation system, where especially the decomposition step can be very resource demanding and time consuming.

==Variance component estimation==
For random factors {{lmt}} supports variance of structure [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Sigma$$ is an dense symmetric positive definite matrix to be estimated. For residuals {{lmt}} supports variance structures $$I\otimes\Sigma$$ and $$\Theta_L(I_{n_{observations}})\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_{n_{observations}}$$ is an identity matrix of dimensions equal to the total number of observations across all traits. Note that the number of records associated to a particular $$\Sigma_i$$ should be sufficient to facilitate its estimation.

===Gibbs sampling===
====Single pass Gibbs sampling====
{{lmt}}'s single pass Gibbs sampling algorithm is described in <ref name="Sorensen2002" />. In short, all location parameters are drawn from their joint conditional posterior distribution. Note that this requires solving the mixed model equation system once per iteration which usually leads to a substantial increase in processing time. Note that ssSNBPLUP models are not supported.

====Blocked Gibbs sampling====
For random factors {{lmt}}'s blocked Gibbs sampler draws correlated location parameters within factor level from their joint conditional posterior distribution. Location parameters of fixed factors are drawn in scalar mode from their fully conditional posterior. Note that ssGTBLUP and ssSNPBLUP models are not supported.
===Restricted Maximum Likelyhood===
====MC-EM-REML====
{{lmt}} provides a monte-carlo expectation-maximisation REML algorithms which uses the preconditioned gradient solver for solving the mixed model equations and a blocked Gibbs sampler to sample the necessary traces<ref name="Harville2004" />. Note that ssSNPBLUP and ssGTBLUP models are not supported.

The MC-EM-REML convergence criterion is $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.

====Average information (AI)-REML====
{{lmt}} provides the calculation of variance components using average information REML <ref name="Johnson1995" />, <ref name="Gilmour1995" /> and <ref name="Jensen1997" />.
REML estimates of co-variance matrices can be derived using the phenotypic co-variance matrix $$V$$ or the mixed-model equations system coefficient matrix C.

{{lmt}} provides three different AI-REML convergence criterions:

* the relative change of the log-likelihood calculated as $$log_e\left(\sqrt{\frac{||(l_{i}-l_{i-1})||}{||l_{i-1}||}}\right)$$ where $$l$$ is the log-likelihood and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{||g_{i}||}\right)$$ where $$g$$ is the gradient vector and $$i$$ is the iteration counter.

=====AI-REML-C=====
{{lmt}} supports AI-REML-C, which relies on the construction and factorization of the mixed-model equations system coefficient matrix C.

Note that ssSNPBLUP and ssGTBLUP models are not supported. Further, it is not advisable to use airemlc for ssGBLUP models with several correlated genetic effects.

======REML Iteration mechanism======

For finding the next parameter vector {{lmt}} use a mixture of the [https://en.wikipedia.org/wiki/Levenberg%E2%80%93Marquardt_algorithm](#Levenberg–Marquardt algorithm) and ordinary step length down scaling.

===Fixation of Sigma matrix elements===
Elements of $$\Sigma$$ matrices can be exempted from re-estimation in two ways:
#providing a boolean [[Parameter_file_elements#<sigma>|mask matrix]] $$B$$ where elements set to "T" are related to elements in $$\Sigma$$ which should be regarded as fixed, or by
#setting a diagonal element in $$\Sigma$$ desired to be fixed to 1.0 to 1.0, or by
#setting an off-diagonal element in $$\Sigma$$ desired to be fixed to 0.0 to 0.0.

Note that in case exemption is communicated via options 2 and 3 the $$\Sigma$$ matrix provided at start must still be positive definite. Further note that using option 1 overrides all information contained in $$\Sigma$$. That is if $$\Sigma[1,1]$$ is set to 1.0 but $$B$$[1,1] is set to false, $$\Sigma$$[1,1] is not exempt.

==Elements of the inverse of the mixed model coefficient matrix==
In principle {{lmt}} can generate any element of the inverse mixed model coefficient matrix. However, the user interface is currently limited to the diagonal elements for fixed factors and the diagonal blocks for random factors. These elements can either be sampled or obtained accurately via solving.
===Gibbs Sampling===
Following the approach of Harville(1999)<ref name="Harville1999" /> {{lmt}} can sample for fixed factors the diagonal elements of the inverse of the mixed model coefficient matrix, for random factors the diagonal blocks of the inverse of the coefficient matrix where the block size is determined by the dimension of the related $$\Sigma$$ matrix. The blocks are the prediction error co-variance matrices of the factor levels of correlated sub-factors. When sampling prediction error variances {{lmt}} can run many Gibbs chains in parallel allowing to exploit multi-core hardware architecture. However, it is recommended to specify not more chains than the number of available '''real''' cores excluding hyper-threading technology.
===Solving===
{{lmt}} can obtain elements of the inverse of the coefficient matrix via solving the mixed model equations. This method is currently only supported for the diagonal prediction error co-variance blocks of random factors, where the block size is determined by the dimension of the related $$\Sigma$$ matrix. For this algorithm {{lmt}} can utilize either the [[#Iterative solver]] or the [[#Direct solver]].

==Iterative inbreeding==
{{lmt}} supports the iterative calculation of inbreeding coefficients as described in VanRaden(1992)<ref name="VanRaden1992" />.

==References==
<references>
<ref name="Sorensen2002">D. Sorensen and D. Gianola; Likelihood, Bayesian, and MCMC Methods in Quantitative Genetics; 2002; 584-588</ref>
<ref name="Harville1999">David A. Harville; Use of the Gibbs sampler to invert large, possibly sparse, positive definite matrices; Linear Algebra and its Applications; 1999</ref>
<ref name="Harville2004">David A. Harville; Making REML computationally feasible for large data sets: use of the Gibbs sampler; Journal of Statistical Computation & Simulation; 2004</ref>
<ref name="Jensen1997">J. Jensen et. al.; Residual maximum likelihood estimation of (co) variance components in multivariate mixed linear models using average information; Indian Society of Agricultural Statistics; 1997</ref>
<ref name="Gilmour1995">A. Gilmour et. al.; Average information REML: an efficient algorithm for variance parameter estimation in linear mixed models; Biometrics; 1995</ref>
<ref name="Johnson1995">D.L. Johnson and R. Thompson; Restricted maximum likelihood estimation of variance components for univariate animal models using sparse matrix techniques and average information; Journal of Dairy Science; 1995</ref>
<ref name="VanRaden1992">PM VanRanden; Accounting for Inbreeding and Crossbreeding in Genetic Evaluation of Large Populations; Journal of Dairy Science; 1992</ref>
</references>

Output files

2022-09-22T10:24:35Z

127.0.0.1: /* _sigma_UPDATE.csv */

==Default output files==
===General output files===
====lmt.log====
General log file always generated. Provides information of the current state of operation.
===Operation dependent output files===
====Solving the mixed model equation system====
=====results.csv=====
The file contains the solutions for the mixed model equation system. The file has four columns:
*factor name,
*sub-factor name,
*factor level id, and
*solution.

Note that {{cc|factor name}}s are derived according to the lmt factor naming convention, and {{cc|sub-factor name}}s are user-defined and are extracted from the equation system. Further, the {{cc|factor level id}} is the original as provided by the data, pedigree, etc. For variables undergoing polynomial expansions, e.g. sub-factor {{cc|c}} in

y=x*b+age(t(co(p(1,2))))*c+id*u(v(my_var(1)))

the sub-factor name will be expanded as well to {{cc|sub-factor name_id}}, where "id" is the polynomial id. For the above example {{cc|c}} would be expanded to {{cc|c_1}} and {{cc|c_2}}.

The file has as many records the system has equations. Fixed factor levels which have been omitted due to rank deficiencies are not printed.
=====PCG solver output files=====
======so_conv.csv======
Contains the iteration statistics with columns
*iteration number
*alpha
*beta
*$$||r_i M r_i||$$, where $$M$$ is the preconditioner matrix and $$r_i=Cx_i-b$$ for a system $$Cx=b$$
*convergence criterion CD
*convergence criterion CR
*second per iteration

====Variance component estimation using Gibbs sampling====

=====<u.d. variance name>_sigma_SA.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as MC-EM-REML iterations.
Estimates for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}}, assuming 10,000 samples, a burn-in of 1,000 samples and a thinning of 50 samples, can be obtained by

<syntaxhighlight lang="R" line>
d<-as.matrix(fread("g_sigma_SA.csv")))
n<-floor(sqrt(ncol(d)*2))
gMean<-matrix(0,n,n);gSd<-gMean
gMean[upper.tri(g,diag=TRUE)]<-colMeans(d[seq(1000,nrow(d),20),]);
gSd[upper.tri(g,diag=TRUE)]<-apply(d[seq(1000,nrow(d),20),],2,sd);
</syntaxhighlight>

====Variance component estimation using MC-EM-REML====

=====mcemreml_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*seconds for the last MC-Em iteration
*seconds for solving the equation system
*seconds for sampling the traces
*convergence criterion '''cd'''

=====<u.d. variance name>_sigma_SA.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as MC-EM-REML iterations. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_SA.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d),];
</syntaxhighlight>

====Variance component estimation using AI-REML-C====

=====aic_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*iteration number
*convergence criterion '''ng'''
*convergence criterion '''cd'''
*convergence criterion '''ll'''
*log-likelihood
*Newton over-relaxation parameter
*number of Newton over-relaxation iterations
*seconds for the last AI-REML iteration

=====<u.d. variance name>_sigma_UPDATE.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as AI-REML-C iterations plus one. The row before the last contains the co-variance estimates at convergence. The last row contains the approximate standard errors of the parameter estimates. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_UPDATE.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d)-1,];
</syntaxhighlight>

Note that when restarting {{lmt}} will not overwrite this file. Instead it will append records.

===Intermediate output files===
====Files from processing pedigrees====
====="u.d. pedigree name"_sorted.csv=====
File contains a 3(ordinary pedigree) or 4(probabilistic pedigree) column matrix containing the sorted and renumbered pedigree generated from the original pedigree.
====="u.d. pedigree name"_crossref.csv=====
File contains a vector of original ids of individuals in '''"u.d. pedigree name"_sorted.csv'''. That is, the original id of individual #1 in '''"u.d. pedigree name"_sorted.csv''' is located in record 1 of this file, etc.

====="u.d. pedigree name".bin=====
Block file in binary format containing for blocks:
*a: real vector of diagonal elements of $$A$$
*ai: real vector of diagonal elements of $$A^{-1}$$
*m: real vector of mendelian sampling terms
*pe: 3 column integer matrix of the sorted and renumbered pedigree underlying $$A$$
==Requested output files==
===Files from processing pedigrees===
====Genetic group regression matrix====
lmt can write the genetic group regression matrix(aka $$Q$$) of a pedigree containing phantom parents to a user-defined file. For the necessary key string see [[Parameter_file_elements#<pedigree_name>|here]].

A $$Q$$ matrix written to {{cc|Q.coocsv}} format maybe read into R

<syntaxhighlight lang="R" line>
dim<-scan("Q.coocsv",n=2,sep=",")
Q<-matrix(0,d[1],d[2])
dat<-fread("Q.coocsv",skip=1)
Q[cbind(d$V1,d$V2)]<-d$V3
</syntaxhighlight>

===Files from building GRMs===
====Genomic relationship matrix====
lmt can write a genomic relationship matrix to a user-nominated file after it has been constructed. Supported output file formats are {{cc|csc}} and {{cc|bin}} where the latter nominates a block file in binary format. In both cases only the upper triangular in column major order is written out. The matrix maybe reconstructed in R

<syntaxhighlight lang="R" line>
d<-scan("mygrm.csv")
n<-floor(sqrt(length(d)*2))
G<-matrix(0,n,n)
G[upper.tri(G,diag=T)]<-d
</syntaxhighlight>

===Files from running AI-REML jobs===
====AI matrix, gradient vector and parameter vector====
Upon provision of the respective [[parameter_file_elements#airemlc|switch]] in the instruction file {{lmt}} writes the AI matrix, gradient vector and parameter vector to files {{cc|ai_ai.csv}}, {{cc|ai_ja.csv}} and {{cc|ai_pa.csv}}, respectively. Files {{cc|ai_ai.csv}} and {{cc|ai_ja.csv}} contain as many records as AI-REML iterations. File {{cc|ai_pa.csv}} contains contains as many records as AI-REML iterations + 1, where the first record is the parameter vector at the start.

Each row of file {{cc|ai_ai.csv}} contains the upper-triangular of the AI in column-major order. The AI matrix of say iteration 2 can be reconstructed by

<syntaxhighlight lang="R" line>
d<-fread("ai_ai.csv"))
n<-floor(sqrt(ncol(d)*2))
ai<-matrix(0,n,n);ai[upper.tri(ai,diag=TRUE)]<-d[2,];
</syntaxhighlight>

Parameter file elements

2022-08-31T23:44:20Z

127.0.0.1: /* grm name> */

Below is a list of all possible parameter file xml elements. For each element an example is provided as well as information about the element's host element, the element's type and the element's content. '''Note that all words(element names, key string words, key string variables) in bold are hard-coded, all in italic are user-defined (this does not apply to the example box)'''. The spelling of hard-coded words must be abide by, the spelling of user-defined words is user-defined.

=<'''model'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<model>
<eqn attribute="strings">
..
</eqn>
<poly attribute="strings">
..
</poly>
</model>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}compulsory
{{!}}hosts information about the equations and the polynomials.
}}

content:

*compulsory element '''<eqn attributes="strings">'''
*optional element '''<poly attributes="strings">'''
==<'''eqn'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<model>
<eqn attribute="strings">
y1=x*b1+z*u1(v(g(1))
y2=x*b2+z*u2(v(g(2))
y3=x*b3+a(t(co(p(1,2);n(k))))*c1+z*u3(v(g(3)))
</eqn>
..
</model>
</root>
</syntaxhighlight>
{{!}}'''model'''
{{!}}compulsory
{{!}}hosts information about the equations.
}}

content:

*[[linear mixed models in lmt#Model_syntax|model strings]] which are escaped from the formatting rules by adding '''attributes="strings"''' to the start tag.

==<'''poly'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<model>
<poly attribute="strings">
x^0
x^2
3*x^2+sqrt(sin(x))
</poly>
..
</model>
</root>
</syntaxhighlight>
{{!}}'''model'''
{{!}}optional
{{!}}hosts user defined polynomials and references to hard-coded polynomials. Note that there can only be one polynomial per line. Model strings will reference polynomials by their line number.
}}

content

*[[linear mixed models in lmt#Polynomials|polynomial strings]] which are escaped from the formatting rules by adding '''attributes="strings"''' to the start tag.

=<'''pedigrees'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<pedigrees>
pedigrees: a,b
...
</pedigrees>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}automatic-optional
{{!}}hosts one to several elements each containing information about a specific pedigree}}

content:
*key strings
{{tablekeys2|
{{!}}'''pedigrees'''
{{!}}'''pedigrees''': ''a,b''
{{!}}compulsory
{{!}}csv word-list
{{!}}''pedigree names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements}}
*nominated-compulsory elements
==<''pedigree name''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<pedigrees>
pedigrees: myped
..
<myped>
file: myped.csv
switch: selfing
phantomparents: 2
qfile: myq.coocsv
</myped>
..
</pedigrees>
</root>
</syntaxhighlight>
{{!}}'''pedigrees'''
{{!}}nominated-compulsory
{{!}}hosts information about a specific pedigree identified by ''pedigree name''
}}
content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''myped.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}list content determines the name of the file containing the pedigree
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''selfing'''
{{!}}optional
{{!}}csv-word-list
{{!}}'''selfing,probabilistic'''
{{!}}none
{{!}}list content determines pedigree properties.
*'''selfing''': both parents can have the same id
*'''probabilistic''': each individual can have more than 1 pair of parents
{{!}}-
{{!}}'''phantomparents'''
{{!}}'''phantomparents''': 2
{{!}}optional
{{!}}single numeric value
{{!}}positive integer
{{!}}none
{{!}}integer number determines the number of individuals at the top of the pedigree which are phantom parents
{{!}}-
{{!}}'''qfile'''
{{!}}'''qfile''': myq.coocsv
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}provides name of file to which the genetic regression matrix should be written. Supported file name suffixes are ".bin" for binary block file, ".blkcsv" for csv blockfile and ".coocsv" for csv coordinate format.
{{!}}-
{{!}}'''metafile'''
{{!}}'''metafile''': meta.csv
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}provides name of the file containing the metafounder co-variance matrix.
}}

=<'''genotypes'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<genotypes>
genotypes: a,b
...
</genotypes>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}automatic-optional
{{!}}hosts one to several elements each containing information about different sets of genotypes
}}

content:
*key strings
{{tablekeys2|
{{!}}'''genotypes'''
{{!}}'''genotypes''': ''a,b''
{{!}}compulsory
{{!}}csv word-list
{{!}}''genotype names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements
}}
*nominated-compulsory elements
==<''genotype name''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<genotypes>
genotypes: mygn
..
<mygn>
file: genotypes.txt
pedigree: myped
cross: crossref.csv
</mygn>
..
</genotypes>
</root>
</syntaxhighlight>
{{!}}'''genotypes'''
{{!}}nominated-compulsory
{{!}}hosts information about a specific set of genotypes identified by ''genotype name''
}}
content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''genotype.txt''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the genotypes
{{!}}-
{{!}}'''cross'''
{{!}}'''cross''': ''mycross.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the pedigree ids related to the genotypes
{{!}}-
{{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}optional
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree previously invoked pedigree related to the content of the cross-reference file
{{!}}-
{{!}}'''pqfile'''
{{!}}'''pqfile''': ''mypq.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the allele frequencies. Note that the file content is used as a substitute for the column means of the marker matrix. It must therefore contain 2p.
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''ignorefixed'''
{{!}}optional
{{!}}csv word-list
{{!}}'''ignorefixed,ignoremissing'''
{{!}}none
{{!}}
*ignorefixed: fixed markers are ignored '''but may lead to program crash or spurious results latter on'''
*ignoremissing: marker coded as missing(3) are set to 0.
}}

=<'''grms'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<grms>
grms: a,b
...
</grms>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}automatic-optional
{{!}}hosts one to several elements each containing information about a specific grm
}}

content:
*key strings
{{tablekeys2|
{{!}}'''grms'''
{{!}}'''grms''': ''x,y''
{{!}}compulsory
{{!}}csv word-list
{{!}}''grm names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements
}}
*nominated-compulsory elements
==<''grm name''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<grms>
grms: mygrm
..
<mygrm>
genotype: mygn
method: YA
</mygrm>
..
</genotypes>
</root>
</syntaxhighlight>
{{!}}'''grms'''
{{!}}nominated-compulsory
{{!}}hosts information about a specific grm identified by ''grm name''
}}
content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''mygrm.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the grm. mutually exclusive with keyword '''genotype'''.
{{!}}-
{{!}}'''genotype'''
{{!}}'''genotype''': ''mygn''
{{!}}compulsory
{{!}}word
{{!}}''genotype name''
{{!}}none
{{!}}content determines the genotype element to be used for building the grm. mutually exclusive with keyword '''file'''.
{{!}}-
{{!}}'''cross'''
{{!}}'''cross''': ''mycross.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the pedigree ids related to the genotypes. if this information has already been supplied to the genotypes it cannot be supplied here.
{{!}}-
{{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}optional
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree previously invoked pedigree related to the content of the cross-reference file. if this information has already been supplied to the genotypes it cannot be supplied here.
{{!}}-
{{!}}'''method'''
{{!}}'''method''':'''vr1'''
{{!}}optional
{{!}}alternative words
{{!}}'''vr1<nowiki>|</nowiki>vr2'''
{{!}}'''vr1'''
{{!}}content determines the method to be used for building a grm from genotypes
*'''vr1''': VanRaden Method 1 is used
*'''vr2''': VanRaden Method 2(method Yang) is used
{{!}}-
{{!}}'''outfile'''
{{!}}'''outfile''': ''mygrm.bin''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file where the grm should be written to. will only take effect if the grm was build from genotypes. if the genotypes had a pedigree assigned a cross-reference file will be written out as well which contains the original pedigree ids of the genotyped individuals in the order of the rows/columns of the grm. the file name of the cross-reference file is that of the grm with the prefix '''cross_'''.
}}

=<'''vars'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
vars: g,p
...
</vars>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}compulsory
{{!}}hosts one to several elements each containing information about a specific variance.
}}

content:
*key strings
{{tablekeys2|
{{!}}'''vars'''
{{!}}'''vars''': ''g,p''
{{!}}compulsory
{{!}}csv word-list
{{!}}''variance names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements
}}
*nominated-compulsory elements
*compulsory element '''<res>'''
=='''Kronecker products'''==
Variance structures below are Kronecker products $$\Gamma \otimes \Sigma$$. If no '''type''' keystring is provided this is the default.
==='''<res>'''===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
<res>
<sigma>
..
</sigma>
</res>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''vars'''
{{!}}compulsory
{{!}}hosts information about the residual variance structure.
}}

content:
*compulsory element [[#<sigma>|'''<sigma>''']]
*optional element [[#<gamma>|'''<gamma>''']]

===''<variance name>''===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
..
</sigma>
<gamma>
..
</gamma>
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''vars'''
{{!}}nominated-compulsory
{{!}}hosts information about variance structure identified by ''variance name''.
}}

content:
*compulsory element [[#<sigma>|'''<sigma>''']]
*optional element [[#<gamma>|'''<gamma>''']]

*key strings
{{tablekeys2|
1={{!}}'''type'''
{{!}}'''type''': ''kronecker''
{{!}}optional
{{!}}word
{{!}}''kronecker,snpblup_1''
{{!}}kronecker
{{!}}determines whether the variance structure deviates from a Kronecker product.
}}

===='''<sigma>'''====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
..
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''variance name''
{{!}}compulsory
{{!}}hosts information about $$\Sigma$$ as part of [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]].
}}

content:

*key strings
{{tablekeys2|
1={{!}}'''file'''
{{!}}'''file''': ''mymatrix.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the $$\Sigma$$ matrix. is mutually exclusive with '''<nowiki><matrix attributes="array"></nowiki>'''.
{{!}}-
{{!}}'''type'''
{{!}}'''type''': '''block'''
{{!}}optional
{{!}}word
{{!}}'''block'''
{{!}}none
{{!}}determines that $$\Sigma$$ is equal to [[Supported_features#Supported_variance_structures|$$\Theta$$]]
{{!}}-
{{!}}'''scale'''
{{!}}'''scale''': ''0.05''
{{!}}optional
{{!}}single numeric value
{{!}}real number>0.0
{{!}}none
{{!}}multiplies $$\Sigma$$ once by the provided value after reading.
{{!}}-
{{!}}'''priordf'''
{{!}}'''priordf''': ''10''
{{!}}optional
{{!}}single numeric value
{{!}}real number>=0.0
{{!}}0.0
{{!}}prior degree of freedom when doing Gibbs sampling
{{!}}-
{{!}}'''maskfile'''
{{!}}'''maskfile''': ''mymatrixmask.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing a T/F matrix of the same dimension as the respective $$\Sigma$$ matrix. Is mutually exclusive with '''<nowiki><maskmatrix attributes="array"></nowiki>'''.
}}

*optional element '''<matrix attributes="array">'''
=====<'''matrix attributes="array"'''>=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
<matrix attributes="array">
5.0,0.5
0.5,1.8
</matrix>
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''sigma'''
{{!}}optional
{{!}}hosts the content of a single $$\Sigma$$ matrix. Is mutually exclusive with key string '''file: '''.
}}
=====<'''maskmatrix attributes="array"'''>=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
<maskmatrix attributes="array">
T,F
F,T
</matrix>
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''sigma'''
{{!}}optional
{{!}}hosts the content of a single indicator matrix of the same dimensions as the respective $$\Sigma$$ matrix. Is mutually exclusive with key string '''maskfile: '''.
}}

===='''<gamma>'''====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
..
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''variance name''
{{!}}optional
{{!}}hosts information about $$\Gamma$$ as part of [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]]. If absent $$\Gamma$$ defaults to $$I$$.
}}

content:

*mutually exclusive elements '''<A>, <H>, <G> and <E>'''

====='''<A>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<A>
pedigree: myped
</A>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma$$ being constructed as the numerator relationship matrix A using pedigree ''pedigree name''.
}}

content:
*key strings
{{tablekeys2|
{{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}optional
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree previously invoked to be used to construct A.
{{!}}-
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''gg'''
{{!}}optional
{{!}}csv word-list
{{!}}'''gg'''
{{!}}none
{{!}}
*gg: the pedigree contains genetic groups which will be fitted as random
}}

====='''<H>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<H>
type: tblup
pedigree: myped
genotype: mygn
aweight: 0.05
switch: adjustg2a
</H>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma$$ being constructed as combined single step relationship matrix H using pedigree ''pedigree name'' and genomic information. the genomic information can be supplied
*via a grm element for single step H-BLUP models
*via a genotype element for single step T-BLUP models
Note that for '''type:tblup''' it is not necessary to have an automatic-optional [[#<grms>|<grms>]] element in the parameter file. Doing so will cause the construction and RAM-storage of $$G$$ although it is not need for building H, thus maybe leading to substantial increase in processing time and RAM demand.
}}

content:
*key strings
{{tablekeys2|
1={{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}compulsory
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree element to be used to construct H.
{{!}}-
{{!}}'''type'''
{{!}}'''type''': '''tblup'''
{{!}}optional
{{!}}word
{{!}}'''tblup<nowiki>|</nowiki>gblup'''
{{!}}'''gblup'''
{{!}}content determines the way the inverse of H is constructed.
{{!}}-
{{!}}'''grm'''
{{!}}'''grm''': ''mygrm''
{{!}}conditional-compulsory
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the grm element to be used to construct H. compulsory for '''type: hblup'''.
{{!}}-
{{!}}'''genotype'''
{{!}}'''genotype''': ''mygn''
{{!}}conditional-compulsory
{{!}}word
{{!}}''genotype name''
{{!}}none
{{!}}content determines the genotype element to be used to construct H. compulsory for '''type: tblup'''.
{{!}}-
{{!}}'''aweight'''
{{!}}'''aweight: 0.05'''
{{!}}optional
{{!}}single numeric value
{{!}}0.0<=aweight<=1.0
{{!}}0.0
{{!}}blending of $$G$$ with $$A_{gg}$$ by $$G_w=aweight\times A_{gg}+(1-aweight)\times G$$
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''adjustg2a'''
{{!}}optional
{{!}}csv word-list
{{!}}'''adjustg2a,gg,diag'''
{{!}}none
{{!}}
*adjustg2a: adjustment of $$G$$ towards $$A_{gg}$$ using method
*gg: the pedigree contains genetic groups which will be fitted as random
*diag: calculate H diagonal elements and write to file (only supported for gblup).
{{!}}-
{{!}}'''grmdadd'''
{{!}}'''grmdadd''': ''0.05''
{{!}}optional
{{!}}single numeric value
{{!}}real number >=0.0
{{!}}none
{{!}} value added to the diagonal of $$G$$ to ensure invertibility. The policy is
*if '''aweight'''>0.0, nothing will be added to the diagonals
*if '''aweight''' is not supplied or is zero:
** if '''grmdadd''' is not supplied 0.001 will be added to the diagonals
** otherwise '''grmdadd''' will be used
}}

====='''<G>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<G>
grm: mygrm
</G>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma$$ being constructed from a genomic relationsship matrix.
}}

content:
*key strings
{{tablekeys2|
1={{!}}'''grmdadd'''
{{!}}'''grmdadd''': ''0.05''
{{!}}optional
{{!}}single numeric value
{{!}}real number >=0.0
{{!}}none
{{!}} value added to the diagonal of $$G$$ to ensure invertibility.
}}

====='''<E>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<E>
file: mygamma.csv
</E>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma^{-1}$$ being uploaded from a file.
}}

content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''mygamma.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the file which contains $$\Gamma^{-1}$$.
{{!}}-
{{!}}'''type'''
{{!}}'''type''': '''dense'''
{{!}}optional
{{!}}word
{{!}}'''dense<nowiki>|</nowiki>sparse_csr_ut'''
{{!}}'''sparse_csr_ut'''
{{!}}content determines the file storage of $$\Gamma^{-1}$$
*dense: full squared symmetric matrix
*sparse_csr_ut: squared symmetric sparse upper triangular matrix in [https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_row_(CSR,_CRS_or_Yale_format) csr] format
}}

=='''snpblup1'''==

===''<variance name>''===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
genotype: mygn
aweight: 0.05
switch: adjustg2a
<sigma>
..
</sigma>
<gamma>
..
</gamma>
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''vars'''
{{!}}nominated-compulsory
{{!}}hosts information about variance structure identified by ''variance name''.
}}

content:
*compulsory element '''<sigma>'''
*compulsory element [[#<marker_sb1>|'''<marker_sb1>''']]

*key strings
{{tablekeys2|
1={{!}}'''type'''
{{!}}'''type''': ''kronecker''
{{!}}optional
{{!}}word
{{!}}''kronecker,snpblup_1''
{{!}}kronecker
{{!}}determines whether the variance structure deviates from a Kronecker product.
{{!}}-
{{!}}'''genotype'''
{{!}}'''genotype''': ''mygn''
{{!}}conditional-compulsory
{{!}}word
{{!}}''genotype name''
{{!}}none
{{!}}content determines the genotype element to be used to construct H. compulsory for '''type: tblup'''.
{{!}}-
{{!}}'''aweight'''
{{!}}'''aweight: 0.05'''
{{!}}optional
{{!}}single numeric value
{{!}}0.0<=aweight<=1.0
{{!}}0.0
{{!}}blending of $$G$$ with $$A_{gg}$$ by $$G_w=aweight\times A_{gg}+(1-aweight)\times G$$
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''adjustg2a'''
{{!}}optional
{{!}}csv word-list
{{!}}'''adjustg2a,gg,diag'''
{{!}}none
{{!}}
*adjustg2a: adjustment of $$G$$ towards $$A_{gg}$$ using method
*gg: the pedigree contains genetic groups which will be fitted as random
*diag: calculate H diagonal elements and write to file (only supported for gblup).
}}

===='''<sigma>'''====

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
<sigma>
..
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''variance name''
{{!}}compulsory
{{!}}hosts information about $$\Sigma$$ for the poly-genetic part of the variance structure.
}}

content:

see [[#<sigma>|'''<sigma''']]

===='''<marker_sb1>'''====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
..
<marker_sb1>
..
</marker_sb1>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''marker''
{{!}}compulsory
{{!}}hosts information about the co-variance between and within markers following [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]].
}}

content:

*compulsory element '''<sigma>'''
*optional element '''<gamma>'''

====='''<sigma>'''=====

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
..
<marker_sb1>
<sigma>
..
</sigma>
..
</marker_sb1>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''marker''
{{!}}compulsory
{{!}}hosts information about $$\Sigma$$ as part of [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]] for the marker part of the variance structure. Note that $$\Sigma$$ will be scaled by (1-aweight).
}}

see [[#<sigma>|'''<sigma>''']]

=<'''jobs'''>=

{{tableele2|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: solve,yh
...
</jobs>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}optional
{{!}}hosts one to several elements each containing information about a specific job
{{!}}run default job(solve) in default parameterization(default pcgiod parameterization)
}}

content:
*key strings
{{tablekeys2|
{{!}}'''jobs'''
{{!}}'''jobs''': '''solve,yhat'''
{{!}}compulsory
{{!}}csv word-list
{{!}}'''solve,sample,pevsample,mcemreml,yhat'''
{{!}}none
{{!}}job sequence is determined by the list sequence. list content determines nominated-compulsory elements
}}

*nominated-compulsory elements
**'''<default>'''
**'''<solve>'''
**'''<sample>'''
**'''<pevsample>'''
**'''<pevsolve>'''
**'''<mcemreml>'''
**'''<airemlc>'''
**'''<yhat>'''

==<'''default'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
..
<default>
conv: -18.42
</default>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''default'''
}}

content: see [[#<pcgiod>|<pcgiod>]] for a list of all possible key strings

==<'''solve'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
..
<solve>
solver: mysolver
</solve>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''solve'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''solver'''
{{!}}'''solver''': ''mysolver''
{{!}}compulsory
{{!}}word
{{!}}''solver name''
{{!}}none
{{!}}''solver name'' must be the name of a previously defined solver
}}

==<'''sample'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: sample,..
<sample>
sampler: mysampler
</sample>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''sample'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''sampler'''
{{!}}'''sampler''': ''mysampler''
{{!}}compulsory
{{!}}word
{{!}}''sampler name''
{{!}}none
{{!}}''sampler name'' must be the name of a previously defined sampler
}}

==<'''pevsample'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: pevsample,..
<pevsample>
sampler: mysampler
</pevsample>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''pevsample'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''sampler'''
{{!}}'''sampler''': ''mysampler''
{{!}}compulsory
{{!}}word
{{!}}''sampler name''
{{!}}none
{{!}}''sampler name'' must be the name of a previously defined sampler of type pev
}}

==<'''pevsolve'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: pevsolve,..
<pevsolve>
solver: mysolver
</pevsolver>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''pevsolve'''
}}

content:

*key strings
{{tablekeys2|
1={{!}}'''solver'''
{{!}}'''solver''': ''mysolver''
{{!}}compulsory
{{!}}word
{{!}}''solver name''
{{!}}none
{{!}}''solver name'' must be the name of a previously defined solver
{{!}}-
{{!}}'''factor'''
{{!}}'''factor''': ''gen''
{{!}}compulsory
{{!}}word
{{!}}''factor name''
{{!}}none
{{!}}''factor name'' must be the name of a random factor
{{!}}-
{{!}}'''levels'''
{{!}}'''levels''': ''5,10,20''
{{!}}optional
{{!}}csv integer list
{{!}}''factor level ids''
{{!}}none
{{!}}original factor level ids(.e.g. pedigree ids etc). If not supplied the prediction error co-variance blocks of all factor levels associated to the nominated factor will be calculated. Mutually exclusive with '''levelfile'''.
{{!}}-
{{!}}'''levelfile'''
{{!}}'''levelfile''': ''myfile.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}file containing original factor level ids(.e.g. pedigree ids etc). If not supplied the prediction error co-variance blocks of all factor levels associated to the nominated factor will be calculated. Mutually exclusive with '''levels'''.
{{!}}-
{{!}}'''nrhs'''
{{!}}'''nrhs''': ''50''
{{!}}optional
{{!}}integer
{{!}}''number of right-hand sides''
{{!}}1000
{{!}}number of right-hand-sides to be solved for simultaneously. Has only effect if the direct solver is used. The default may exceed the available RAM.
}}

==<'''airemlc'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: airemlc,..
<airemlc>
rounds: 50
..
</airemlc>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''airemlc'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''rounds'''
{{!}}'''rounds''': ''10''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}20
{{!}}provides the number of aireml-rounds to run
{{!}}-
{{!}}'''convtype'''
{{!}}'''convtype''': '''ng'''
{{!}}optional
{{!}}word
{{!}}'''cd<nowiki>|</nowiki>ng<nowiki>|</nowiki>ll<nowiki>|</nowiki>any<nowiki>|</nowiki>all'''
{{!}}'''cd'''
{{!}}provides the convergence criterion to use
* ll: log of relative change in log-likelihood
* ng: log of the norm of the gradient vector
* cd: log of the relative change of the parameter vector
* all: all of the above
* any: any of the above
{{!}}-
{{!}}'''convll'''
{{!}}'''convll''': ''-10.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''-6.907755''
{{!}}provides the convergence threshold for convergence criterion '''ll'''
{{!}}-
{{!}}'''convng'''
{{!}}'''convng''': ''-10.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''-16.1181''
{{!}}provides the convergence threshold for convergence criterion '''ng'''
{{!}}-
{{!}}'''convcd'''
{{!}}'''convcd''': ''-10.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''-16.1181''
{{!}}provides the convergence threshold for convergence criterion '''cd'''
{{!}}-
{{!}}'''nscale'''
{{!}}'''nscale''': ''0.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''1.0''
{{!}}scales the length of the Newton step.
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''residuals'''
{{!}}optional
{{!}}csv word-list
{{!}}any real number
{{!}}'''writeai,residuals,solutions'''
{{!}}
*'''writeai''': write ai matrix and gradient vector to files ai_ai.csv and ai_ja.csv.
*'''residuals''': after convergence write the residuals to file aic_residuals.csv
*'''solutions''': after convergence write the MME solutions to file results.csv
}}

==<'''mcemreml'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: mcemreml,..
<mcemreml>
rounds: 500
sampler: mysampler
solver: mysolver
</mcemreml>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''mcemreml'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''rounds'''
{{!}}'''rounds''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}500
{{!}}provides maximum the number of mcemreml-rounds to run
{{!}}-
{{!}}'''conv'''
{{!}}'''conv''': ''-16.21''
{{!}}optional
{{!}}numeric value
{{!}}real number
{{!}} -6.907755
{{!}}provides the convergence threshold
{{!}}-
{{!}}'''sampler'''
{{!}}'''sampler''': ''mysampler''
{{!}}compulsory
{{!}}word
{{!}}''sampler name''
{{!}}none
{{!}}''sampler name'' must be the name of a previously defined sampler
{{!}}-
{{!}}'''solver'''
{{!}}'''solver''': ''mysolver''
{{!}}compulsory
{{!}}word
{{!}}''solver name''
{{!}}none
{{!}}''solver name'' must be the name of a previously defined solver
}}

==<'''yhat'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: yhat,..
<yhat>
</yhat>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''yhat'''
}}
Currently '''yhat''' has no key strings or nested elements defined.

=<'''samplers'''>=

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,b,..
...
</samplers>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}optional
{{!}}hosts one to several elements each containing information about a specific sampler
}}

content:
*key strings
{{tablekeys2|
{{!}}'''samplers'''
{{!}}'''samplers''': ''a''
{{!}}compulsory
{{!}}csv word-list
{{!}}''sampler names''
{{!}}none
{{!}}list content determines nominated-compulsory elements
}}
*conditional-compulsory elements

==<''sampler name''>==

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
..
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}'''samplers'''
{{!}}conditional-compulsory
{{!}}hosts one of several mutually exclusive elements defining the type of sampler ''sampler name''
}}

content:
*compulsory mutually exclusive elements
**'''<singlepass>'''
**'''<blocked>'''
**'''<pev>'''

===<'''singlepass'''>===

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
<singlepass>
samples: 10000
burnin: 1000
</singlepass>
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}''sampler name''
{{!}}compulsory
{{!}}defines parameters of a sampler of type '''singlepass'''
}}

*key strings
{{tablekeys2|
{{!}}'''samples'''
{{!}}'''samples''': ''100000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the total number of samples to draw
{{!}}-
{{!}}'''burnin'''
{{!}}'''burnin''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}0
{{!}}provides the number of samples to be discarded as burnin
}}

===<'''blocked'''>===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
<blocked>
samples: 10000
burnin: 1000
</blocked>
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}''sampler name''
{{!}}compulsory
{{!}}defines parameters of a sampler of type '''blocked'''
}}

*key strings
{{tablekeys2|
{{!}}'''samples'''
{{!}}'''samples''': ''100000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the total number of samples to draw
{{!}}-
{{!}}'''burnin'''
{{!}}'''burnin''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}0
{{!}}provides the number of samples to be discarded as burnin
}}

===<'''pev'''>===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
<pev>
samples: 10000
burnin: 1000
chains: 10
</pev>
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}''sampler name''
{{!}}compulsory
{{!}}defines parameters of a sampler of type '''pev'''
}}

*key strings
{{tablekeys2|
{{!}}'''samples'''
{{!}}'''samples''': ''100000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the total number of samples to draw
{{!}}-
{{!}}'''burnin'''
{{!}}'''burnin''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}0
{{!}}provides the number of samples to be discarded as burnin
{{!}}-
{{!}}'''chains'''
{{!}}'''chains''': ''10''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}1
{{!}}provides the number of parallel chains to run
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''trace'''
{{!}}optional
{{!}}word
{{!}}'''trace'''
{{!}}none
{{!}}changes sampler from sampling prediction error variances to sampling traces required for emreml
}}

=<'''solvers'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,b,..
...
</solvers>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}optional
{{!}}hosts one to several elements each containing information about a specific solver
}}

content:
*key strings
{{tablekeys2|
{{!}}'''solvers'''
{{!}}'''solvers''': ''a''
{{!}}compulsory
{{!}}csv word-list
{{!}}''solver names''
{{!}}none
{{!}}list content determines nominated-compulsory elements
}}
*conditional-compulsory elements

==<''solver name''>==

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,..
<a>
..
</a>
</solvers>
</root>
</syntaxhighlight>
{{!}}'''solvers'''
{{!}}conditional-compulsory
{{!}}hosts one of several mutually exclusive elements defining the type of solver ''solver name''
}}

content:
*compulsory mutually exclusive elements with default element
**'''<pcgiod>''', default
**'''<direct>'''

===<'''pcgiod'''>===

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,..
<a>
<pcgiod>
rounds: 1000
conv: -20.0
</pcgiod>
</a>
</solvers>
</root>
</syntaxhighlight>
{{!}}''solver name''
{{!}}compulsory
{{!}}defines parameters of a solver of type '''pcgiod'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''rounds'''
{{!}}'''rounds''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the maximum number of rounds to run
{{!}}-
{{!}}'''conv'''
{{!}}'''conv''': ''-15.0''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}} -18.42
{{!}}provides the convergence threshold
{{!}}-
{{!}}'''convtype'''
{{!}}'''convtype''': '''cd'''
{{!}}optional
{{!}}word
{{!}}'''cr<nowiki>|</nowiki>cd'''
{{!}} '''cr'''
{{!}}provides the convergence parameter type
}}

===<'''direct'''>===

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,..
<a>
<direct>
</direct>
</a>
</solvers>
</root>
</syntaxhighlight>
{{!}}''solver name''
{{!}}compulsory
{{!}}defines parameters of a solver of type '''direct'''
}}

content: no content defined

Input files

2022-08-31T23:42:36Z

127.0.0.1: /* Allele frequency file */

lmt '''does not require''' the user to provide information about the file content. Depending on the prospective use lmt will expect a particular file content and will try to read the file accordingly. For example

*the data file is supposed to contain only real/float numbers which are transferred to integer if required,
*a file containing an ordinary pedigree is supposed to contain only integer numbers,
*a file containing a missing value indicator matrix is supposed to contain only character strings, etc.

== data file ==

{{lmt}} accepts only a single file containing the actual data. A data file in ".csv" format must follow the following formatting rules:
*file must have at least one commented line where the last commented line must containing the column names separated by comma,
*the column names
**must be alpha-numeric only
**must not be quoted
**must be unique
*below the header the data file must contain only numeric values where the decimal separator is a dot(".").
The content of a data file maybe named "mydata.csv" with three columns may look like:

#y,mu,id
25.0,1,5
33.1,1,6
36.0,1,7
28.3,1,8

== co-variance matrix file ==

A co-variance matrix files must contain a single full squared symmetric positive definite matrix. The content of a co-variance file maybe named "sigma.csv" may look like
1.5,0.8,0.1
0.8,2.1,1.1
0.1,1.1,1.9
A co-variance matrix can be checked in [https://en.wikipedia.org/wiki/R_(programming_language) R] via
<syntaxhighlight lang="R" line>
s<-as.matrix(read.table("sigma.csv",sep=","))
if(nrow(s)!=ncol(s)) stop("matrix not squared")
if(any(s[lower.tri(s)]!=t(s)[lower.tri(s)])) stop("matrix not symmetric")
if(any(diag(s)<10e-12)) stop("diagonal element near zero")
if(min(eigen(s)$values)<10e-5) stop("matrix near indefinite")
</syntaxhighlight>

== co-variance mask files ==

A co-variance mask file communicates to {{lmt}} which co-variances should remain constant when {{lmt}} is used to estimate variances. The mask file must contain characters which can be interpreted as a [https://en.wikipedia.org/wiki/Boolean_data_type boolean data type], and where "T" codes for co-variances which must remain constant and "F" codes for variances which are allowed to float. The mask file must have the same dimensions as the associated co-variance matrix. For instance the above co-variance matrix file maybe accompanied by a mask file containing
T,F,F
F,T,F
F,F,F
which communicates to {{lmt}} that the first and second diagonal element should remain at their original values.

== missing observations indicator file ==

The pattern of missing observations maybe communicated via an indicator file, where the file must contain characters which can be interpreted as a [https://en.wikipedia.org/wiki/Boolean_data_type boolean data type], and where "T" codes for an available observation and "F" codes for a missing observation. Further, similar to the data file, the missing value indicator file must contain a header with the same column names as the observation columns in the data file.

An example data file "mydata.csv"
#y1,y2,mu,id
25.0,0.0,1,5
0.0,0.8,1,6
36.0,-1.5,1,7
28.3,0.0,1,8
maybe accompanied by a missing value indicator file "mymiss.csv"
#y1,y2
T,F
F,T
T,T
T,F

== pedigree file ==

For all types of pedigree described below it is required that
*all pedigree ids are positive integer numbers not larger than 9.223372e+18(i.e. the ids must fit in a 64 bit integer)
*the pedigree is complete, that is all individuals occurring as parents must have a record as individuals,
*missing parents are coded with zero
*the pedigree must not contain cycle dependencies

It is not necessary that the pedigree is sorted or that a sorting variable(e.g. date of birth) is supplied.

=== ordinary pedigree file ===
A file containing an ordinary pedigree must have three numeric columns: individual id,first parent id, second parent id, where the number of unique ids in the first column must be equal to the row dimension of the pedigree.

For instance a file maybe called "myped.csv" may contain
1,0,0
2,0,0
3,1,2
4,1,2
5,3,4
A consistency check for that pedigree in [https://en.wikipedia.org/wiki/R_(programming_language) R] may be
<syntaxhighlight lang="R" line>
p<-read.table("myped.csv",sep=",")
colnames(p)<-c("i","s","d")
if(length(unique(p$i))!=nrow(p)) stop("ids not unique")
if(any(!(p$s[p$s!=0] %in% p$i))) stop("some sires don't have records")
if(any(!(p$d[p$d!=0] %in% p$i))) stop("some dams don't have records")
</syntaxhighlight>

=== probabilistic pedigree file ===
Probabilistic pedigrees account for the possibility that an individual originates from more than one pair of parents. That is, an ordinary pedigree is just a special case of a probabilistic pedigree with all probabilities set to 1. In a probabilistic pedigree individual may have repeated records.
A file containing an ordinary pedigree must have three numeric columns: individual id,first parent id, second parent id, parentage probability. Within individuals parentage probabilities must sum up to 1. Further, repeated records of the same individual id must be adjacent. For instance
1,0,0,1.0
2,0,0,1.0
3,1,2,1.0
4,1,2,0.5
4,0,0,0.5
5,3,4,0.1
5,1,3,0.2
5,1,4,0.2
5,1,2,0.5
A consistency check for that pedigree in [https://en.wikipedia.org/wiki/R_(programming_language) R] may be
<syntaxhighlight lang="R" line>
p<-read.table("myped.csv",sep=",")
colnames(p)<-c("i","s","d","p")
if(any(!(p$s[p$s!=0] %in% p$i))) stop("some sires don't have records")
if(any(!(p$d[p$d!=0] %in% p$i))) stop("some dams don't have records")
if(any((abs(aggregate(p$p,by=list(p$i),sum)$x-1.0)>10e-12))) stop("probabilities do not sum up")
</syntaxhighlight>

=== genetic group pedigree file ===
Ordinary and probabilistic pedigrees can contain genetic groups. {{lmt}} assumes '''one phantom parent per genetic group''' where the phantom parents must be located at the top of pedigree and must have their parents set to zero. The number of phantom parents is communicated to {{lmt}} as an extra parameter at the appropriate location in the parameter file. Adding phantom parents to a pedigree requires to shift the numbering of the original pedigree by the number of phantom parents. For example the above ordinary pedigree can be transferred into a pedigree with 2 genetic groups, and therefore 2 phantom parents:
1,0,0
2,0,0
3,1,1
4,2,2
5,3,4
6,3,4
7,5,6
where the original founder individuals 1 and 2 are now coded as 3 and 4, and are off-spring of phantom parents 1 and 2 respectively.
The genetic group methodology requires that in a genetic group pedigree the only individuals with unknown parents are the phantom parents. {{lmt}} is not enforcing this concept, that is the user may supply a genetic group pedigree where an individual has one or both parents unknown although the individual is not a phantom parent.

A consistency check for the above pedigree in [https://en.wikipedia.org/wiki/R_(programming_language) R] may be
<syntaxhighlight lang="R" line>
p<-read.table("myped.csv",sep=",")
colnames(p)<-c("i","s","d")
if(length(unique(p$i))!=nrow(p)) stop("ids not unique")
if(any(!(p$s[p$s!=0] %in% p$i))) stop("some sires don't have records")
if(any(!(p$d[p$d!=0] %in% p$i))) stop("some dams don't have records")
if(any(p[c(1:2),c("s","d")]!=0)) stop("some phantom parents have known parents")
if(any(p[-c(1:2),c("s","d")]==0)) stop("some ordinary individuals have missing parents")
</syntaxhighlight>

=== meta-founder pedigree file ===
The meta-founder concept is very similar to the genetic group concept with the phantom parents becoming meta-founders, and therefore the same format requirements as for the genetic group pedigree apply. The number of meta-founders as well as the meta-founder co-variance matrix are communicated to {{lmt}} as extra parameters at the appropriate location in the parameter file.

== Genotype cross-reference file ==
The file contains the pedigree ids of the genotyped individuals as a single column vector. The genotype file and the cross-reference file must have the same number of lines. {{lmt}} will related the individual id and the genotype via the file line number, that is the pedigree id located in line #5 of the cross-reference file is that of an individual of which genotype is located in line #5 of the genotype file.

== Genotype file ==

A genotype file must be in ascii text format where each line contains a single genotype coded 0,1 or 2 for homozygous "aa", heterozygous "Aa" and homozygous "AA", respectively. Currently, missing values are not supported. A single genotype must not contain any space. The file must have a many lines as there are genotypes and each genotype must have the same number of markers. A file containing 10 genotypes of 40 markers each maybe
0122221210011211221100021210220020021221
1211121121111120110011110201121020111111
0122211210012202222200022120220111021222
0122211210012202222200022120220111021222
0222220220020220220000020200220020022220
1111122111102111111111111211121020110112
2200022002202020000002200202022020200002
1211111121112111111111111111121111111112
2200022012202020000002200202012020200002
1211121121111120110001110201111020111111
Note that additional information about the genotypes, e.g. the pedigree ids of the related individuals, maybe supplied via an additional file.

== Allele frequency file ==

A file containing allele frequencies must be in block format and contain a single block named {{cc|FREQUENCIES}}.
As an example, for 5 markers and setting the allele frequencies to 0.5 the file content is

BEGIN FREQUENCIES
real,array,64,10
1.0
1.0
1.0
1.0
1.0
END FREQUENCIES

Note that the allele frequencies must be expressed as expected allele content(2p).
A pqfile can be generated in R by

<syntaxhighlight lang="R" line>
x=list(FREQUENCIES=rep(1,nmarker))
writelmtblockfile(x,"pq.blkcsv","txt")
</syntaxhighlight>

and providing it to {{lmt}}.

Input files

2022-08-31T23:40:22Z

127.0.0.1: /* Allele frequency file */

lmt '''does not require''' the user to provide information about the file content. Depending on the prospective use lmt will expect a particular file content and will try to read the file accordingly. For example

*the data file is supposed to contain only real/float numbers which are transferred to integer if required,
*a file containing an ordinary pedigree is supposed to contain only integer numbers,
*a file containing a missing value indicator matrix is supposed to contain only character strings, etc.

== data file ==

{{lmt}} accepts only a single file containing the actual data. A data file in ".csv" format must follow the following formatting rules:
*file must have at least one commented line where the last commented line must containing the column names separated by comma,
*the column names
**must be alpha-numeric only
**must not be quoted
**must be unique
*below the header the data file must contain only numeric values where the decimal separator is a dot(".").
The content of a data file maybe named "mydata.csv" with three columns may look like:

#y,mu,id
25.0,1,5
33.1,1,6
36.0,1,7
28.3,1,8

== co-variance matrix file ==

A co-variance matrix files must contain a single full squared symmetric positive definite matrix. The content of a co-variance file maybe named "sigma.csv" may look like
1.5,0.8,0.1
0.8,2.1,1.1
0.1,1.1,1.9
A co-variance matrix can be checked in [https://en.wikipedia.org/wiki/R_(programming_language) R] via
<syntaxhighlight lang="R" line>
s<-as.matrix(read.table("sigma.csv",sep=","))
if(nrow(s)!=ncol(s)) stop("matrix not squared")
if(any(s[lower.tri(s)]!=t(s)[lower.tri(s)])) stop("matrix not symmetric")
if(any(diag(s)<10e-12)) stop("diagonal element near zero")
if(min(eigen(s)$values)<10e-5) stop("matrix near indefinite")
</syntaxhighlight>

== co-variance mask files ==

A co-variance mask file communicates to {{lmt}} which co-variances should remain constant when {{lmt}} is used to estimate variances. The mask file must contain characters which can be interpreted as a [https://en.wikipedia.org/wiki/Boolean_data_type boolean data type], and where "T" codes for co-variances which must remain constant and "F" codes for variances which are allowed to float. The mask file must have the same dimensions as the associated co-variance matrix. For instance the above co-variance matrix file maybe accompanied by a mask file containing
T,F,F
F,T,F
F,F,F
which communicates to {{lmt}} that the first and second diagonal element should remain at their original values.

== missing observations indicator file ==

The pattern of missing observations maybe communicated via an indicator file, where the file must contain characters which can be interpreted as a [https://en.wikipedia.org/wiki/Boolean_data_type boolean data type], and where "T" codes for an available observation and "F" codes for a missing observation. Further, similar to the data file, the missing value indicator file must contain a header with the same column names as the observation columns in the data file.

An example data file "mydata.csv"
#y1,y2,mu,id
25.0,0.0,1,5
0.0,0.8,1,6
36.0,-1.5,1,7
28.3,0.0,1,8
maybe accompanied by a missing value indicator file "mymiss.csv"
#y1,y2
T,F
F,T
T,T
T,F

== pedigree file ==

For all types of pedigree described below it is required that
*all pedigree ids are positive integer numbers not larger than 9.223372e+18(i.e. the ids must fit in a 64 bit integer)
*the pedigree is complete, that is all individuals occurring as parents must have a record as individuals,
*missing parents are coded with zero
*the pedigree must not contain cycle dependencies

It is not necessary that the pedigree is sorted or that a sorting variable(e.g. date of birth) is supplied.

=== ordinary pedigree file ===
A file containing an ordinary pedigree must have three numeric columns: individual id,first parent id, second parent id, where the number of unique ids in the first column must be equal to the row dimension of the pedigree.

For instance a file maybe called "myped.csv" may contain
1,0,0
2,0,0
3,1,2
4,1,2
5,3,4
A consistency check for that pedigree in [https://en.wikipedia.org/wiki/R_(programming_language) R] may be
<syntaxhighlight lang="R" line>
p<-read.table("myped.csv",sep=",")
colnames(p)<-c("i","s","d")
if(length(unique(p$i))!=nrow(p)) stop("ids not unique")
if(any(!(p$s[p$s!=0] %in% p$i))) stop("some sires don't have records")
if(any(!(p$d[p$d!=0] %in% p$i))) stop("some dams don't have records")
</syntaxhighlight>

=== probabilistic pedigree file ===
Probabilistic pedigrees account for the possibility that an individual originates from more than one pair of parents. That is, an ordinary pedigree is just a special case of a probabilistic pedigree with all probabilities set to 1. In a probabilistic pedigree individual may have repeated records.
A file containing an ordinary pedigree must have three numeric columns: individual id,first parent id, second parent id, parentage probability. Within individuals parentage probabilities must sum up to 1. Further, repeated records of the same individual id must be adjacent. For instance
1,0,0,1.0
2,0,0,1.0
3,1,2,1.0
4,1,2,0.5
4,0,0,0.5
5,3,4,0.1
5,1,3,0.2
5,1,4,0.2
5,1,2,0.5
A consistency check for that pedigree in [https://en.wikipedia.org/wiki/R_(programming_language) R] may be
<syntaxhighlight lang="R" line>
p<-read.table("myped.csv",sep=",")
colnames(p)<-c("i","s","d","p")
if(any(!(p$s[p$s!=0] %in% p$i))) stop("some sires don't have records")
if(any(!(p$d[p$d!=0] %in% p$i))) stop("some dams don't have records")
if(any((abs(aggregate(p$p,by=list(p$i),sum)$x-1.0)>10e-12))) stop("probabilities do not sum up")
</syntaxhighlight>

=== genetic group pedigree file ===
Ordinary and probabilistic pedigrees can contain genetic groups. {{lmt}} assumes '''one phantom parent per genetic group''' where the phantom parents must be located at the top of pedigree and must have their parents set to zero. The number of phantom parents is communicated to {{lmt}} as an extra parameter at the appropriate location in the parameter file. Adding phantom parents to a pedigree requires to shift the numbering of the original pedigree by the number of phantom parents. For example the above ordinary pedigree can be transferred into a pedigree with 2 genetic groups, and therefore 2 phantom parents:
1,0,0
2,0,0
3,1,1
4,2,2
5,3,4
6,3,4
7,5,6
where the original founder individuals 1 and 2 are now coded as 3 and 4, and are off-spring of phantom parents 1 and 2 respectively.
The genetic group methodology requires that in a genetic group pedigree the only individuals with unknown parents are the phantom parents. {{lmt}} is not enforcing this concept, that is the user may supply a genetic group pedigree where an individual has one or both parents unknown although the individual is not a phantom parent.

A consistency check for the above pedigree in [https://en.wikipedia.org/wiki/R_(programming_language) R] may be
<syntaxhighlight lang="R" line>
p<-read.table("myped.csv",sep=",")
colnames(p)<-c("i","s","d")
if(length(unique(p$i))!=nrow(p)) stop("ids not unique")
if(any(!(p$s[p$s!=0] %in% p$i))) stop("some sires don't have records")
if(any(!(p$d[p$d!=0] %in% p$i))) stop("some dams don't have records")
if(any(p[c(1:2),c("s","d")]!=0)) stop("some phantom parents have known parents")
if(any(p[-c(1:2),c("s","d")]==0)) stop("some ordinary individuals have missing parents")
</syntaxhighlight>

=== meta-founder pedigree file ===
The meta-founder concept is very similar to the genetic group concept with the phantom parents becoming meta-founders, and therefore the same format requirements as for the genetic group pedigree apply. The number of meta-founders as well as the meta-founder co-variance matrix are communicated to {{lmt}} as extra parameters at the appropriate location in the parameter file.

== Genotype cross-reference file ==
The file contains the pedigree ids of the genotyped individuals as a single column vector. The genotype file and the cross-reference file must have the same number of lines. {{lmt}} will related the individual id and the genotype via the file line number, that is the pedigree id located in line #5 of the cross-reference file is that of an individual of which genotype is located in line #5 of the genotype file.

== Genotype file ==

A genotype file must be in ascii text format where each line contains a single genotype coded 0,1 or 2 for homozygous "aa", heterozygous "Aa" and homozygous "AA", respectively. Currently, missing values are not supported. A single genotype must not contain any space. The file must have a many lines as there are genotypes and each genotype must have the same number of markers. A file containing 10 genotypes of 40 markers each maybe
0122221210011211221100021210220020021221
1211121121111120110011110201121020111111
0122211210012202222200022120220111021222
0122211210012202222200022120220111021222
0222220220020220220000020200220020022220
1111122111102111111111111211121020110112
2200022002202020000002200202022020200002
1211111121112111111111111111121111111112
2200022012202020000002200202012020200002
1211121121111120110001110201111020111111
Note that additional information about the genotypes, e.g. the pedigree ids of the related individuals, maybe supplied via an additional file.

== Allele frequency file ==

A file containing allele frequencies must be in block format and contain a single block named {{cc|FREQUENCIES}}.
As an example, for 10 markers the file content is

Note that the allele frequencies must be expressed as expected allele content(2p).
As an example, setting all allele frequencies to 0.5 can be achieved by generating a pq file in R

<syntaxhighlight lang="R" line>
x=list(FREQUENCIES=rep(1,nmarker))
writelmtblockfile(x,"pq.blkcsv","txt")
</syntaxhighlight>

and providing it to {{lmt}}.

Input files

2022-08-31T23:37:45Z

127.0.0.1: /* Allele frequency file */

lmt '''does not require''' the user to provide information about the file content. Depending on the prospective use lmt will expect a particular file content and will try to read the file accordingly. For example

*the data file is supposed to contain only real/float numbers which are transferred to integer if required,
*a file containing an ordinary pedigree is supposed to contain only integer numbers,
*a file containing a missing value indicator matrix is supposed to contain only character strings, etc.

== data file ==

{{lmt}} accepts only a single file containing the actual data. A data file in ".csv" format must follow the following formatting rules:
*file must have at least one commented line where the last commented line must containing the column names separated by comma,
*the column names
**must be alpha-numeric only
**must not be quoted
**must be unique
*below the header the data file must contain only numeric values where the decimal separator is a dot(".").
The content of a data file maybe named "mydata.csv" with three columns may look like:

#y,mu,id
25.0,1,5
33.1,1,6
36.0,1,7
28.3,1,8

== co-variance matrix file ==

A co-variance matrix files must contain a single full squared symmetric positive definite matrix. The content of a co-variance file maybe named "sigma.csv" may look like
1.5,0.8,0.1
0.8,2.1,1.1
0.1,1.1,1.9
A co-variance matrix can be checked in [https://en.wikipedia.org/wiki/R_(programming_language) R] via
<syntaxhighlight lang="R" line>
s<-as.matrix(read.table("sigma.csv",sep=","))
if(nrow(s)!=ncol(s)) stop("matrix not squared")
if(any(s[lower.tri(s)]!=t(s)[lower.tri(s)])) stop("matrix not symmetric")
if(any(diag(s)<10e-12)) stop("diagonal element near zero")
if(min(eigen(s)$values)<10e-5) stop("matrix near indefinite")
</syntaxhighlight>

== co-variance mask files ==

A co-variance mask file communicates to {{lmt}} which co-variances should remain constant when {{lmt}} is used to estimate variances. The mask file must contain characters which can be interpreted as a [https://en.wikipedia.org/wiki/Boolean_data_type boolean data type], and where "T" codes for co-variances which must remain constant and "F" codes for variances which are allowed to float. The mask file must have the same dimensions as the associated co-variance matrix. For instance the above co-variance matrix file maybe accompanied by a mask file containing
T,F,F
F,T,F
F,F,F
which communicates to {{lmt}} that the first and second diagonal element should remain at their original values.

== missing observations indicator file ==

The pattern of missing observations maybe communicated via an indicator file, where the file must contain characters which can be interpreted as a [https://en.wikipedia.org/wiki/Boolean_data_type boolean data type], and where "T" codes for an available observation and "F" codes for a missing observation. Further, similar to the data file, the missing value indicator file must contain a header with the same column names as the observation columns in the data file.

An example data file "mydata.csv"
#y1,y2,mu,id
25.0,0.0,1,5
0.0,0.8,1,6
36.0,-1.5,1,7
28.3,0.0,1,8
maybe accompanied by a missing value indicator file "mymiss.csv"
#y1,y2
T,F
F,T
T,T
T,F

== pedigree file ==

For all types of pedigree described below it is required that
*all pedigree ids are positive integer numbers not larger than 9.223372e+18(i.e. the ids must fit in a 64 bit integer)
*the pedigree is complete, that is all individuals occurring as parents must have a record as individuals,
*missing parents are coded with zero
*the pedigree must not contain cycle dependencies

It is not necessary that the pedigree is sorted or that a sorting variable(e.g. date of birth) is supplied.

=== ordinary pedigree file ===
A file containing an ordinary pedigree must have three numeric columns: individual id,first parent id, second parent id, where the number of unique ids in the first column must be equal to the row dimension of the pedigree.

For instance a file maybe called "myped.csv" may contain
1,0,0
2,0,0
3,1,2
4,1,2
5,3,4
A consistency check for that pedigree in [https://en.wikipedia.org/wiki/R_(programming_language) R] may be
<syntaxhighlight lang="R" line>
p<-read.table("myped.csv",sep=",")
colnames(p)<-c("i","s","d")
if(length(unique(p$i))!=nrow(p)) stop("ids not unique")
if(any(!(p$s[p$s!=0] %in% p$i))) stop("some sires don't have records")
if(any(!(p$d[p$d!=0] %in% p$i))) stop("some dams don't have records")
</syntaxhighlight>

=== probabilistic pedigree file ===
Probabilistic pedigrees account for the possibility that an individual originates from more than one pair of parents. That is, an ordinary pedigree is just a special case of a probabilistic pedigree with all probabilities set to 1. In a probabilistic pedigree individual may have repeated records.
A file containing an ordinary pedigree must have three numeric columns: individual id,first parent id, second parent id, parentage probability. Within individuals parentage probabilities must sum up to 1. Further, repeated records of the same individual id must be adjacent. For instance
1,0,0,1.0
2,0,0,1.0
3,1,2,1.0
4,1,2,0.5
4,0,0,0.5
5,3,4,0.1
5,1,3,0.2
5,1,4,0.2
5,1,2,0.5
A consistency check for that pedigree in [https://en.wikipedia.org/wiki/R_(programming_language) R] may be
<syntaxhighlight lang="R" line>
p<-read.table("myped.csv",sep=",")
colnames(p)<-c("i","s","d","p")
if(any(!(p$s[p$s!=0] %in% p$i))) stop("some sires don't have records")
if(any(!(p$d[p$d!=0] %in% p$i))) stop("some dams don't have records")
if(any((abs(aggregate(p$p,by=list(p$i),sum)$x-1.0)>10e-12))) stop("probabilities do not sum up")
</syntaxhighlight>

=== genetic group pedigree file ===
Ordinary and probabilistic pedigrees can contain genetic groups. {{lmt}} assumes '''one phantom parent per genetic group''' where the phantom parents must be located at the top of pedigree and must have their parents set to zero. The number of phantom parents is communicated to {{lmt}} as an extra parameter at the appropriate location in the parameter file. Adding phantom parents to a pedigree requires to shift the numbering of the original pedigree by the number of phantom parents. For example the above ordinary pedigree can be transferred into a pedigree with 2 genetic groups, and therefore 2 phantom parents:
1,0,0
2,0,0
3,1,1
4,2,2
5,3,4
6,3,4
7,5,6
where the original founder individuals 1 and 2 are now coded as 3 and 4, and are off-spring of phantom parents 1 and 2 respectively.
The genetic group methodology requires that in a genetic group pedigree the only individuals with unknown parents are the phantom parents. {{lmt}} is not enforcing this concept, that is the user may supply a genetic group pedigree where an individual has one or both parents unknown although the individual is not a phantom parent.

A consistency check for the above pedigree in [https://en.wikipedia.org/wiki/R_(programming_language) R] may be
<syntaxhighlight lang="R" line>
p<-read.table("myped.csv",sep=",")
colnames(p)<-c("i","s","d")
if(length(unique(p$i))!=nrow(p)) stop("ids not unique")
if(any(!(p$s[p$s!=0] %in% p$i))) stop("some sires don't have records")
if(any(!(p$d[p$d!=0] %in% p$i))) stop("some dams don't have records")
if(any(p[c(1:2),c("s","d")]!=0)) stop("some phantom parents have known parents")
if(any(p[-c(1:2),c("s","d")]==0)) stop("some ordinary individuals have missing parents")
</syntaxhighlight>

=== meta-founder pedigree file ===
The meta-founder concept is very similar to the genetic group concept with the phantom parents becoming meta-founders, and therefore the same format requirements as for the genetic group pedigree apply. The number of meta-founders as well as the meta-founder co-variance matrix are communicated to {{lmt}} as extra parameters at the appropriate location in the parameter file.

== Genotype cross-reference file ==
The file contains the pedigree ids of the genotyped individuals as a single column vector. The genotype file and the cross-reference file must have the same number of lines. {{lmt}} will related the individual id and the genotype via the file line number, that is the pedigree id located in line #5 of the cross-reference file is that of an individual of which genotype is located in line #5 of the genotype file.

== Genotype file ==

A genotype file must be in ascii text format where each line contains a single genotype coded 0,1 or 2 for homozygous "aa", heterozygous "Aa" and homozygous "AA", respectively. Currently, missing values are not supported. A single genotype must not contain any space. The file must have a many lines as there are genotypes and each genotype must have the same number of markers. A file containing 10 genotypes of 40 markers each maybe
0122221210011211221100021210220020021221
1211121121111120110011110201121020111111
0122211210012202222200022120220111021222
0122211210012202222200022120220111021222
0222220220020220220000020200220020022220
1111122111102111111111111211121020110112
2200022002202020000002200202022020200002
1211111121112111111111111111121111111112
2200022012202020000002200202012020200002
1211121121111120110001110201111020111111
Note that additional information about the genotypes, e.g. the pedigree ids of the related individuals, maybe supplied via an additional file.

== Allele frequency file ==

A file containing allele frequencies must be in block format and contain a single block named {{cc|FREQUENCIES}}. Note that the allele frequencies must be expressed as expected allele content(2p).
As an example, setting all allele frequencies to 0.5 can be achieved by generating a pq file in R

<syntaxhighlight lang="R" line>
x=list(FREQUENCIES=rep(1,nmarker))
writelmtblockfile(x,"pq.blkcsv","txt")
</syntaxhighlight>

and providing it to {{lmt}}.

Input files

2022-08-31T23:37:14Z

127.0.0.1: /* Allele frequency file */

lmt '''does not require''' the user to provide information about the file content. Depending on the prospective use lmt will expect a particular file content and will try to read the file accordingly. For example

*the data file is supposed to contain only real/float numbers which are transferred to integer if required,
*a file containing an ordinary pedigree is supposed to contain only integer numbers,
*a file containing a missing value indicator matrix is supposed to contain only character strings, etc.

== data file ==

{{lmt}} accepts only a single file containing the actual data. A data file in ".csv" format must follow the following formatting rules:
*file must have at least one commented line where the last commented line must containing the column names separated by comma,
*the column names
**must be alpha-numeric only
**must not be quoted
**must be unique
*below the header the data file must contain only numeric values where the decimal separator is a dot(".").
The content of a data file maybe named "mydata.csv" with three columns may look like:

#y,mu,id
25.0,1,5
33.1,1,6
36.0,1,7
28.3,1,8

== co-variance matrix file ==

A co-variance matrix files must contain a single full squared symmetric positive definite matrix. The content of a co-variance file maybe named "sigma.csv" may look like
1.5,0.8,0.1
0.8,2.1,1.1
0.1,1.1,1.9
A co-variance matrix can be checked in [https://en.wikipedia.org/wiki/R_(programming_language) R] via
<syntaxhighlight lang="R" line>
s<-as.matrix(read.table("sigma.csv",sep=","))
if(nrow(s)!=ncol(s)) stop("matrix not squared")
if(any(s[lower.tri(s)]!=t(s)[lower.tri(s)])) stop("matrix not symmetric")
if(any(diag(s)<10e-12)) stop("diagonal element near zero")
if(min(eigen(s)$values)<10e-5) stop("matrix near indefinite")
</syntaxhighlight>

== co-variance mask files ==

A co-variance mask file communicates to {{lmt}} which co-variances should remain constant when {{lmt}} is used to estimate variances. The mask file must contain characters which can be interpreted as a [https://en.wikipedia.org/wiki/Boolean_data_type boolean data type], and where "T" codes for co-variances which must remain constant and "F" codes for variances which are allowed to float. The mask file must have the same dimensions as the associated co-variance matrix. For instance the above co-variance matrix file maybe accompanied by a mask file containing
T,F,F
F,T,F
F,F,F
which communicates to {{lmt}} that the first and second diagonal element should remain at their original values.

== missing observations indicator file ==

The pattern of missing observations maybe communicated via an indicator file, where the file must contain characters which can be interpreted as a [https://en.wikipedia.org/wiki/Boolean_data_type boolean data type], and where "T" codes for an available observation and "F" codes for a missing observation. Further, similar to the data file, the missing value indicator file must contain a header with the same column names as the observation columns in the data file.

An example data file "mydata.csv"
#y1,y2,mu,id
25.0,0.0,1,5
0.0,0.8,1,6
36.0,-1.5,1,7
28.3,0.0,1,8
maybe accompanied by a missing value indicator file "mymiss.csv"
#y1,y2
T,F
F,T
T,T
T,F

== pedigree file ==

For all types of pedigree described below it is required that
*all pedigree ids are positive integer numbers not larger than 9.223372e+18(i.e. the ids must fit in a 64 bit integer)
*the pedigree is complete, that is all individuals occurring as parents must have a record as individuals,
*missing parents are coded with zero
*the pedigree must not contain cycle dependencies

It is not necessary that the pedigree is sorted or that a sorting variable(e.g. date of birth) is supplied.

=== ordinary pedigree file ===
A file containing an ordinary pedigree must have three numeric columns: individual id,first parent id, second parent id, where the number of unique ids in the first column must be equal to the row dimension of the pedigree.

For instance a file maybe called "myped.csv" may contain
1,0,0
2,0,0
3,1,2
4,1,2
5,3,4
A consistency check for that pedigree in [https://en.wikipedia.org/wiki/R_(programming_language) R] may be
<syntaxhighlight lang="R" line>
p<-read.table("myped.csv",sep=",")
colnames(p)<-c("i","s","d")
if(length(unique(p$i))!=nrow(p)) stop("ids not unique")
if(any(!(p$s[p$s!=0] %in% p$i))) stop("some sires don't have records")
if(any(!(p$d[p$d!=0] %in% p$i))) stop("some dams don't have records")
</syntaxhighlight>

=== probabilistic pedigree file ===
Probabilistic pedigrees account for the possibility that an individual originates from more than one pair of parents. That is, an ordinary pedigree is just a special case of a probabilistic pedigree with all probabilities set to 1. In a probabilistic pedigree individual may have repeated records.
A file containing an ordinary pedigree must have three numeric columns: individual id,first parent id, second parent id, parentage probability. Within individuals parentage probabilities must sum up to 1. Further, repeated records of the same individual id must be adjacent. For instance
1,0,0,1.0
2,0,0,1.0
3,1,2,1.0
4,1,2,0.5
4,0,0,0.5
5,3,4,0.1
5,1,3,0.2
5,1,4,0.2
5,1,2,0.5
A consistency check for that pedigree in [https://en.wikipedia.org/wiki/R_(programming_language) R] may be
<syntaxhighlight lang="R" line>
p<-read.table("myped.csv",sep=",")
colnames(p)<-c("i","s","d","p")
if(any(!(p$s[p$s!=0] %in% p$i))) stop("some sires don't have records")
if(any(!(p$d[p$d!=0] %in% p$i))) stop("some dams don't have records")
if(any((abs(aggregate(p$p,by=list(p$i),sum)$x-1.0)>10e-12))) stop("probabilities do not sum up")
</syntaxhighlight>

=== genetic group pedigree file ===
Ordinary and probabilistic pedigrees can contain genetic groups. {{lmt}} assumes '''one phantom parent per genetic group''' where the phantom parents must be located at the top of pedigree and must have their parents set to zero. The number of phantom parents is communicated to {{lmt}} as an extra parameter at the appropriate location in the parameter file. Adding phantom parents to a pedigree requires to shift the numbering of the original pedigree by the number of phantom parents. For example the above ordinary pedigree can be transferred into a pedigree with 2 genetic groups, and therefore 2 phantom parents:
1,0,0
2,0,0
3,1,1
4,2,2
5,3,4
6,3,4
7,5,6
where the original founder individuals 1 and 2 are now coded as 3 and 4, and are off-spring of phantom parents 1 and 2 respectively.
The genetic group methodology requires that in a genetic group pedigree the only individuals with unknown parents are the phantom parents. {{lmt}} is not enforcing this concept, that is the user may supply a genetic group pedigree where an individual has one or both parents unknown although the individual is not a phantom parent.

A consistency check for the above pedigree in [https://en.wikipedia.org/wiki/R_(programming_language) R] may be
<syntaxhighlight lang="R" line>
p<-read.table("myped.csv",sep=",")
colnames(p)<-c("i","s","d")
if(length(unique(p$i))!=nrow(p)) stop("ids not unique")
if(any(!(p$s[p$s!=0] %in% p$i))) stop("some sires don't have records")
if(any(!(p$d[p$d!=0] %in% p$i))) stop("some dams don't have records")
if(any(p[c(1:2),c("s","d")]!=0)) stop("some phantom parents have known parents")
if(any(p[-c(1:2),c("s","d")]==0)) stop("some ordinary individuals have missing parents")
</syntaxhighlight>

=== meta-founder pedigree file ===
The meta-founder concept is very similar to the genetic group concept with the phantom parents becoming meta-founders, and therefore the same format requirements as for the genetic group pedigree apply. The number of meta-founders as well as the meta-founder co-variance matrix are communicated to {{lmt}} as extra parameters at the appropriate location in the parameter file.

== Genotype cross-reference file ==
The file contains the pedigree ids of the genotyped individuals as a single column vector. The genotype file and the cross-reference file must have the same number of lines. {{lmt}} will related the individual id and the genotype via the file line number, that is the pedigree id located in line #5 of the cross-reference file is that of an individual of which genotype is located in line #5 of the genotype file.

== Genotype file ==

A genotype file must be in ascii text format where each line contains a single genotype coded 0,1 or 2 for homozygous "aa", heterozygous "Aa" and homozygous "AA", respectively. Currently, missing values are not supported. A single genotype must not contain any space. The file must have a many lines as there are genotypes and each genotype must have the same number of markers. A file containing 10 genotypes of 40 markers each maybe
0122221210011211221100021210220020021221
1211121121111120110011110201121020111111
0122211210012202222200022120220111021222
0122211210012202222200022120220111021222
0222220220020220220000020200220020022220
1111122111102111111111111211121020110112
2200022002202020000002200202022020200002
1211111121112111111111111111121111111112
2200022012202020000002200202012020200002
1211121121111120110001110201111020111111
Note that additional information about the genotypes, e.g. the pedigree ids of the related individuals, maybe supplied via an additional file.

== Allele frequency file ==

A file containing allele frequencies must be in block format and contain a single block named {{cc|FREQUENCIES}}. Note that the allele frequencies must be expressed as expected allele content(2p).
As an example, setting all allele frequencies to 0.5 can be achieved by generating a pq file in R

<syntaxhighlight lang="R" line>
x=list(FREQUENCIES=rep(1,nmarker))
writelmtblockfile(x,"pq.blkcsv","txt")
</syntaxhighlight>

and providing it to {{cc|LMT}}.

Input files

2022-08-31T23:35:17Z

127.0.0.1: /* Genotype file */

lmt '''does not require''' the user to provide information about the file content. Depending on the prospective use lmt will expect a particular file content and will try to read the file accordingly. For example

*the data file is supposed to contain only real/float numbers which are transferred to integer if required,
*a file containing an ordinary pedigree is supposed to contain only integer numbers,
*a file containing a missing value indicator matrix is supposed to contain only character strings, etc.

== data file ==

{{lmt}} accepts only a single file containing the actual data. A data file in ".csv" format must follow the following formatting rules:
*file must have at least one commented line where the last commented line must containing the column names separated by comma,
*the column names
**must be alpha-numeric only
**must not be quoted
**must be unique
*below the header the data file must contain only numeric values where the decimal separator is a dot(".").
The content of a data file maybe named "mydata.csv" with three columns may look like:

#y,mu,id
25.0,1,5
33.1,1,6
36.0,1,7
28.3,1,8

== co-variance matrix file ==

A co-variance matrix files must contain a single full squared symmetric positive definite matrix. The content of a co-variance file maybe named "sigma.csv" may look like
1.5,0.8,0.1
0.8,2.1,1.1
0.1,1.1,1.9
A co-variance matrix can be checked in [https://en.wikipedia.org/wiki/R_(programming_language) R] via
<syntaxhighlight lang="R" line>
s<-as.matrix(read.table("sigma.csv",sep=","))
if(nrow(s)!=ncol(s)) stop("matrix not squared")
if(any(s[lower.tri(s)]!=t(s)[lower.tri(s)])) stop("matrix not symmetric")
if(any(diag(s)<10e-12)) stop("diagonal element near zero")
if(min(eigen(s)$values)<10e-5) stop("matrix near indefinite")
</syntaxhighlight>

== co-variance mask files ==

A co-variance mask file communicates to {{lmt}} which co-variances should remain constant when {{lmt}} is used to estimate variances. The mask file must contain characters which can be interpreted as a [https://en.wikipedia.org/wiki/Boolean_data_type boolean data type], and where "T" codes for co-variances which must remain constant and "F" codes for variances which are allowed to float. The mask file must have the same dimensions as the associated co-variance matrix. For instance the above co-variance matrix file maybe accompanied by a mask file containing
T,F,F
F,T,F
F,F,F
which communicates to {{lmt}} that the first and second diagonal element should remain at their original values.

== missing observations indicator file ==

The pattern of missing observations maybe communicated via an indicator file, where the file must contain characters which can be interpreted as a [https://en.wikipedia.org/wiki/Boolean_data_type boolean data type], and where "T" codes for an available observation and "F" codes for a missing observation. Further, similar to the data file, the missing value indicator file must contain a header with the same column names as the observation columns in the data file.

An example data file "mydata.csv"
#y1,y2,mu,id
25.0,0.0,1,5
0.0,0.8,1,6
36.0,-1.5,1,7
28.3,0.0,1,8
maybe accompanied by a missing value indicator file "mymiss.csv"
#y1,y2
T,F
F,T
T,T
T,F

== pedigree file ==

For all types of pedigree described below it is required that
*all pedigree ids are positive integer numbers not larger than 9.223372e+18(i.e. the ids must fit in a 64 bit integer)
*the pedigree is complete, that is all individuals occurring as parents must have a record as individuals,
*missing parents are coded with zero
*the pedigree must not contain cycle dependencies

It is not necessary that the pedigree is sorted or that a sorting variable(e.g. date of birth) is supplied.

=== ordinary pedigree file ===
A file containing an ordinary pedigree must have three numeric columns: individual id,first parent id, second parent id, where the number of unique ids in the first column must be equal to the row dimension of the pedigree.

For instance a file maybe called "myped.csv" may contain
1,0,0
2,0,0
3,1,2
4,1,2
5,3,4
A consistency check for that pedigree in [https://en.wikipedia.org/wiki/R_(programming_language) R] may be
<syntaxhighlight lang="R" line>
p<-read.table("myped.csv",sep=",")
colnames(p)<-c("i","s","d")
if(length(unique(p$i))!=nrow(p)) stop("ids not unique")
if(any(!(p$s[p$s!=0] %in% p$i))) stop("some sires don't have records")
if(any(!(p$d[p$d!=0] %in% p$i))) stop("some dams don't have records")
</syntaxhighlight>

=== probabilistic pedigree file ===
Probabilistic pedigrees account for the possibility that an individual originates from more than one pair of parents. That is, an ordinary pedigree is just a special case of a probabilistic pedigree with all probabilities set to 1. In a probabilistic pedigree individual may have repeated records.
A file containing an ordinary pedigree must have three numeric columns: individual id,first parent id, second parent id, parentage probability. Within individuals parentage probabilities must sum up to 1. Further, repeated records of the same individual id must be adjacent. For instance
1,0,0,1.0
2,0,0,1.0
3,1,2,1.0
4,1,2,0.5
4,0,0,0.5
5,3,4,0.1
5,1,3,0.2
5,1,4,0.2
5,1,2,0.5
A consistency check for that pedigree in [https://en.wikipedia.org/wiki/R_(programming_language) R] may be
<syntaxhighlight lang="R" line>
p<-read.table("myped.csv",sep=",")
colnames(p)<-c("i","s","d","p")
if(any(!(p$s[p$s!=0] %in% p$i))) stop("some sires don't have records")
if(any(!(p$d[p$d!=0] %in% p$i))) stop("some dams don't have records")
if(any((abs(aggregate(p$p,by=list(p$i),sum)$x-1.0)>10e-12))) stop("probabilities do not sum up")
</syntaxhighlight>

=== genetic group pedigree file ===
Ordinary and probabilistic pedigrees can contain genetic groups. {{lmt}} assumes '''one phantom parent per genetic group''' where the phantom parents must be located at the top of pedigree and must have their parents set to zero. The number of phantom parents is communicated to {{lmt}} as an extra parameter at the appropriate location in the parameter file. Adding phantom parents to a pedigree requires to shift the numbering of the original pedigree by the number of phantom parents. For example the above ordinary pedigree can be transferred into a pedigree with 2 genetic groups, and therefore 2 phantom parents:
1,0,0
2,0,0
3,1,1
4,2,2
5,3,4
6,3,4
7,5,6
where the original founder individuals 1 and 2 are now coded as 3 and 4, and are off-spring of phantom parents 1 and 2 respectively.
The genetic group methodology requires that in a genetic group pedigree the only individuals with unknown parents are the phantom parents. {{lmt}} is not enforcing this concept, that is the user may supply a genetic group pedigree where an individual has one or both parents unknown although the individual is not a phantom parent.

A consistency check for the above pedigree in [https://en.wikipedia.org/wiki/R_(programming_language) R] may be
<syntaxhighlight lang="R" line>
p<-read.table("myped.csv",sep=",")
colnames(p)<-c("i","s","d")
if(length(unique(p$i))!=nrow(p)) stop("ids not unique")
if(any(!(p$s[p$s!=0] %in% p$i))) stop("some sires don't have records")
if(any(!(p$d[p$d!=0] %in% p$i))) stop("some dams don't have records")
if(any(p[c(1:2),c("s","d")]!=0)) stop("some phantom parents have known parents")
if(any(p[-c(1:2),c("s","d")]==0)) stop("some ordinary individuals have missing parents")
</syntaxhighlight>

=== meta-founder pedigree file ===
The meta-founder concept is very similar to the genetic group concept with the phantom parents becoming meta-founders, and therefore the same format requirements as for the genetic group pedigree apply. The number of meta-founders as well as the meta-founder co-variance matrix are communicated to {{lmt}} as extra parameters at the appropriate location in the parameter file.

== Genotype cross-reference file ==
The file contains the pedigree ids of the genotyped individuals as a single column vector. The genotype file and the cross-reference file must have the same number of lines. {{lmt}} will related the individual id and the genotype via the file line number, that is the pedigree id located in line #5 of the cross-reference file is that of an individual of which genotype is located in line #5 of the genotype file.

== Genotype file ==

A genotype file must be in ascii text format where each line contains a single genotype coded 0,1 or 2 for homozygous "aa", heterozygous "Aa" and homozygous "AA", respectively. Currently, missing values are not supported. A single genotype must not contain any space. The file must have a many lines as there are genotypes and each genotype must have the same number of markers. A file containing 10 genotypes of 40 markers each maybe
0122221210011211221100021210220020021221
1211121121111120110011110201121020111111
0122211210012202222200022120220111021222
0122211210012202222200022120220111021222
0222220220020220220000020200220020022220
1111122111102111111111111211121020110112
2200022002202020000002200202022020200002
1211111121112111111111111111121111111112
2200022012202020000002200202012020200002
1211121121111120110001110201111020111111
Note that additional information about the genotypes, e.g. the pedigree ids of the related individuals, maybe supplied via an additional file.

== Allele frequency file ==

A file containing allele frequencies must be in block format and contain a single block named {{cc|FREQUENCIES}}. Note that the allele frequencies must be expressed as expected allele content(2p).
As an example, setting all allele frequencies to 0.5 can be achieved by

Output files

2022-08-28T11:24:22Z

127.0.0.1: /* Requested output files */

==Default output files==
===General output files===
====lmt.log====
General log file always generated. Provides information of the current state of operation.
===Operation dependent output files===
====Solving the mixed model equation system====
=====results.csv=====
The file contains the solutions for the mixed model equation system. The file has four columns:
*factor name,
*sub-factor name,
*factor level id, and
*solution.

Note that {{cc|factor name}}s are derived according to the lmt factor naming convention, and {{cc|sub-factor name}}s are user-defined and are extracted from the equation system. Further, the {{cc|factor level id}} is the original as provided by the data, pedigree, etc. For variables undergoing polynomial expansions, e.g. sub-factor {{cc|c}} in

y=x*b+age(t(co(p(1,2))))*c+id*u(v(my_var(1)))

the sub-factor name will be expanded as well to {{cc|sub-factor name_id}}, where "id" is the polynomial id. For the above example {{cc|c}} would be expanded to {{cc|c_1}} and {{cc|c_2}}.

The file has as many records the system has equations. Fixed factor levels which have been omitted due to rank deficiencies are not printed.
=====PCG solver output files=====
======so_conv.csv======
Contains the iteration statistics with columns
*iteration number
*alpha
*beta
*$$||r_i M r_i||$$, where $$M$$ is the preconditioner matrix and $$r_i=Cx_i-b$$ for a system $$Cx=b$$
*convergence criterion CD
*convergence criterion CR
*second per iteration

====Variance component estimation using Gibbs sampling====

=====<u.d. variance name>_sigma_SA.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as MC-EM-REML iterations.
Estimates for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}}, assuming 10,000 samples, a burn-in of 1,000 samples and a thinning of 50 samples, can be obtained by

<syntaxhighlight lang="R" line>
d<-as.matrix(fread("g_sigma_SA.csv")))
n<-floor(sqrt(ncol(d)*2))
gMean<-matrix(0,n,n);gSd<-gMean
gMean[upper.tri(g,diag=TRUE)]<-colMeans(d[seq(1000,nrow(d),20),]);
gSd[upper.tri(g,diag=TRUE)]<-apply(d[seq(1000,nrow(d),20),],2,sd);
</syntaxhighlight>

====Variance component estimation using MC-EM-REML====

=====mcemreml_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*seconds for the last MC-Em iteration
*seconds for solving the equation system
*seconds for sampling the traces
*convergence criterion '''cd'''

=====<u.d. variance name>_sigma_SA.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as MC-EM-REML iterations. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_SA.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d),];
</syntaxhighlight>

====Variance component estimation using AI-REML-C====

=====aic_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*iteration number
*convergence criterion '''ng'''
*convergence criterion '''cd'''
*convergence criterion '''ll'''
*log-likelihood
*Newton over-relaxation parameter
*number of Newton over-relaxation iterations
*seconds for the last AI-REML iteration

=====<u.d. variance name>_sigma_UPDATE.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as AI-REML-C iterations plus one. The row before the last contains the co-variance estimates at convergence. The last row contains the approximate standard errors of the parameter estimates. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_UPDATE.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d)-1,];
</syntaxhighlight>

===Intermediate output files===
====Files from processing pedigrees====
====="u.d. pedigree name"_sorted.csv=====
File contains a 3(ordinary pedigree) or 4(probabilistic pedigree) column matrix containing the sorted and renumbered pedigree generated from the original pedigree.
====="u.d. pedigree name"_crossref.csv=====
File contains a vector of original ids of individuals in '''"u.d. pedigree name"_sorted.csv'''. That is, the original id of individual #1 in '''"u.d. pedigree name"_sorted.csv''' is located in record 1 of this file, etc.

====="u.d. pedigree name".bin=====
Block file in binary format containing for blocks:
*a: real vector of diagonal elements of $$A$$
*ai: real vector of diagonal elements of $$A^{-1}$$
*m: real vector of mendelian sampling terms
*pe: 3 column integer matrix of the sorted and renumbered pedigree underlying $$A$$
==Requested output files==
===Files from processing pedigrees===
====Genetic group regression matrix====
lmt can write the genetic group regression matrix(aka $$Q$$) of a pedigree containing phantom parents to a user-defined file. For the necessary key string see [[Parameter_file_elements#<pedigree_name>|here]].

A $$Q$$ matrix written to {{cc|Q.coocsv}} format maybe read into R

<syntaxhighlight lang="R" line>
dim<-scan("Q.coocsv",n=2,sep=",")
Q<-matrix(0,d[1],d[2])
dat<-fread("Q.coocsv",skip=1)
Q[cbind(d$V1,d$V2)]<-d$V3
</syntaxhighlight>

===Files from building GRMs===
====Genomic relationship matrix====
lmt can write a genomic relationship matrix to a user-nominated file after it has been constructed. Supported output file formats are {{cc|csc}} and {{cc|bin}} where the latter nominates a block file in binary format. In both cases only the upper triangular in column major order is written out. The matrix maybe reconstructed in R

<syntaxhighlight lang="R" line>
d<-scan("mygrm.csv")
n<-floor(sqrt(length(d)*2))
G<-matrix(0,n,n)
G[upper.tri(G,diag=T)]<-d
</syntaxhighlight>

===Files from running AI-REML jobs===
====AI matrix, gradient vector and parameter vector====
Upon provision of the respective [[parameter_file_elements#airemlc|switch]] in the instruction file {{lmt}} writes the AI matrix, gradient vector and parameter vector to files {{cc|ai_ai.csv}}, {{cc|ai_ja.csv}} and {{cc|ai_pa.csv}}, respectively. Files {{cc|ai_ai.csv}} and {{cc|ai_ja.csv}} contain as many records as AI-REML iterations. File {{cc|ai_pa.csv}} contains contains as many records as AI-REML iterations + 1, where the first record is the parameter vector at the start.

Each row of file {{cc|ai_ai.csv}} contains the upper-triangular of the AI in column-major order. The AI matrix of say iteration 2 can be reconstructed by

<syntaxhighlight lang="R" line>
d<-fread("ai_ai.csv"))
n<-floor(sqrt(ncol(d)*2))
ai<-matrix(0,n,n);ai[upper.tri(ai,diag=TRUE)]<-d[2,];
</syntaxhighlight>

Examples

2022-06-07T05:04:08Z

127.0.0.1: /* Estimating variance components using AI-REML-C using single-pass Gibbs sampling to obtain starting values */

The examples provided in this section are meant to provide a practical examples about the {{lmt}} facilities and the parameter file syntax. It is assumed that the reader is familiar with [[Parameterfile1|section]]

== Solving linear mixed model equations ==

=== Estimating a mean in a uni-variate model ===

Estimating a mean is equivalent to obtaining the generalized least square solution $$b=(X'R^{-1}X)^{-1}X'R^{-1}y$$ for model $$y=Xb+e$$, where $$y$$ is a vector of $$n$$ observations, $$X$$ is as single column matrix of $$1$$, $$b$$ is a fixed factor (mean), $$e$$ is the residual and $$y\sim N(Xb,R)$$ where $$R$$ is a $$n \times n$$ co-variance matrix.

From the above it follows that for task of solving for $$b$$ {{lmt}} needs following information:

the data
the residual variance $$R$$
the model
the solver

Assume we have a data file "data.csv" with content:
#y,mu
25.0,1
33.1,1
36.0,1
28.3,1
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records.
A valid {{lmt}} xml parameter file would look like:
<syntaxhighlight lang="xml" line highlight="5,27">
<root>
<models>
<eqn attributes="strings">
y=mu*b
</eqn>
</models>
<data>
datafile: data.csv
missingthreshold: -50.0
</data>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
</vars>
</root>
</syntaxhighlight>

Following the introduced [[Parameterfile1|parameterfile terminology]] tags {{cc|<data>}}, {{cc|<vars>}} and {{cc|<model>}} are automatic-compulsory. Since {{cc|solve}} is the default job and we are using the default solver in default parameterization no further information about the job or solver is required.

The most important aspect is the model definition in tag {{cc|<eqn>}}, nested inside tag {{cc|<model>}} $$y=mu*b$$. The variable names used here are either defined by the data file header, or by the user. That is, $$y$$ and $$mu$$ are defined in the data file header, whereas $$b$$ is a user-defined factor name. Translated this means that the content of the data column named $$y$$ should be regressed on the content of the data column named $$mu$$ with the regression coefficient named $$b$$.

Since there are no further specifications supplied about $$y$$, $$mu$$ and $$b$$, it is assumed that $$y$$ is a continuous variable, $$mu$$ is a classification variable, and $$b$$ is fixed factor.
The necessary variances are defined by the content of the automatic-compulsory tag {{cc|<vars>}}. {{lmt}} requires one compulsory variance, the residual variance, which must be specified via tag {{cc|<res>}}. Therefore tag {{cc|res}} is automatic-compulsory.

The default {{lmt}} variance structure is [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Gamma$$ and $$\Sigma$$ are specified inside tags {{cc|<gamma>}} and {{cc|<sigma>}}, respectively.
However, only tag {{cc|<sigma>}} is [[Parameterfile1#Parsing logic|automatic-compulsory]], whereas tag {{cc|<gamma>}} is [[Parameterfile1#Parsing logic|automatic-optional]]. A missing {{cc|<gamma>}} tag implies that [https://en.wikipedia.org/wiki/Identity_matrix $$\Gamma = I$$]. Note that for {{lmt}} $$\Sigma$$ is always a matrix, that is a scalar $$\sigma^2$$ is treated as a matrix $$1 \times 1$$ matrix.

For the above example, the variance specification inside {{cc|<res>}} implies that $$\Gamma\otimes \Sigma \equiv I\otimes \Sigma$$. Since $$\Sigma$$ is a $$1\times 1$$ matrix with $$\Sigma[1,1]=\sigma_e^2$$, $$R$$ reduces to $$I\sigma_e^2$$.

Note tag {{cc|<matrix>}} nested in tag {{cc|<sigma>}}. The content of tag {{cc|<matrix>}} does not comply with the formatting rules as pointed o ut [[Parameterfile1#Key strings|above]]. That is {{cc|5.0}} is not a valid key string. To let {{lmt}} know that the content of tag {{cc|<matrix>}} should not be evaluated as a key string, with a subsequent error message, [[Parameterfile1#Escaping tag content formatting rules|the tag must have attributes]]. In this example {{cc|1=matrix attributes="matrix"}} escapes the content of tag {{cc|<matrix>}} from the formatting rules.

Further, tag {{cc|<matrix>}} is automatic-optional. This might be confusing because, as pointed out above, $$\Sigma$$ forms an indispensable part of $$\Gamma\otimes \Sigma$$. However, tag {{cc|<matrix>}} belongs to a [[Parameterfile1#Group of mutually exclusive information sources|group of mutually exclusive information sources]] of which members are tag {{cc|<matrix>}} and key string {{cc|file: yourfilename}}. That is, $$\Sigma$$ maybe either embedded in the parameter file or supplied via an external file.

Note that the spelling of most tags used in the above parameter file is determined by {{lmt}} and must be abide by.

=== Estimating a fixed mean and a random genetic effect in a uni-variate model ===

Consider the linear model $$y=Xb+Zu+e$$ where all variables are those declared in [[#Estimating a mean]], $$u$$ is vector of length $$m$$ of random direct genetic effects and $$Z$$ is a design matrix of dimension $$n \times m$$ linking genetic effects to their respective observations. Note that $$u\sim N(0,A\sigma_a^2)$$ where $$A$$ is the pedigree-derived relationship matrix and forms the $$\Gamma$$ part in $$\Gamma\otimes\Sigma$$. A possible data file for such mode may look like:

#y,mu,id
25.0,1,5
33.1,1,6
36.0,1,7
28.3,1,8
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records. Further assume a pedigree in a file called "ped.csv" with content:
1,0,0
2,0,0
3,1,0
4,0,2
5,3,4
6,0,4
7,5,4
8,5,7

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y = mu*b + id*u(v(my_var(1)))
</eqn>
</model>
</root>
</syntaxhighlight>

Compared with the parameter file in example [[#Estimating a mean]] the one above contains only a few extra elements. One this the automatic-optional {{cc|<pedigrees>}} nested inside tag {{cc|<root>}}. This tag contains a keystring {{cc|pedigrees: myped}}, where the user-defined variable behind {{cc|pedigrees:}} is the name of a nominated-compulsory tag nested inside tag {cc|<pedigrees>}}. This concept allows to supply several pedigrees to lmt (e.g. a normal pedigree and a genetic group pedigree). In our example we have only one pedigree named my_ped, with tag {{cc|<my_ped>}} containing the information about this pedigree. Another additional element is the key string {{cc|vars: my_var}} nested in tag {{cc|<vars>}} where the variable of key string {{cc|vars: my_var}} provides the tag names of nominated-compulsory tags, in this example tag {{cc|<my_var>}}.

Tag {{cc|<myvar>}} consist of two structural components: the automatic-compulsory tag {{cc|<sigma>}} and the automatic-optional {{cc|<gamma>}}. Since the the variance of $$u=A\sigma_a^2$$, where $$A=\Gamma$$ and $$\sigma_a^2=\Sigma$$, a {{cc|<gamma>}} tag must be supplied to fully specify the variance. '''Note that if the {{cc|<gamma>}} tag is missing or miss-spelled {{lmt}} will assume that the variance of $$u=I\sigma_a^2$$'''. Tag {{cc|<gamma>}} contains a automatic-compulsory tag {{cc|<A>}} which specifies the $$\Gamma=A$$. Since $$A$$ is build from a pedigree, tag {{cc|<A>}} contains a compulsory key string {{cc|pedigree: my_ped}} which nominates pedigree in tag {{cc|<my_ped>}} to be used for building $$A$$.

Note the difference between the tags {{cc|<sigma>}} nested in tag {{cc|<res>}} and {{cc|<my_var>}}. The former specifies {{cc|<sigma>}} to be provided by tag {{cc|1=<matrix attributes="matrix">}}, whereas the latter specifies {{cc|<sigma>}} to be provided by a file.

The model section in the above parameter file need to communicate to to {{lmt}} that $$u$$ is a random factor with a variance $$A\sigma_a^2$$. This is done by extending the u.d. factor name {{cc|u}} in {{cc|1=y = mu*b + id*u(v(my_var(1)))}} by a specifier {{cc|(v(my_var(1)))}}. Note that without a specifier {{cc|u}} would be regarded as a fixed factor. The specifier {{cc|u(v)}} communicates that {{cc|u}} has a variance assigned. Further, {{cc|v}} has a specifier assigned via {{cc|v(my_var)}} which communicates that the name of the variance is {{cc|my_var}}. The variance in tag {{cc|<my_var>}} contains a {{cc|<gamma>}} and a {{cc|<sigma>}} component. The integer number inside bracket {{cc|my_var(1)}} communicates that $$\sigma_a^2$$ of {{cc|u}} is located in the first diagonal element of $$\Sigma$$.

In summary construct {{cc|u(v(my_var(1)))}} communicates that
*{{cc|u}} has a variance assigned
*the variance is named {{cc|my_var}}
*the variance is located in the first diagonal element of the $$\Sigma$$ matrix specified in tag {{cc|<sigma>}} nested in tag {{cc|<my_var>>}}

=== Estimating fixed means and a random genetic effects in a multi-variate model ===

Consider the linear model

$$
\left(
\begin{array}{c}
y_1 \\
y_2
\end{array}
\right)=
\left(
\begin{array}{cc}
X_1 & 0 \\
0 & X_2 \\
\end{array}
\right)
\left(
\begin{array}{c}
b_1 \\
b_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
Z & 0 \\
0 & Z
\end{array}
\right)
\left(
\begin{array}{c}
u_1 \\
u_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
I & 0 \\
0 & I
\end{array}
\right)
\left(
\begin{array}{c}
e_1 \\
e_2
\end{array}
\right)
$$

where all variables are those declared in [[#Estimating a mean and a random genetic effect in a uni-variate model|above]], and subscripts $$1$$ and $$2$$ index trait $$1$$ and $$2$$, respectively.

Note that $$[u_1,u_2]\sim N([0,0],A\otimes \Sigma_a)$$ where $$A$$ is the pedigree-derived relationship matrix and
$$
\Sigma_a=
\left(\begin{array}{cc}
\sigma_{a_1}^2 & \sigma_{a_1,a_2}\\
\sigma_{a_2,a_1} & \sigma_{a_2}^2
\end{array}\right)
$$
Further, $$[e_1,e_2]\sim N([0,0],I\otimes \Sigma_e)$$ with
$$
\Sigma_e=
\left(\begin{array}{cc}
\sigma_{e_1}^2 & \sigma_{e_1,e_2}\\
\sigma_{e_2,e_1} & \sigma_{e_2}^2
\end{array}\right)
$$.

A possible data file for such mode may look like:
#y1,y2,mu,id
25.0,0.8,1,5
33.1,0.5,1,6
36.0,1.5,1,7
28.3,3.6,1,8
and the pedigree files is that provided in example [[#Estimating a mean and a random genetic effect in a uni-variate model]].

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0,0.8
0.8,1.2
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y1 = mu*b1 + id*u1(v(my_var(1)))
y2 = mu*b2 + id*u2(v(my_var(2)))
</eqn>
</model>
</root>
</syntaxhighlight>

== Example code chunks ==

'''The following code chunks are only subset of a full parameter file. It is assumed that all other parts of the instruction file are functional and all necessary input data are available and the that the data file columns have the respective names.'''

=== Providing pedigrees ===

==== Providing a pedigree containing genetic groups ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
phantomparents: 2
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a pedigree containing metafounders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
metafile: mymeta.csv
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a probabilistic pedigree ====

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<pedigrees>
pedigrees: a
<a>
switch: probabilistic
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing several pedigrees ====

<syntaxhighlight lang="xml">
<root>
...
<pedigrees>
pedigrees: a,b
<a>
...
</a>

...

</pedigrees>
...
</root>
</syntaxhighlight>

=== Providing Genotypes ===

==== Providing external allele frequencies ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
pqfile: mypq.csv 
</a>
</genotypes>
...
</root>
</syntaxhighlight>

==== Providing several genotype files ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
...
</root>
</syntaxhighlight>

=== Providing GRMs ===

==== Constructing GRM from genotypes ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Overriding the default GRM construction method ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
method: YA 
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing a GRM from file ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<grms>
grms: x
<x>
file: mygrm.csv
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing several GRMs ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
...
</root>
</syntaxhighlight>

=== Single step models ===

==== ssGBLUP model with GRM build from genotypes====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGBLUP model with GRM supplied externally ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<grms>
grms: x
<x>
file: mygrm.bin
pedigree: a
cross: id.csv
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGTBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
file: pedigree.csv
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
file: mygeno.txt
pedigree: a
cross: ids.csv
...
</a>
</genotypes>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
type: tblup
genotype: a
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssSNPBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
switch: adjustg2a
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with meta-founders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
metafile: mymeta.csv 
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
pqfile: myp.csv 
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with a separate polygenic factor ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: a,g
<a>
<sigma>
file: cov_polygenic.csv 
</sigma>
<gamma>
<A>
pedigree: a
</A>
</gamma>
</a>
<g>
type: snpblup1
genotype: a
aweight: 0.001 
switch: adjustg2a
<sigma>
file: cov_genomic.csv 
</sigma>
<marker_sb1>
<sigma>
file: cov_genomic.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*ug1(v(g(1))+dam*mg1(v(g(2))+individual*ua1(v(a(1))+dam*ma1(v(a(2))
y2=mu*b2+individual*ug2(v(g(3))+dam*mg2(v(g(4))+individual*ua2(v(a(3))+dam*ma2(v(a(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssGBLUP with two genomic factors ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a,b
<a>
...
pedigree: a
</a>

...
pedigree: a

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
<vars>
...
vars: g1,g2
<g1>
...
<gamma>
<H>
...
grm: x
</H>
</gamma>
</g1>
<g2>
...
<gamma>
<H>
...
grm: y
</H>
</gamma>
</g2>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u11(v(g1(1))+id*u21(v(g2(1))
y2=mu*b2+id*u12(v(g1(2))+id*u22(v(g2(2))
</eqn>
</models>
</root>
</syntaxhighlight>

=== Regression on continuous co-variables ===

==== Linear regression ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co))*age1
y2=mu*b2+age(t(co))*age2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== User-defined polynomial expansion ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
x^1
log(sqrt(x))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Using hard-coded Legendre polynomials ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2,3))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
l0
l1
l2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested co-variables ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
weaningweight=mu*b1+age(t(co(p(1,2);n(sex))))*age
intramuscularfatcontent=mu*b2+weight(t(co(p(1,2);n(sex))))*weight
</eqn>
<eqn attributes="strings">
x^1
x^2
</eqn>
</models>
...
</root>
</syntaxhighlight>

=== Random-regression models ===
==== Nested continuous random co-variables ====

{{cc|days}} is a co-variable which is nested within {{cc|individual}} or {{cc|dam}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(n(individual))))*u1(v(g(1))+days(t(co(n(dam))))*m1(v(g(2))
y2=mu*b2+days(t(co(n(individual))))*u2(v(g(3))+days(t(co(n(dam))))*m2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous random co-variables with polynomial expansion ====

Similar to [[#Nested continuous co-variables|Nested continuous co-variables]] but {{cc|days}} is expanded

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(p(1,2,3);n(dam))))*m1(v(g(4,5,6))
y2=mu*b2+days(t(co(p(1,2,3);n(individual))))*u2(v(g(7,8,9))+days(t(co(p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous co-variables with polynomial expansion and an integer co-variable ====

Similar to [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]], but an additional information {{cc|t(i)}} is provided telling {{lmt}} that {{cc|days}} is actually an integer. While the results do not differ from [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]] {{lmt}} can exploit this information for memory efficiency.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(t(i);p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(t(i);p(1,2,3);n(dam))))*m1(v(g(7,8,9))
y2=mu*b2+days(t(co(t(i);p(1,2,3);n(individual))))*u2(v(g(4,5,6))+days(t(co(t(i);p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials of order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
</root>
</syntaxhighlight>

=== Defining equivalent models with genetic groups ===

Note that in the parameterization provided below [[#Defining a model with absorbed genetic groups|absorbed genetic groups]] and [[#Defining a model with genetic groups as extra factor|genetic groups as extra factor]] must yield the same results. However, only when using {{cc|absorbed genetic groups}} the factor level solutions are the actual breeding values. When modelling genetic groups as an extra factor genetic factor solutions and genetic group factor solutions must be added by the user.

==== Defining a model with absorbed genetic groups ====

Note that the only information necessary is the number of phantom parents '''at the top of the pedigree'''({{cc|phantomparents: 10}}) and the information to the variance that the it should be constructed allowing for genetic groups({{cc|switch gg}}).

<syntaxhighlight lang="xml" line highlight="6,19">
<root>
<pedigrees>
pedigrees: a
<a>
file: myped.csv
phantomparents: 10
</a>
<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: a
switch: gg
</A>
</gamma>
</g>
</vars>
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Defining a model with genetic groups as extra random factor ====

Genetic groups are defined as an extra factor, which requires an extra variance({{cc|gg}}) and two pedigrees, the genetic group pedigree({{cc|a}}) and the normal pedigree({{cc|b}}). For a model equivalent to [[#Defining a model with absorbed genetic groups|absorption]] pedigree {{cc|b}} must be a subset of pedigree {{cc|a}}. Further, if breeding values are required {{lmt}} can provide the genetic group regression matrix {{cc|qfile: Q.coocsv}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g,gg
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
<gg>
<sigma>
file: myG.csv <! must contain a 4x4 matrix. should be the same as for "g">
</sigma>
</gg>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1(v(gg(1))+dam(t(gg(a)))*damgg1(v(gg(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2(v(gg(2))+dam(t(gg(a)))*damgg2(v(gg(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== Defining a model with fixed genetic groups ====

Fixed genetic groups are only supported if modeled as an extra factor. Therefore, the model is similar to [[#Defining a model with genetic groups as extra random factor|above]], but the extra variance is omitted. Note that when modeling genetic groups as fixed it is the users responsibility to omit one group from the respective pedigree to ensure that $$X$$ is of full column rank. [[#Linear models in lmt:Column rank of $$X$$|bla]]

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1+dam(t(gg(a)))*damgg1
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2+dam(t(gg(a)))*damgg2
</eqn>
</models>
</root>
</syntaxhighlight>

=== Override the default job parameters ===

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<jobs>
jobs: default
<default>
conv: -9.21 <! log(10e-5)>
</default>
</jobs>
...
</root>
</syntaxhighlight>

=== Use job "solve" instead of "default" ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>

</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Use a direct solver in stead of the default solver ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>
<direct>
</direct>
</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Estimating variance components ===
==== Gibbs sampling ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: sample
<sample>
sampler: x
</sample>
</jobs>
<samplers>
samplers: x
<x>
<blocked>
samples: 100000
</blocked>
</x>
</samplers>
...
</root>
</syntaxhighlight>

==== MC-EM-REML ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: mcemreml
<mcemreml>
conv: -9.21034
rounds: 300
sampler: x
solver: y
</mcemreml>
</jobs>
<solvers>
solvers: y
<y>
<pcgiod>
conv: -16.1181
</pcgiod>
</y>
</solvers>
<samplers>
samplers: x
<x>
<pe>
samples: 50
switch: trace
chains: 36
</pe>
</x>
</samplers>
...
</root>
</syntaxhighlight>

==== AI-REML-C ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: airemlc
<airemlc>
</airemlc>
</jobs>
...
</root>
</syntaxhighlight>

==== AI-REML-C using single-pass Gibbs sampling to obtain starting values====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: sample,airemlc
<sample>
sampler: x
</sample>
<airemlc>
</airemlc>
</jobs>
<samplers>
samplers: x
<x>
<singlepass>
samples: 200
</singlepass>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Calculating exact prediction error co-variances using a direct solver===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>
<direct>
</direct>
</a>
</solvers>
...
</root>
</syntaxhighlight>

=== Calculating prediction error co-variances for a target individual===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
levels: 1156679414 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>

</a>
</solvers>
...
</root>
</syntaxhighlight>

Examples

2022-06-07T05:03:38Z

127.0.0.1: /* Estimating variance components using AI-REML-C */

The examples provided in this section are meant to provide a practical examples about the {{lmt}} facilities and the parameter file syntax. It is assumed that the reader is familiar with [[Parameterfile1|section]]

== Solving linear mixed model equations ==

=== Estimating a mean in a uni-variate model ===

Estimating a mean is equivalent to obtaining the generalized least square solution $$b=(X'R^{-1}X)^{-1}X'R^{-1}y$$ for model $$y=Xb+e$$, where $$y$$ is a vector of $$n$$ observations, $$X$$ is as single column matrix of $$1$$, $$b$$ is a fixed factor (mean), $$e$$ is the residual and $$y\sim N(Xb,R)$$ where $$R$$ is a $$n \times n$$ co-variance matrix.

From the above it follows that for task of solving for $$b$$ {{lmt}} needs following information:

the data
the residual variance $$R$$
the model
the solver

Assume we have a data file "data.csv" with content:
#y,mu
25.0,1
33.1,1
36.0,1
28.3,1
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records.
A valid {{lmt}} xml parameter file would look like:
<syntaxhighlight lang="xml" line highlight="5,27">
<root>
<models>
<eqn attributes="strings">
y=mu*b
</eqn>
</models>
<data>
datafile: data.csv
missingthreshold: -50.0
</data>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
</vars>
</root>
</syntaxhighlight>

Following the introduced [[Parameterfile1|parameterfile terminology]] tags {{cc|<data>}}, {{cc|<vars>}} and {{cc|<model>}} are automatic-compulsory. Since {{cc|solve}} is the default job and we are using the default solver in default parameterization no further information about the job or solver is required.

The most important aspect is the model definition in tag {{cc|<eqn>}}, nested inside tag {{cc|<model>}} $$y=mu*b$$. The variable names used here are either defined by the data file header, or by the user. That is, $$y$$ and $$mu$$ are defined in the data file header, whereas $$b$$ is a user-defined factor name. Translated this means that the content of the data column named $$y$$ should be regressed on the content of the data column named $$mu$$ with the regression coefficient named $$b$$.

Since there are no further specifications supplied about $$y$$, $$mu$$ and $$b$$, it is assumed that $$y$$ is a continuous variable, $$mu$$ is a classification variable, and $$b$$ is fixed factor.
The necessary variances are defined by the content of the automatic-compulsory tag {{cc|<vars>}}. {{lmt}} requires one compulsory variance, the residual variance, which must be specified via tag {{cc|<res>}}. Therefore tag {{cc|res}} is automatic-compulsory.

The default {{lmt}} variance structure is [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Gamma$$ and $$\Sigma$$ are specified inside tags {{cc|<gamma>}} and {{cc|<sigma>}}, respectively.
However, only tag {{cc|<sigma>}} is [[Parameterfile1#Parsing logic|automatic-compulsory]], whereas tag {{cc|<gamma>}} is [[Parameterfile1#Parsing logic|automatic-optional]]. A missing {{cc|<gamma>}} tag implies that [https://en.wikipedia.org/wiki/Identity_matrix $$\Gamma = I$$]. Note that for {{lmt}} $$\Sigma$$ is always a matrix, that is a scalar $$\sigma^2$$ is treated as a matrix $$1 \times 1$$ matrix.

For the above example, the variance specification inside {{cc|<res>}} implies that $$\Gamma\otimes \Sigma \equiv I\otimes \Sigma$$. Since $$\Sigma$$ is a $$1\times 1$$ matrix with $$\Sigma[1,1]=\sigma_e^2$$, $$R$$ reduces to $$I\sigma_e^2$$.

Note tag {{cc|<matrix>}} nested in tag {{cc|<sigma>}}. The content of tag {{cc|<matrix>}} does not comply with the formatting rules as pointed o ut [[Parameterfile1#Key strings|above]]. That is {{cc|5.0}} is not a valid key string. To let {{lmt}} know that the content of tag {{cc|<matrix>}} should not be evaluated as a key string, with a subsequent error message, [[Parameterfile1#Escaping tag content formatting rules|the tag must have attributes]]. In this example {{cc|1=matrix attributes="matrix"}} escapes the content of tag {{cc|<matrix>}} from the formatting rules.

Further, tag {{cc|<matrix>}} is automatic-optional. This might be confusing because, as pointed out above, $$\Sigma$$ forms an indispensable part of $$\Gamma\otimes \Sigma$$. However, tag {{cc|<matrix>}} belongs to a [[Parameterfile1#Group of mutually exclusive information sources|group of mutually exclusive information sources]] of which members are tag {{cc|<matrix>}} and key string {{cc|file: yourfilename}}. That is, $$\Sigma$$ maybe either embedded in the parameter file or supplied via an external file.

Note that the spelling of most tags used in the above parameter file is determined by {{lmt}} and must be abide by.

=== Estimating a fixed mean and a random genetic effect in a uni-variate model ===

Consider the linear model $$y=Xb+Zu+e$$ where all variables are those declared in [[#Estimating a mean]], $$u$$ is vector of length $$m$$ of random direct genetic effects and $$Z$$ is a design matrix of dimension $$n \times m$$ linking genetic effects to their respective observations. Note that $$u\sim N(0,A\sigma_a^2)$$ where $$A$$ is the pedigree-derived relationship matrix and forms the $$\Gamma$$ part in $$\Gamma\otimes\Sigma$$. A possible data file for such mode may look like:

#y,mu,id
25.0,1,5
33.1,1,6
36.0,1,7
28.3,1,8
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records. Further assume a pedigree in a file called "ped.csv" with content:
1,0,0
2,0,0
3,1,0
4,0,2
5,3,4
6,0,4
7,5,4
8,5,7

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y = mu*b + id*u(v(my_var(1)))
</eqn>
</model>
</root>
</syntaxhighlight>

Compared with the parameter file in example [[#Estimating a mean]] the one above contains only a few extra elements. One this the automatic-optional {{cc|<pedigrees>}} nested inside tag {{cc|<root>}}. This tag contains a keystring {{cc|pedigrees: myped}}, where the user-defined variable behind {{cc|pedigrees:}} is the name of a nominated-compulsory tag nested inside tag {cc|<pedigrees>}}. This concept allows to supply several pedigrees to lmt (e.g. a normal pedigree and a genetic group pedigree). In our example we have only one pedigree named my_ped, with tag {{cc|<my_ped>}} containing the information about this pedigree. Another additional element is the key string {{cc|vars: my_var}} nested in tag {{cc|<vars>}} where the variable of key string {{cc|vars: my_var}} provides the tag names of nominated-compulsory tags, in this example tag {{cc|<my_var>}}.

Tag {{cc|<myvar>}} consist of two structural components: the automatic-compulsory tag {{cc|<sigma>}} and the automatic-optional {{cc|<gamma>}}. Since the the variance of $$u=A\sigma_a^2$$, where $$A=\Gamma$$ and $$\sigma_a^2=\Sigma$$, a {{cc|<gamma>}} tag must be supplied to fully specify the variance. '''Note that if the {{cc|<gamma>}} tag is missing or miss-spelled {{lmt}} will assume that the variance of $$u=I\sigma_a^2$$'''. Tag {{cc|<gamma>}} contains a automatic-compulsory tag {{cc|<A>}} which specifies the $$\Gamma=A$$. Since $$A$$ is build from a pedigree, tag {{cc|<A>}} contains a compulsory key string {{cc|pedigree: my_ped}} which nominates pedigree in tag {{cc|<my_ped>}} to be used for building $$A$$.

Note the difference between the tags {{cc|<sigma>}} nested in tag {{cc|<res>}} and {{cc|<my_var>}}. The former specifies {{cc|<sigma>}} to be provided by tag {{cc|1=<matrix attributes="matrix">}}, whereas the latter specifies {{cc|<sigma>}} to be provided by a file.

The model section in the above parameter file need to communicate to to {{lmt}} that $$u$$ is a random factor with a variance $$A\sigma_a^2$$. This is done by extending the u.d. factor name {{cc|u}} in {{cc|1=y = mu*b + id*u(v(my_var(1)))}} by a specifier {{cc|(v(my_var(1)))}}. Note that without a specifier {{cc|u}} would be regarded as a fixed factor. The specifier {{cc|u(v)}} communicates that {{cc|u}} has a variance assigned. Further, {{cc|v}} has a specifier assigned via {{cc|v(my_var)}} which communicates that the name of the variance is {{cc|my_var}}. The variance in tag {{cc|<my_var>}} contains a {{cc|<gamma>}} and a {{cc|<sigma>}} component. The integer number inside bracket {{cc|my_var(1)}} communicates that $$\sigma_a^2$$ of {{cc|u}} is located in the first diagonal element of $$\Sigma$$.

In summary construct {{cc|u(v(my_var(1)))}} communicates that
*{{cc|u}} has a variance assigned
*the variance is named {{cc|my_var}}
*the variance is located in the first diagonal element of the $$\Sigma$$ matrix specified in tag {{cc|<sigma>}} nested in tag {{cc|<my_var>>}}

=== Estimating fixed means and a random genetic effects in a multi-variate model ===

Consider the linear model

$$
\left(
\begin{array}{c}
y_1 \\
y_2
\end{array}
\right)=
\left(
\begin{array}{cc}
X_1 & 0 \\
0 & X_2 \\
\end{array}
\right)
\left(
\begin{array}{c}
b_1 \\
b_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
Z & 0 \\
0 & Z
\end{array}
\right)
\left(
\begin{array}{c}
u_1 \\
u_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
I & 0 \\
0 & I
\end{array}
\right)
\left(
\begin{array}{c}
e_1 \\
e_2
\end{array}
\right)
$$

where all variables are those declared in [[#Estimating a mean and a random genetic effect in a uni-variate model|above]], and subscripts $$1$$ and $$2$$ index trait $$1$$ and $$2$$, respectively.

Note that $$[u_1,u_2]\sim N([0,0],A\otimes \Sigma_a)$$ where $$A$$ is the pedigree-derived relationship matrix and
$$
\Sigma_a=
\left(\begin{array}{cc}
\sigma_{a_1}^2 & \sigma_{a_1,a_2}\\
\sigma_{a_2,a_1} & \sigma_{a_2}^2
\end{array}\right)
$$
Further, $$[e_1,e_2]\sim N([0,0],I\otimes \Sigma_e)$$ with
$$
\Sigma_e=
\left(\begin{array}{cc}
\sigma_{e_1}^2 & \sigma_{e_1,e_2}\\
\sigma_{e_2,e_1} & \sigma_{e_2}^2
\end{array}\right)
$$.

A possible data file for such mode may look like:
#y1,y2,mu,id
25.0,0.8,1,5
33.1,0.5,1,6
36.0,1.5,1,7
28.3,3.6,1,8
and the pedigree files is that provided in example [[#Estimating a mean and a random genetic effect in a uni-variate model]].

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0,0.8
0.8,1.2
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y1 = mu*b1 + id*u1(v(my_var(1)))
y2 = mu*b2 + id*u2(v(my_var(2)))
</eqn>
</model>
</root>
</syntaxhighlight>

== Example code chunks ==

'''The following code chunks are only subset of a full parameter file. It is assumed that all other parts of the instruction file are functional and all necessary input data are available and the that the data file columns have the respective names.'''

=== Providing pedigrees ===

==== Providing a pedigree containing genetic groups ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
phantomparents: 2
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a pedigree containing metafounders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
metafile: mymeta.csv
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a probabilistic pedigree ====

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<pedigrees>
pedigrees: a
<a>
switch: probabilistic
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing several pedigrees ====

<syntaxhighlight lang="xml">
<root>
...
<pedigrees>
pedigrees: a,b
<a>
...
</a>

...

</pedigrees>
...
</root>
</syntaxhighlight>

=== Providing Genotypes ===

==== Providing external allele frequencies ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
pqfile: mypq.csv 
</a>
</genotypes>
...
</root>
</syntaxhighlight>

==== Providing several genotype files ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
...
</root>
</syntaxhighlight>

=== Providing GRMs ===

==== Constructing GRM from genotypes ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Overriding the default GRM construction method ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
method: YA 
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing a GRM from file ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<grms>
grms: x
<x>
file: mygrm.csv
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing several GRMs ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
...
</root>
</syntaxhighlight>

=== Single step models ===

==== ssGBLUP model with GRM build from genotypes====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGBLUP model with GRM supplied externally ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<grms>
grms: x
<x>
file: mygrm.bin
pedigree: a
cross: id.csv
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGTBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
file: pedigree.csv
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
file: mygeno.txt
pedigree: a
cross: ids.csv
...
</a>
</genotypes>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
type: tblup
genotype: a
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssSNPBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
switch: adjustg2a
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with meta-founders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
metafile: mymeta.csv 
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
pqfile: myp.csv 
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with a separate polygenic factor ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: a,g
<a>
<sigma>
file: cov_polygenic.csv 
</sigma>
<gamma>
<A>
pedigree: a
</A>
</gamma>
</a>
<g>
type: snpblup1
genotype: a
aweight: 0.001 
switch: adjustg2a
<sigma>
file: cov_genomic.csv 
</sigma>
<marker_sb1>
<sigma>
file: cov_genomic.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*ug1(v(g(1))+dam*mg1(v(g(2))+individual*ua1(v(a(1))+dam*ma1(v(a(2))
y2=mu*b2+individual*ug2(v(g(3))+dam*mg2(v(g(4))+individual*ua2(v(a(3))+dam*ma2(v(a(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssGBLUP with two genomic factors ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a,b
<a>
...
pedigree: a
</a>

...
pedigree: a

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
<vars>
...
vars: g1,g2
<g1>
...
<gamma>
<H>
...
grm: x
</H>
</gamma>
</g1>
<g2>
...
<gamma>
<H>
...
grm: y
</H>
</gamma>
</g2>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u11(v(g1(1))+id*u21(v(g2(1))
y2=mu*b2+id*u12(v(g1(2))+id*u22(v(g2(2))
</eqn>
</models>
</root>
</syntaxhighlight>

=== Regression on continuous co-variables ===

==== Linear regression ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co))*age1
y2=mu*b2+age(t(co))*age2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== User-defined polynomial expansion ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
x^1
log(sqrt(x))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Using hard-coded Legendre polynomials ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2,3))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
l0
l1
l2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested co-variables ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
weaningweight=mu*b1+age(t(co(p(1,2);n(sex))))*age
intramuscularfatcontent=mu*b2+weight(t(co(p(1,2);n(sex))))*weight
</eqn>
<eqn attributes="strings">
x^1
x^2
</eqn>
</models>
...
</root>
</syntaxhighlight>

=== Random-regression models ===
==== Nested continuous random co-variables ====

{{cc|days}} is a co-variable which is nested within {{cc|individual}} or {{cc|dam}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(n(individual))))*u1(v(g(1))+days(t(co(n(dam))))*m1(v(g(2))
y2=mu*b2+days(t(co(n(individual))))*u2(v(g(3))+days(t(co(n(dam))))*m2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous random co-variables with polynomial expansion ====

Similar to [[#Nested continuous co-variables|Nested continuous co-variables]] but {{cc|days}} is expanded

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(p(1,2,3);n(dam))))*m1(v(g(4,5,6))
y2=mu*b2+days(t(co(p(1,2,3);n(individual))))*u2(v(g(7,8,9))+days(t(co(p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous co-variables with polynomial expansion and an integer co-variable ====

Similar to [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]], but an additional information {{cc|t(i)}} is provided telling {{lmt}} that {{cc|days}} is actually an integer. While the results do not differ from [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]] {{lmt}} can exploit this information for memory efficiency.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(t(i);p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(t(i);p(1,2,3);n(dam))))*m1(v(g(7,8,9))
y2=mu*b2+days(t(co(t(i);p(1,2,3);n(individual))))*u2(v(g(4,5,6))+days(t(co(t(i);p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials of order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
</root>
</syntaxhighlight>

=== Defining equivalent models with genetic groups ===

Note that in the parameterization provided below [[#Defining a model with absorbed genetic groups|absorbed genetic groups]] and [[#Defining a model with genetic groups as extra factor|genetic groups as extra factor]] must yield the same results. However, only when using {{cc|absorbed genetic groups}} the factor level solutions are the actual breeding values. When modelling genetic groups as an extra factor genetic factor solutions and genetic group factor solutions must be added by the user.

==== Defining a model with absorbed genetic groups ====

Note that the only information necessary is the number of phantom parents '''at the top of the pedigree'''({{cc|phantomparents: 10}}) and the information to the variance that the it should be constructed allowing for genetic groups({{cc|switch gg}}).

<syntaxhighlight lang="xml" line highlight="6,19">
<root>
<pedigrees>
pedigrees: a
<a>
file: myped.csv
phantomparents: 10
</a>
<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: a
switch: gg
</A>
</gamma>
</g>
</vars>
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Defining a model with genetic groups as extra random factor ====

Genetic groups are defined as an extra factor, which requires an extra variance({{cc|gg}}) and two pedigrees, the genetic group pedigree({{cc|a}}) and the normal pedigree({{cc|b}}). For a model equivalent to [[#Defining a model with absorbed genetic groups|absorption]] pedigree {{cc|b}} must be a subset of pedigree {{cc|a}}. Further, if breeding values are required {{lmt}} can provide the genetic group regression matrix {{cc|qfile: Q.coocsv}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g,gg
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
<gg>
<sigma>
file: myG.csv <! must contain a 4x4 matrix. should be the same as for "g">
</sigma>
</gg>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1(v(gg(1))+dam(t(gg(a)))*damgg1(v(gg(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2(v(gg(2))+dam(t(gg(a)))*damgg2(v(gg(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== Defining a model with fixed genetic groups ====

Fixed genetic groups are only supported if modeled as an extra factor. Therefore, the model is similar to [[#Defining a model with genetic groups as extra random factor|above]], but the extra variance is omitted. Note that when modeling genetic groups as fixed it is the users responsibility to omit one group from the respective pedigree to ensure that $$X$$ is of full column rank. [[#Linear models in lmt:Column rank of $$X$$|bla]]

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1+dam(t(gg(a)))*damgg1
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2+dam(t(gg(a)))*damgg2
</eqn>
</models>
</root>
</syntaxhighlight>

=== Override the default job parameters ===

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<jobs>
jobs: default
<default>
conv: -9.21 <! log(10e-5)>
</default>
</jobs>
...
</root>
</syntaxhighlight>

=== Use job "solve" instead of "default" ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>

</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Use a direct solver in stead of the default solver ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>
<direct>
</direct>
</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Estimating variance components ===
==== Gibbs sampling ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: sample
<sample>
sampler: x
</sample>
</jobs>
<samplers>
samplers: x
<x>
<blocked>
samples: 100000
</blocked>
</x>
</samplers>
...
</root>
</syntaxhighlight>

==== MC-EM-REML ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: mcemreml
<mcemreml>
conv: -9.21034
rounds: 300
sampler: x
solver: y
</mcemreml>
</jobs>
<solvers>
solvers: y
<y>
<pcgiod>
conv: -16.1181
</pcgiod>
</y>
</solvers>
<samplers>
samplers: x
<x>
<pe>
samples: 50
switch: trace
chains: 36
</pe>
</x>
</samplers>
...
</root>
</syntaxhighlight>

==== AI-REML-C ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: airemlc
<airemlc>
</airemlc>
</jobs>
...
</root>
</syntaxhighlight>

=== Estimating variance components using AI-REML-C using single-pass Gibbs sampling to obtain starting values===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: sample,airemlc
<sample>
sampler: x
</sample>
<airemlc>
</airemlc>
</jobs>
<samplers>
samplers: x
<x>
<singlepass>
samples: 200
</singlepass>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Calculating exact prediction error co-variances using a direct solver===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>
<direct>
</direct>
</a>
</solvers>
...
</root>
</syntaxhighlight>

=== Calculating prediction error co-variances for a target individual===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
levels: 1156679414 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>

</a>
</solvers>
...
</root>
</syntaxhighlight>

Examples

2022-06-07T05:03:01Z

127.0.0.1: /* Estimating variance components using MC-EM-REML */

The examples provided in this section are meant to provide a practical examples about the {{lmt}} facilities and the parameter file syntax. It is assumed that the reader is familiar with [[Parameterfile1|section]]

== Solving linear mixed model equations ==

=== Estimating a mean in a uni-variate model ===

Estimating a mean is equivalent to obtaining the generalized least square solution $$b=(X'R^{-1}X)^{-1}X'R^{-1}y$$ for model $$y=Xb+e$$, where $$y$$ is a vector of $$n$$ observations, $$X$$ is as single column matrix of $$1$$, $$b$$ is a fixed factor (mean), $$e$$ is the residual and $$y\sim N(Xb,R)$$ where $$R$$ is a $$n \times n$$ co-variance matrix.

From the above it follows that for task of solving for $$b$$ {{lmt}} needs following information:

the data
the residual variance $$R$$
the model
the solver

Assume we have a data file "data.csv" with content:
#y,mu
25.0,1
33.1,1
36.0,1
28.3,1
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records.
A valid {{lmt}} xml parameter file would look like:
<syntaxhighlight lang="xml" line highlight="5,27">
<root>
<models>
<eqn attributes="strings">
y=mu*b
</eqn>
</models>
<data>
datafile: data.csv
missingthreshold: -50.0
</data>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
</vars>
</root>
</syntaxhighlight>

Following the introduced [[Parameterfile1|parameterfile terminology]] tags {{cc|<data>}}, {{cc|<vars>}} and {{cc|<model>}} are automatic-compulsory. Since {{cc|solve}} is the default job and we are using the default solver in default parameterization no further information about the job or solver is required.

The most important aspect is the model definition in tag {{cc|<eqn>}}, nested inside tag {{cc|<model>}} $$y=mu*b$$. The variable names used here are either defined by the data file header, or by the user. That is, $$y$$ and $$mu$$ are defined in the data file header, whereas $$b$$ is a user-defined factor name. Translated this means that the content of the data column named $$y$$ should be regressed on the content of the data column named $$mu$$ with the regression coefficient named $$b$$.

Since there are no further specifications supplied about $$y$$, $$mu$$ and $$b$$, it is assumed that $$y$$ is a continuous variable, $$mu$$ is a classification variable, and $$b$$ is fixed factor.
The necessary variances are defined by the content of the automatic-compulsory tag {{cc|<vars>}}. {{lmt}} requires one compulsory variance, the residual variance, which must be specified via tag {{cc|<res>}}. Therefore tag {{cc|res}} is automatic-compulsory.

The default {{lmt}} variance structure is [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Gamma$$ and $$\Sigma$$ are specified inside tags {{cc|<gamma>}} and {{cc|<sigma>}}, respectively.
However, only tag {{cc|<sigma>}} is [[Parameterfile1#Parsing logic|automatic-compulsory]], whereas tag {{cc|<gamma>}} is [[Parameterfile1#Parsing logic|automatic-optional]]. A missing {{cc|<gamma>}} tag implies that [https://en.wikipedia.org/wiki/Identity_matrix $$\Gamma = I$$]. Note that for {{lmt}} $$\Sigma$$ is always a matrix, that is a scalar $$\sigma^2$$ is treated as a matrix $$1 \times 1$$ matrix.

For the above example, the variance specification inside {{cc|<res>}} implies that $$\Gamma\otimes \Sigma \equiv I\otimes \Sigma$$. Since $$\Sigma$$ is a $$1\times 1$$ matrix with $$\Sigma[1,1]=\sigma_e^2$$, $$R$$ reduces to $$I\sigma_e^2$$.

Note tag {{cc|<matrix>}} nested in tag {{cc|<sigma>}}. The content of tag {{cc|<matrix>}} does not comply with the formatting rules as pointed o ut [[Parameterfile1#Key strings|above]]. That is {{cc|5.0}} is not a valid key string. To let {{lmt}} know that the content of tag {{cc|<matrix>}} should not be evaluated as a key string, with a subsequent error message, [[Parameterfile1#Escaping tag content formatting rules|the tag must have attributes]]. In this example {{cc|1=matrix attributes="matrix"}} escapes the content of tag {{cc|<matrix>}} from the formatting rules.

Further, tag {{cc|<matrix>}} is automatic-optional. This might be confusing because, as pointed out above, $$\Sigma$$ forms an indispensable part of $$\Gamma\otimes \Sigma$$. However, tag {{cc|<matrix>}} belongs to a [[Parameterfile1#Group of mutually exclusive information sources|group of mutually exclusive information sources]] of which members are tag {{cc|<matrix>}} and key string {{cc|file: yourfilename}}. That is, $$\Sigma$$ maybe either embedded in the parameter file or supplied via an external file.

Note that the spelling of most tags used in the above parameter file is determined by {{lmt}} and must be abide by.

=== Estimating a fixed mean and a random genetic effect in a uni-variate model ===

Consider the linear model $$y=Xb+Zu+e$$ where all variables are those declared in [[#Estimating a mean]], $$u$$ is vector of length $$m$$ of random direct genetic effects and $$Z$$ is a design matrix of dimension $$n \times m$$ linking genetic effects to their respective observations. Note that $$u\sim N(0,A\sigma_a^2)$$ where $$A$$ is the pedigree-derived relationship matrix and forms the $$\Gamma$$ part in $$\Gamma\otimes\Sigma$$. A possible data file for such mode may look like:

#y,mu,id
25.0,1,5
33.1,1,6
36.0,1,7
28.3,1,8
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records. Further assume a pedigree in a file called "ped.csv" with content:
1,0,0
2,0,0
3,1,0
4,0,2
5,3,4
6,0,4
7,5,4
8,5,7

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y = mu*b + id*u(v(my_var(1)))
</eqn>
</model>
</root>
</syntaxhighlight>

Compared with the parameter file in example [[#Estimating a mean]] the one above contains only a few extra elements. One this the automatic-optional {{cc|<pedigrees>}} nested inside tag {{cc|<root>}}. This tag contains a keystring {{cc|pedigrees: myped}}, where the user-defined variable behind {{cc|pedigrees:}} is the name of a nominated-compulsory tag nested inside tag {cc|<pedigrees>}}. This concept allows to supply several pedigrees to lmt (e.g. a normal pedigree and a genetic group pedigree). In our example we have only one pedigree named my_ped, with tag {{cc|<my_ped>}} containing the information about this pedigree. Another additional element is the key string {{cc|vars: my_var}} nested in tag {{cc|<vars>}} where the variable of key string {{cc|vars: my_var}} provides the tag names of nominated-compulsory tags, in this example tag {{cc|<my_var>}}.

Tag {{cc|<myvar>}} consist of two structural components: the automatic-compulsory tag {{cc|<sigma>}} and the automatic-optional {{cc|<gamma>}}. Since the the variance of $$u=A\sigma_a^2$$, where $$A=\Gamma$$ and $$\sigma_a^2=\Sigma$$, a {{cc|<gamma>}} tag must be supplied to fully specify the variance. '''Note that if the {{cc|<gamma>}} tag is missing or miss-spelled {{lmt}} will assume that the variance of $$u=I\sigma_a^2$$'''. Tag {{cc|<gamma>}} contains a automatic-compulsory tag {{cc|<A>}} which specifies the $$\Gamma=A$$. Since $$A$$ is build from a pedigree, tag {{cc|<A>}} contains a compulsory key string {{cc|pedigree: my_ped}} which nominates pedigree in tag {{cc|<my_ped>}} to be used for building $$A$$.

Note the difference between the tags {{cc|<sigma>}} nested in tag {{cc|<res>}} and {{cc|<my_var>}}. The former specifies {{cc|<sigma>}} to be provided by tag {{cc|1=<matrix attributes="matrix">}}, whereas the latter specifies {{cc|<sigma>}} to be provided by a file.

The model section in the above parameter file need to communicate to to {{lmt}} that $$u$$ is a random factor with a variance $$A\sigma_a^2$$. This is done by extending the u.d. factor name {{cc|u}} in {{cc|1=y = mu*b + id*u(v(my_var(1)))}} by a specifier {{cc|(v(my_var(1)))}}. Note that without a specifier {{cc|u}} would be regarded as a fixed factor. The specifier {{cc|u(v)}} communicates that {{cc|u}} has a variance assigned. Further, {{cc|v}} has a specifier assigned via {{cc|v(my_var)}} which communicates that the name of the variance is {{cc|my_var}}. The variance in tag {{cc|<my_var>}} contains a {{cc|<gamma>}} and a {{cc|<sigma>}} component. The integer number inside bracket {{cc|my_var(1)}} communicates that $$\sigma_a^2$$ of {{cc|u}} is located in the first diagonal element of $$\Sigma$$.

In summary construct {{cc|u(v(my_var(1)))}} communicates that
*{{cc|u}} has a variance assigned
*the variance is named {{cc|my_var}}
*the variance is located in the first diagonal element of the $$\Sigma$$ matrix specified in tag {{cc|<sigma>}} nested in tag {{cc|<my_var>>}}

=== Estimating fixed means and a random genetic effects in a multi-variate model ===

Consider the linear model

$$
\left(
\begin{array}{c}
y_1 \\
y_2
\end{array}
\right)=
\left(
\begin{array}{cc}
X_1 & 0 \\
0 & X_2 \\
\end{array}
\right)
\left(
\begin{array}{c}
b_1 \\
b_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
Z & 0 \\
0 & Z
\end{array}
\right)
\left(
\begin{array}{c}
u_1 \\
u_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
I & 0 \\
0 & I
\end{array}
\right)
\left(
\begin{array}{c}
e_1 \\
e_2
\end{array}
\right)
$$

where all variables are those declared in [[#Estimating a mean and a random genetic effect in a uni-variate model|above]], and subscripts $$1$$ and $$2$$ index trait $$1$$ and $$2$$, respectively.

Note that $$[u_1,u_2]\sim N([0,0],A\otimes \Sigma_a)$$ where $$A$$ is the pedigree-derived relationship matrix and
$$
\Sigma_a=
\left(\begin{array}{cc}
\sigma_{a_1}^2 & \sigma_{a_1,a_2}\\
\sigma_{a_2,a_1} & \sigma_{a_2}^2
\end{array}\right)
$$
Further, $$[e_1,e_2]\sim N([0,0],I\otimes \Sigma_e)$$ with
$$
\Sigma_e=
\left(\begin{array}{cc}
\sigma_{e_1}^2 & \sigma_{e_1,e_2}\\
\sigma_{e_2,e_1} & \sigma_{e_2}^2
\end{array}\right)
$$.

A possible data file for such mode may look like:
#y1,y2,mu,id
25.0,0.8,1,5
33.1,0.5,1,6
36.0,1.5,1,7
28.3,3.6,1,8
and the pedigree files is that provided in example [[#Estimating a mean and a random genetic effect in a uni-variate model]].

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0,0.8
0.8,1.2
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y1 = mu*b1 + id*u1(v(my_var(1)))
y2 = mu*b2 + id*u2(v(my_var(2)))
</eqn>
</model>
</root>
</syntaxhighlight>

== Example code chunks ==

'''The following code chunks are only subset of a full parameter file. It is assumed that all other parts of the instruction file are functional and all necessary input data are available and the that the data file columns have the respective names.'''

=== Providing pedigrees ===

==== Providing a pedigree containing genetic groups ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
phantomparents: 2
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a pedigree containing metafounders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
metafile: mymeta.csv
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a probabilistic pedigree ====

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<pedigrees>
pedigrees: a
<a>
switch: probabilistic
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing several pedigrees ====

<syntaxhighlight lang="xml">
<root>
...
<pedigrees>
pedigrees: a,b
<a>
...
</a>

...

</pedigrees>
...
</root>
</syntaxhighlight>

=== Providing Genotypes ===

==== Providing external allele frequencies ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
pqfile: mypq.csv 
</a>
</genotypes>
...
</root>
</syntaxhighlight>

==== Providing several genotype files ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
...
</root>
</syntaxhighlight>

=== Providing GRMs ===

==== Constructing GRM from genotypes ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Overriding the default GRM construction method ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
method: YA 
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing a GRM from file ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<grms>
grms: x
<x>
file: mygrm.csv
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing several GRMs ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
...
</root>
</syntaxhighlight>

=== Single step models ===

==== ssGBLUP model with GRM build from genotypes====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGBLUP model with GRM supplied externally ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<grms>
grms: x
<x>
file: mygrm.bin
pedigree: a
cross: id.csv
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGTBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
file: pedigree.csv
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
file: mygeno.txt
pedigree: a
cross: ids.csv
...
</a>
</genotypes>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
type: tblup
genotype: a
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssSNPBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
switch: adjustg2a
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with meta-founders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
metafile: mymeta.csv 
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
pqfile: myp.csv 
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with a separate polygenic factor ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: a,g
<a>
<sigma>
file: cov_polygenic.csv 
</sigma>
<gamma>
<A>
pedigree: a
</A>
</gamma>
</a>
<g>
type: snpblup1
genotype: a
aweight: 0.001 
switch: adjustg2a
<sigma>
file: cov_genomic.csv 
</sigma>
<marker_sb1>
<sigma>
file: cov_genomic.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*ug1(v(g(1))+dam*mg1(v(g(2))+individual*ua1(v(a(1))+dam*ma1(v(a(2))
y2=mu*b2+individual*ug2(v(g(3))+dam*mg2(v(g(4))+individual*ua2(v(a(3))+dam*ma2(v(a(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssGBLUP with two genomic factors ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a,b
<a>
...
pedigree: a
</a>

...
pedigree: a

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
<vars>
...
vars: g1,g2
<g1>
...
<gamma>
<H>
...
grm: x
</H>
</gamma>
</g1>
<g2>
...
<gamma>
<H>
...
grm: y
</H>
</gamma>
</g2>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u11(v(g1(1))+id*u21(v(g2(1))
y2=mu*b2+id*u12(v(g1(2))+id*u22(v(g2(2))
</eqn>
</models>
</root>
</syntaxhighlight>

=== Regression on continuous co-variables ===

==== Linear regression ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co))*age1
y2=mu*b2+age(t(co))*age2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== User-defined polynomial expansion ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
x^1
log(sqrt(x))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Using hard-coded Legendre polynomials ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2,3))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
l0
l1
l2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested co-variables ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
weaningweight=mu*b1+age(t(co(p(1,2);n(sex))))*age
intramuscularfatcontent=mu*b2+weight(t(co(p(1,2);n(sex))))*weight
</eqn>
<eqn attributes="strings">
x^1
x^2
</eqn>
</models>
...
</root>
</syntaxhighlight>

=== Random-regression models ===
==== Nested continuous random co-variables ====

{{cc|days}} is a co-variable which is nested within {{cc|individual}} or {{cc|dam}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(n(individual))))*u1(v(g(1))+days(t(co(n(dam))))*m1(v(g(2))
y2=mu*b2+days(t(co(n(individual))))*u2(v(g(3))+days(t(co(n(dam))))*m2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous random co-variables with polynomial expansion ====

Similar to [[#Nested continuous co-variables|Nested continuous co-variables]] but {{cc|days}} is expanded

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(p(1,2,3);n(dam))))*m1(v(g(4,5,6))
y2=mu*b2+days(t(co(p(1,2,3);n(individual))))*u2(v(g(7,8,9))+days(t(co(p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous co-variables with polynomial expansion and an integer co-variable ====

Similar to [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]], but an additional information {{cc|t(i)}} is provided telling {{lmt}} that {{cc|days}} is actually an integer. While the results do not differ from [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]] {{lmt}} can exploit this information for memory efficiency.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(t(i);p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(t(i);p(1,2,3);n(dam))))*m1(v(g(7,8,9))
y2=mu*b2+days(t(co(t(i);p(1,2,3);n(individual))))*u2(v(g(4,5,6))+days(t(co(t(i);p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials of order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
</root>
</syntaxhighlight>

=== Defining equivalent models with genetic groups ===

Note that in the parameterization provided below [[#Defining a model with absorbed genetic groups|absorbed genetic groups]] and [[#Defining a model with genetic groups as extra factor|genetic groups as extra factor]] must yield the same results. However, only when using {{cc|absorbed genetic groups}} the factor level solutions are the actual breeding values. When modelling genetic groups as an extra factor genetic factor solutions and genetic group factor solutions must be added by the user.

==== Defining a model with absorbed genetic groups ====

Note that the only information necessary is the number of phantom parents '''at the top of the pedigree'''({{cc|phantomparents: 10}}) and the information to the variance that the it should be constructed allowing for genetic groups({{cc|switch gg}}).

<syntaxhighlight lang="xml" line highlight="6,19">
<root>
<pedigrees>
pedigrees: a
<a>
file: myped.csv
phantomparents: 10
</a>
<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: a
switch: gg
</A>
</gamma>
</g>
</vars>
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Defining a model with genetic groups as extra random factor ====

Genetic groups are defined as an extra factor, which requires an extra variance({{cc|gg}}) and two pedigrees, the genetic group pedigree({{cc|a}}) and the normal pedigree({{cc|b}}). For a model equivalent to [[#Defining a model with absorbed genetic groups|absorption]] pedigree {{cc|b}} must be a subset of pedigree {{cc|a}}. Further, if breeding values are required {{lmt}} can provide the genetic group regression matrix {{cc|qfile: Q.coocsv}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g,gg
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
<gg>
<sigma>
file: myG.csv <! must contain a 4x4 matrix. should be the same as for "g">
</sigma>
</gg>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1(v(gg(1))+dam(t(gg(a)))*damgg1(v(gg(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2(v(gg(2))+dam(t(gg(a)))*damgg2(v(gg(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== Defining a model with fixed genetic groups ====

Fixed genetic groups are only supported if modeled as an extra factor. Therefore, the model is similar to [[#Defining a model with genetic groups as extra random factor|above]], but the extra variance is omitted. Note that when modeling genetic groups as fixed it is the users responsibility to omit one group from the respective pedigree to ensure that $$X$$ is of full column rank. [[#Linear models in lmt:Column rank of $$X$$|bla]]

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1+dam(t(gg(a)))*damgg1
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2+dam(t(gg(a)))*damgg2
</eqn>
</models>
</root>
</syntaxhighlight>

=== Override the default job parameters ===

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<jobs>
jobs: default
<default>
conv: -9.21 <! log(10e-5)>
</default>
</jobs>
...
</root>
</syntaxhighlight>

=== Use job "solve" instead of "default" ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>

</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Use a direct solver in stead of the default solver ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>
<direct>
</direct>
</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Estimating variance components ===
==== Gibbs sampling ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: sample
<sample>
sampler: x
</sample>
</jobs>
<samplers>
samplers: x
<x>
<blocked>
samples: 100000
</blocked>
</x>
</samplers>
...
</root>
</syntaxhighlight>

==== MC-EM-REML ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: mcemreml
<mcemreml>
conv: -9.21034
rounds: 300
sampler: x
solver: y
</mcemreml>
</jobs>
<solvers>
solvers: y
<y>
<pcgiod>
conv: -16.1181
</pcgiod>
</y>
</solvers>
<samplers>
samplers: x
<x>
<pe>
samples: 50
switch: trace
chains: 36
</pe>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using AI-REML-C ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: airemlc
<airemlc>
</airemlc>
</jobs>
...
</root>
</syntaxhighlight>

=== Estimating variance components using AI-REML-C using single-pass Gibbs sampling to obtain starting values===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: sample,airemlc
<sample>
sampler: x
</sample>
<airemlc>
</airemlc>
</jobs>
<samplers>
samplers: x
<x>
<singlepass>
samples: 200
</singlepass>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Calculating exact prediction error co-variances using a direct solver===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>
<direct>
</direct>
</a>
</solvers>
...
</root>
</syntaxhighlight>

=== Calculating prediction error co-variances for a target individual===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
levels: 1156679414 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>

</a>
</solvers>
...
</root>
</syntaxhighlight>

Examples

2022-06-07T05:02:33Z

127.0.0.1: /* Estimating variance components using Gibbs sampling */

The examples provided in this section are meant to provide a practical examples about the {{lmt}} facilities and the parameter file syntax. It is assumed that the reader is familiar with [[Parameterfile1|section]]

== Solving linear mixed model equations ==

=== Estimating a mean in a uni-variate model ===

Estimating a mean is equivalent to obtaining the generalized least square solution $$b=(X'R^{-1}X)^{-1}X'R^{-1}y$$ for model $$y=Xb+e$$, where $$y$$ is a vector of $$n$$ observations, $$X$$ is as single column matrix of $$1$$, $$b$$ is a fixed factor (mean), $$e$$ is the residual and $$y\sim N(Xb,R)$$ where $$R$$ is a $$n \times n$$ co-variance matrix.

From the above it follows that for task of solving for $$b$$ {{lmt}} needs following information:

the data
the residual variance $$R$$
the model
the solver

Assume we have a data file "data.csv" with content:
#y,mu
25.0,1
33.1,1
36.0,1
28.3,1
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records.
A valid {{lmt}} xml parameter file would look like:
<syntaxhighlight lang="xml" line highlight="5,27">
<root>
<models>
<eqn attributes="strings">
y=mu*b
</eqn>
</models>
<data>
datafile: data.csv
missingthreshold: -50.0
</data>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
</vars>
</root>
</syntaxhighlight>

Following the introduced [[Parameterfile1|parameterfile terminology]] tags {{cc|<data>}}, {{cc|<vars>}} and {{cc|<model>}} are automatic-compulsory. Since {{cc|solve}} is the default job and we are using the default solver in default parameterization no further information about the job or solver is required.

The most important aspect is the model definition in tag {{cc|<eqn>}}, nested inside tag {{cc|<model>}} $$y=mu*b$$. The variable names used here are either defined by the data file header, or by the user. That is, $$y$$ and $$mu$$ are defined in the data file header, whereas $$b$$ is a user-defined factor name. Translated this means that the content of the data column named $$y$$ should be regressed on the content of the data column named $$mu$$ with the regression coefficient named $$b$$.

Since there are no further specifications supplied about $$y$$, $$mu$$ and $$b$$, it is assumed that $$y$$ is a continuous variable, $$mu$$ is a classification variable, and $$b$$ is fixed factor.
The necessary variances are defined by the content of the automatic-compulsory tag {{cc|<vars>}}. {{lmt}} requires one compulsory variance, the residual variance, which must be specified via tag {{cc|<res>}}. Therefore tag {{cc|res}} is automatic-compulsory.

The default {{lmt}} variance structure is [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Gamma$$ and $$\Sigma$$ are specified inside tags {{cc|<gamma>}} and {{cc|<sigma>}}, respectively.
However, only tag {{cc|<sigma>}} is [[Parameterfile1#Parsing logic|automatic-compulsory]], whereas tag {{cc|<gamma>}} is [[Parameterfile1#Parsing logic|automatic-optional]]. A missing {{cc|<gamma>}} tag implies that [https://en.wikipedia.org/wiki/Identity_matrix $$\Gamma = I$$]. Note that for {{lmt}} $$\Sigma$$ is always a matrix, that is a scalar $$\sigma^2$$ is treated as a matrix $$1 \times 1$$ matrix.

For the above example, the variance specification inside {{cc|<res>}} implies that $$\Gamma\otimes \Sigma \equiv I\otimes \Sigma$$. Since $$\Sigma$$ is a $$1\times 1$$ matrix with $$\Sigma[1,1]=\sigma_e^2$$, $$R$$ reduces to $$I\sigma_e^2$$.

Note tag {{cc|<matrix>}} nested in tag {{cc|<sigma>}}. The content of tag {{cc|<matrix>}} does not comply with the formatting rules as pointed o ut [[Parameterfile1#Key strings|above]]. That is {{cc|5.0}} is not a valid key string. To let {{lmt}} know that the content of tag {{cc|<matrix>}} should not be evaluated as a key string, with a subsequent error message, [[Parameterfile1#Escaping tag content formatting rules|the tag must have attributes]]. In this example {{cc|1=matrix attributes="matrix"}} escapes the content of tag {{cc|<matrix>}} from the formatting rules.

Further, tag {{cc|<matrix>}} is automatic-optional. This might be confusing because, as pointed out above, $$\Sigma$$ forms an indispensable part of $$\Gamma\otimes \Sigma$$. However, tag {{cc|<matrix>}} belongs to a [[Parameterfile1#Group of mutually exclusive information sources|group of mutually exclusive information sources]] of which members are tag {{cc|<matrix>}} and key string {{cc|file: yourfilename}}. That is, $$\Sigma$$ maybe either embedded in the parameter file or supplied via an external file.

Note that the spelling of most tags used in the above parameter file is determined by {{lmt}} and must be abide by.

=== Estimating a fixed mean and a random genetic effect in a uni-variate model ===

Consider the linear model $$y=Xb+Zu+e$$ where all variables are those declared in [[#Estimating a mean]], $$u$$ is vector of length $$m$$ of random direct genetic effects and $$Z$$ is a design matrix of dimension $$n \times m$$ linking genetic effects to their respective observations. Note that $$u\sim N(0,A\sigma_a^2)$$ where $$A$$ is the pedigree-derived relationship matrix and forms the $$\Gamma$$ part in $$\Gamma\otimes\Sigma$$. A possible data file for such mode may look like:

#y,mu,id
25.0,1,5
33.1,1,6
36.0,1,7
28.3,1,8
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records. Further assume a pedigree in a file called "ped.csv" with content:
1,0,0
2,0,0
3,1,0
4,0,2
5,3,4
6,0,4
7,5,4
8,5,7

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y = mu*b + id*u(v(my_var(1)))
</eqn>
</model>
</root>
</syntaxhighlight>

Compared with the parameter file in example [[#Estimating a mean]] the one above contains only a few extra elements. One this the automatic-optional {{cc|<pedigrees>}} nested inside tag {{cc|<root>}}. This tag contains a keystring {{cc|pedigrees: myped}}, where the user-defined variable behind {{cc|pedigrees:}} is the name of a nominated-compulsory tag nested inside tag {cc|<pedigrees>}}. This concept allows to supply several pedigrees to lmt (e.g. a normal pedigree and a genetic group pedigree). In our example we have only one pedigree named my_ped, with tag {{cc|<my_ped>}} containing the information about this pedigree. Another additional element is the key string {{cc|vars: my_var}} nested in tag {{cc|<vars>}} where the variable of key string {{cc|vars: my_var}} provides the tag names of nominated-compulsory tags, in this example tag {{cc|<my_var>}}.

Tag {{cc|<myvar>}} consist of two structural components: the automatic-compulsory tag {{cc|<sigma>}} and the automatic-optional {{cc|<gamma>}}. Since the the variance of $$u=A\sigma_a^2$$, where $$A=\Gamma$$ and $$\sigma_a^2=\Sigma$$, a {{cc|<gamma>}} tag must be supplied to fully specify the variance. '''Note that if the {{cc|<gamma>}} tag is missing or miss-spelled {{lmt}} will assume that the variance of $$u=I\sigma_a^2$$'''. Tag {{cc|<gamma>}} contains a automatic-compulsory tag {{cc|<A>}} which specifies the $$\Gamma=A$$. Since $$A$$ is build from a pedigree, tag {{cc|<A>}} contains a compulsory key string {{cc|pedigree: my_ped}} which nominates pedigree in tag {{cc|<my_ped>}} to be used for building $$A$$.

Note the difference between the tags {{cc|<sigma>}} nested in tag {{cc|<res>}} and {{cc|<my_var>}}. The former specifies {{cc|<sigma>}} to be provided by tag {{cc|1=<matrix attributes="matrix">}}, whereas the latter specifies {{cc|<sigma>}} to be provided by a file.

The model section in the above parameter file need to communicate to to {{lmt}} that $$u$$ is a random factor with a variance $$A\sigma_a^2$$. This is done by extending the u.d. factor name {{cc|u}} in {{cc|1=y = mu*b + id*u(v(my_var(1)))}} by a specifier {{cc|(v(my_var(1)))}}. Note that without a specifier {{cc|u}} would be regarded as a fixed factor. The specifier {{cc|u(v)}} communicates that {{cc|u}} has a variance assigned. Further, {{cc|v}} has a specifier assigned via {{cc|v(my_var)}} which communicates that the name of the variance is {{cc|my_var}}. The variance in tag {{cc|<my_var>}} contains a {{cc|<gamma>}} and a {{cc|<sigma>}} component. The integer number inside bracket {{cc|my_var(1)}} communicates that $$\sigma_a^2$$ of {{cc|u}} is located in the first diagonal element of $$\Sigma$$.

In summary construct {{cc|u(v(my_var(1)))}} communicates that
*{{cc|u}} has a variance assigned
*the variance is named {{cc|my_var}}
*the variance is located in the first diagonal element of the $$\Sigma$$ matrix specified in tag {{cc|<sigma>}} nested in tag {{cc|<my_var>>}}

=== Estimating fixed means and a random genetic effects in a multi-variate model ===

Consider the linear model

$$
\left(
\begin{array}{c}
y_1 \\
y_2
\end{array}
\right)=
\left(
\begin{array}{cc}
X_1 & 0 \\
0 & X_2 \\
\end{array}
\right)
\left(
\begin{array}{c}
b_1 \\
b_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
Z & 0 \\
0 & Z
\end{array}
\right)
\left(
\begin{array}{c}
u_1 \\
u_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
I & 0 \\
0 & I
\end{array}
\right)
\left(
\begin{array}{c}
e_1 \\
e_2
\end{array}
\right)
$$

where all variables are those declared in [[#Estimating a mean and a random genetic effect in a uni-variate model|above]], and subscripts $$1$$ and $$2$$ index trait $$1$$ and $$2$$, respectively.

Note that $$[u_1,u_2]\sim N([0,0],A\otimes \Sigma_a)$$ where $$A$$ is the pedigree-derived relationship matrix and
$$
\Sigma_a=
\left(\begin{array}{cc}
\sigma_{a_1}^2 & \sigma_{a_1,a_2}\\
\sigma_{a_2,a_1} & \sigma_{a_2}^2
\end{array}\right)
$$
Further, $$[e_1,e_2]\sim N([0,0],I\otimes \Sigma_e)$$ with
$$
\Sigma_e=
\left(\begin{array}{cc}
\sigma_{e_1}^2 & \sigma_{e_1,e_2}\\
\sigma_{e_2,e_1} & \sigma_{e_2}^2
\end{array}\right)
$$.

A possible data file for such mode may look like:
#y1,y2,mu,id
25.0,0.8,1,5
33.1,0.5,1,6
36.0,1.5,1,7
28.3,3.6,1,8
and the pedigree files is that provided in example [[#Estimating a mean and a random genetic effect in a uni-variate model]].

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0,0.8
0.8,1.2
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y1 = mu*b1 + id*u1(v(my_var(1)))
y2 = mu*b2 + id*u2(v(my_var(2)))
</eqn>
</model>
</root>
</syntaxhighlight>

== Example code chunks ==

'''The following code chunks are only subset of a full parameter file. It is assumed that all other parts of the instruction file are functional and all necessary input data are available and the that the data file columns have the respective names.'''

=== Providing pedigrees ===

==== Providing a pedigree containing genetic groups ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
phantomparents: 2
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a pedigree containing metafounders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
metafile: mymeta.csv
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a probabilistic pedigree ====

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<pedigrees>
pedigrees: a
<a>
switch: probabilistic
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing several pedigrees ====

<syntaxhighlight lang="xml">
<root>
...
<pedigrees>
pedigrees: a,b
<a>
...
</a>

...

</pedigrees>
...
</root>
</syntaxhighlight>

=== Providing Genotypes ===

==== Providing external allele frequencies ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
pqfile: mypq.csv 
</a>
</genotypes>
...
</root>
</syntaxhighlight>

==== Providing several genotype files ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
...
</root>
</syntaxhighlight>

=== Providing GRMs ===

==== Constructing GRM from genotypes ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Overriding the default GRM construction method ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
method: YA 
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing a GRM from file ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<grms>
grms: x
<x>
file: mygrm.csv
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing several GRMs ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
...
</root>
</syntaxhighlight>

=== Single step models ===

==== ssGBLUP model with GRM build from genotypes====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGBLUP model with GRM supplied externally ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<grms>
grms: x
<x>
file: mygrm.bin
pedigree: a
cross: id.csv
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGTBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
file: pedigree.csv
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
file: mygeno.txt
pedigree: a
cross: ids.csv
...
</a>
</genotypes>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
type: tblup
genotype: a
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssSNPBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
switch: adjustg2a
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with meta-founders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
metafile: mymeta.csv 
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
pqfile: myp.csv 
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with a separate polygenic factor ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: a,g
<a>
<sigma>
file: cov_polygenic.csv 
</sigma>
<gamma>
<A>
pedigree: a
</A>
</gamma>
</a>
<g>
type: snpblup1
genotype: a
aweight: 0.001 
switch: adjustg2a
<sigma>
file: cov_genomic.csv 
</sigma>
<marker_sb1>
<sigma>
file: cov_genomic.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*ug1(v(g(1))+dam*mg1(v(g(2))+individual*ua1(v(a(1))+dam*ma1(v(a(2))
y2=mu*b2+individual*ug2(v(g(3))+dam*mg2(v(g(4))+individual*ua2(v(a(3))+dam*ma2(v(a(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssGBLUP with two genomic factors ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a,b
<a>
...
pedigree: a
</a>

...
pedigree: a

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
<vars>
...
vars: g1,g2
<g1>
...
<gamma>
<H>
...
grm: x
</H>
</gamma>
</g1>
<g2>
...
<gamma>
<H>
...
grm: y
</H>
</gamma>
</g2>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u11(v(g1(1))+id*u21(v(g2(1))
y2=mu*b2+id*u12(v(g1(2))+id*u22(v(g2(2))
</eqn>
</models>
</root>
</syntaxhighlight>

=== Regression on continuous co-variables ===

==== Linear regression ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co))*age1
y2=mu*b2+age(t(co))*age2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== User-defined polynomial expansion ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
x^1
log(sqrt(x))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Using hard-coded Legendre polynomials ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2,3))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
l0
l1
l2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested co-variables ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
weaningweight=mu*b1+age(t(co(p(1,2);n(sex))))*age
intramuscularfatcontent=mu*b2+weight(t(co(p(1,2);n(sex))))*weight
</eqn>
<eqn attributes="strings">
x^1
x^2
</eqn>
</models>
...
</root>
</syntaxhighlight>

=== Random-regression models ===
==== Nested continuous random co-variables ====

{{cc|days}} is a co-variable which is nested within {{cc|individual}} or {{cc|dam}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(n(individual))))*u1(v(g(1))+days(t(co(n(dam))))*m1(v(g(2))
y2=mu*b2+days(t(co(n(individual))))*u2(v(g(3))+days(t(co(n(dam))))*m2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous random co-variables with polynomial expansion ====

Similar to [[#Nested continuous co-variables|Nested continuous co-variables]] but {{cc|days}} is expanded

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(p(1,2,3);n(dam))))*m1(v(g(4,5,6))
y2=mu*b2+days(t(co(p(1,2,3);n(individual))))*u2(v(g(7,8,9))+days(t(co(p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous co-variables with polynomial expansion and an integer co-variable ====

Similar to [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]], but an additional information {{cc|t(i)}} is provided telling {{lmt}} that {{cc|days}} is actually an integer. While the results do not differ from [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]] {{lmt}} can exploit this information for memory efficiency.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(t(i);p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(t(i);p(1,2,3);n(dam))))*m1(v(g(7,8,9))
y2=mu*b2+days(t(co(t(i);p(1,2,3);n(individual))))*u2(v(g(4,5,6))+days(t(co(t(i);p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials of order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
</root>
</syntaxhighlight>

=== Defining equivalent models with genetic groups ===

Note that in the parameterization provided below [[#Defining a model with absorbed genetic groups|absorbed genetic groups]] and [[#Defining a model with genetic groups as extra factor|genetic groups as extra factor]] must yield the same results. However, only when using {{cc|absorbed genetic groups}} the factor level solutions are the actual breeding values. When modelling genetic groups as an extra factor genetic factor solutions and genetic group factor solutions must be added by the user.

==== Defining a model with absorbed genetic groups ====

Note that the only information necessary is the number of phantom parents '''at the top of the pedigree'''({{cc|phantomparents: 10}}) and the information to the variance that the it should be constructed allowing for genetic groups({{cc|switch gg}}).

<syntaxhighlight lang="xml" line highlight="6,19">
<root>
<pedigrees>
pedigrees: a
<a>
file: myped.csv
phantomparents: 10
</a>
<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: a
switch: gg
</A>
</gamma>
</g>
</vars>
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Defining a model with genetic groups as extra random factor ====

Genetic groups are defined as an extra factor, which requires an extra variance({{cc|gg}}) and two pedigrees, the genetic group pedigree({{cc|a}}) and the normal pedigree({{cc|b}}). For a model equivalent to [[#Defining a model with absorbed genetic groups|absorption]] pedigree {{cc|b}} must be a subset of pedigree {{cc|a}}. Further, if breeding values are required {{lmt}} can provide the genetic group regression matrix {{cc|qfile: Q.coocsv}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g,gg
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
<gg>
<sigma>
file: myG.csv <! must contain a 4x4 matrix. should be the same as for "g">
</sigma>
</gg>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1(v(gg(1))+dam(t(gg(a)))*damgg1(v(gg(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2(v(gg(2))+dam(t(gg(a)))*damgg2(v(gg(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== Defining a model with fixed genetic groups ====

Fixed genetic groups are only supported if modeled as an extra factor. Therefore, the model is similar to [[#Defining a model with genetic groups as extra random factor|above]], but the extra variance is omitted. Note that when modeling genetic groups as fixed it is the users responsibility to omit one group from the respective pedigree to ensure that $$X$$ is of full column rank. [[#Linear models in lmt:Column rank of $$X$$|bla]]

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1+dam(t(gg(a)))*damgg1
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2+dam(t(gg(a)))*damgg2
</eqn>
</models>
</root>
</syntaxhighlight>

=== Override the default job parameters ===

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<jobs>
jobs: default
<default>
conv: -9.21 <! log(10e-5)>
</default>
</jobs>
...
</root>
</syntaxhighlight>

=== Use job "solve" instead of "default" ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>

</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Use a direct solver in stead of the default solver ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>
<direct>
</direct>
</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Estimating variance components ===
==== Gibbs sampling ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: sample
<sample>
sampler: x
</sample>
</jobs>
<samplers>
samplers: x
<x>
<blocked>
samples: 100000
</blocked>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using MC-EM-REML ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: mcemreml
<mcemreml>
conv: -9.21034
rounds: 300
sampler: x
solver: y
</mcemreml>
</jobs>
<solvers>
solvers: y
<y>
<pcgiod>
conv: -16.1181
</pcgiod>
</y>
</solvers>
<samplers>
samplers: x
<x>
<pe>
samples: 50
switch: trace
chains: 36
</pe>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using AI-REML-C ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: airemlc
<airemlc>
</airemlc>
</jobs>
...
</root>
</syntaxhighlight>

=== Estimating variance components using AI-REML-C using single-pass Gibbs sampling to obtain starting values===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: sample,airemlc
<sample>
sampler: x
</sample>
<airemlc>
</airemlc>
</jobs>
<samplers>
samplers: x
<x>
<singlepass>
samples: 200
</singlepass>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Calculating exact prediction error co-variances using a direct solver===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>
<direct>
</direct>
</a>
</solvers>
...
</root>
</syntaxhighlight>

=== Calculating prediction error co-variances for a target individual===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
levels: 1156679414 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>

</a>
</solvers>
...
</root>
</syntaxhighlight>

Examples

2022-06-07T05:00:20Z

127.0.0.1: /* Estimating variance components using AI-REML-C using single-pass Gibbs sampling to obtain starting values */

The examples provided in this section are meant to provide a practical examples about the {{lmt}} facilities and the parameter file syntax. It is assumed that the reader is familiar with [[Parameterfile1|section]]

== Solving linear mixed model equations ==

=== Estimating a mean in a uni-variate model ===

Estimating a mean is equivalent to obtaining the generalized least square solution $$b=(X'R^{-1}X)^{-1}X'R^{-1}y$$ for model $$y=Xb+e$$, where $$y$$ is a vector of $$n$$ observations, $$X$$ is as single column matrix of $$1$$, $$b$$ is a fixed factor (mean), $$e$$ is the residual and $$y\sim N(Xb,R)$$ where $$R$$ is a $$n \times n$$ co-variance matrix.

From the above it follows that for task of solving for $$b$$ {{lmt}} needs following information:

the data
the residual variance $$R$$
the model
the solver

Assume we have a data file "data.csv" with content:
#y,mu
25.0,1
33.1,1
36.0,1
28.3,1
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records.
A valid {{lmt}} xml parameter file would look like:
<syntaxhighlight lang="xml" line highlight="5,27">
<root>
<models>
<eqn attributes="strings">
y=mu*b
</eqn>
</models>
<data>
datafile: data.csv
missingthreshold: -50.0
</data>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
</vars>
</root>
</syntaxhighlight>

Following the introduced [[Parameterfile1|parameterfile terminology]] tags {{cc|<data>}}, {{cc|<vars>}} and {{cc|<model>}} are automatic-compulsory. Since {{cc|solve}} is the default job and we are using the default solver in default parameterization no further information about the job or solver is required.

The most important aspect is the model definition in tag {{cc|<eqn>}}, nested inside tag {{cc|<model>}} $$y=mu*b$$. The variable names used here are either defined by the data file header, or by the user. That is, $$y$$ and $$mu$$ are defined in the data file header, whereas $$b$$ is a user-defined factor name. Translated this means that the content of the data column named $$y$$ should be regressed on the content of the data column named $$mu$$ with the regression coefficient named $$b$$.

Since there are no further specifications supplied about $$y$$, $$mu$$ and $$b$$, it is assumed that $$y$$ is a continuous variable, $$mu$$ is a classification variable, and $$b$$ is fixed factor.
The necessary variances are defined by the content of the automatic-compulsory tag {{cc|<vars>}}. {{lmt}} requires one compulsory variance, the residual variance, which must be specified via tag {{cc|<res>}}. Therefore tag {{cc|res}} is automatic-compulsory.

The default {{lmt}} variance structure is [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Gamma$$ and $$\Sigma$$ are specified inside tags {{cc|<gamma>}} and {{cc|<sigma>}}, respectively.
However, only tag {{cc|<sigma>}} is [[Parameterfile1#Parsing logic|automatic-compulsory]], whereas tag {{cc|<gamma>}} is [[Parameterfile1#Parsing logic|automatic-optional]]. A missing {{cc|<gamma>}} tag implies that [https://en.wikipedia.org/wiki/Identity_matrix $$\Gamma = I$$]. Note that for {{lmt}} $$\Sigma$$ is always a matrix, that is a scalar $$\sigma^2$$ is treated as a matrix $$1 \times 1$$ matrix.

For the above example, the variance specification inside {{cc|<res>}} implies that $$\Gamma\otimes \Sigma \equiv I\otimes \Sigma$$. Since $$\Sigma$$ is a $$1\times 1$$ matrix with $$\Sigma[1,1]=\sigma_e^2$$, $$R$$ reduces to $$I\sigma_e^2$$.

Note tag {{cc|<matrix>}} nested in tag {{cc|<sigma>}}. The content of tag {{cc|<matrix>}} does not comply with the formatting rules as pointed o ut [[Parameterfile1#Key strings|above]]. That is {{cc|5.0}} is not a valid key string. To let {{lmt}} know that the content of tag {{cc|<matrix>}} should not be evaluated as a key string, with a subsequent error message, [[Parameterfile1#Escaping tag content formatting rules|the tag must have attributes]]. In this example {{cc|1=matrix attributes="matrix"}} escapes the content of tag {{cc|<matrix>}} from the formatting rules.

Further, tag {{cc|<matrix>}} is automatic-optional. This might be confusing because, as pointed out above, $$\Sigma$$ forms an indispensable part of $$\Gamma\otimes \Sigma$$. However, tag {{cc|<matrix>}} belongs to a [[Parameterfile1#Group of mutually exclusive information sources|group of mutually exclusive information sources]] of which members are tag {{cc|<matrix>}} and key string {{cc|file: yourfilename}}. That is, $$\Sigma$$ maybe either embedded in the parameter file or supplied via an external file.

Note that the spelling of most tags used in the above parameter file is determined by {{lmt}} and must be abide by.

=== Estimating a fixed mean and a random genetic effect in a uni-variate model ===

Consider the linear model $$y=Xb+Zu+e$$ where all variables are those declared in [[#Estimating a mean]], $$u$$ is vector of length $$m$$ of random direct genetic effects and $$Z$$ is a design matrix of dimension $$n \times m$$ linking genetic effects to their respective observations. Note that $$u\sim N(0,A\sigma_a^2)$$ where $$A$$ is the pedigree-derived relationship matrix and forms the $$\Gamma$$ part in $$\Gamma\otimes\Sigma$$. A possible data file for such mode may look like:

#y,mu,id
25.0,1,5
33.1,1,6
36.0,1,7
28.3,1,8
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records. Further assume a pedigree in a file called "ped.csv" with content:
1,0,0
2,0,0
3,1,0
4,0,2
5,3,4
6,0,4
7,5,4
8,5,7

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y = mu*b + id*u(v(my_var(1)))
</eqn>
</model>
</root>
</syntaxhighlight>

Compared with the parameter file in example [[#Estimating a mean]] the one above contains only a few extra elements. One this the automatic-optional {{cc|<pedigrees>}} nested inside tag {{cc|<root>}}. This tag contains a keystring {{cc|pedigrees: myped}}, where the user-defined variable behind {{cc|pedigrees:}} is the name of a nominated-compulsory tag nested inside tag {cc|<pedigrees>}}. This concept allows to supply several pedigrees to lmt (e.g. a normal pedigree and a genetic group pedigree). In our example we have only one pedigree named my_ped, with tag {{cc|<my_ped>}} containing the information about this pedigree. Another additional element is the key string {{cc|vars: my_var}} nested in tag {{cc|<vars>}} where the variable of key string {{cc|vars: my_var}} provides the tag names of nominated-compulsory tags, in this example tag {{cc|<my_var>}}.

Tag {{cc|<myvar>}} consist of two structural components: the automatic-compulsory tag {{cc|<sigma>}} and the automatic-optional {{cc|<gamma>}}. Since the the variance of $$u=A\sigma_a^2$$, where $$A=\Gamma$$ and $$\sigma_a^2=\Sigma$$, a {{cc|<gamma>}} tag must be supplied to fully specify the variance. '''Note that if the {{cc|<gamma>}} tag is missing or miss-spelled {{lmt}} will assume that the variance of $$u=I\sigma_a^2$$'''. Tag {{cc|<gamma>}} contains a automatic-compulsory tag {{cc|<A>}} which specifies the $$\Gamma=A$$. Since $$A$$ is build from a pedigree, tag {{cc|<A>}} contains a compulsory key string {{cc|pedigree: my_ped}} which nominates pedigree in tag {{cc|<my_ped>}} to be used for building $$A$$.

Note the difference between the tags {{cc|<sigma>}} nested in tag {{cc|<res>}} and {{cc|<my_var>}}. The former specifies {{cc|<sigma>}} to be provided by tag {{cc|1=<matrix attributes="matrix">}}, whereas the latter specifies {{cc|<sigma>}} to be provided by a file.

The model section in the above parameter file need to communicate to to {{lmt}} that $$u$$ is a random factor with a variance $$A\sigma_a^2$$. This is done by extending the u.d. factor name {{cc|u}} in {{cc|1=y = mu*b + id*u(v(my_var(1)))}} by a specifier {{cc|(v(my_var(1)))}}. Note that without a specifier {{cc|u}} would be regarded as a fixed factor. The specifier {{cc|u(v)}} communicates that {{cc|u}} has a variance assigned. Further, {{cc|v}} has a specifier assigned via {{cc|v(my_var)}} which communicates that the name of the variance is {{cc|my_var}}. The variance in tag {{cc|<my_var>}} contains a {{cc|<gamma>}} and a {{cc|<sigma>}} component. The integer number inside bracket {{cc|my_var(1)}} communicates that $$\sigma_a^2$$ of {{cc|u}} is located in the first diagonal element of $$\Sigma$$.

In summary construct {{cc|u(v(my_var(1)))}} communicates that
*{{cc|u}} has a variance assigned
*the variance is named {{cc|my_var}}
*the variance is located in the first diagonal element of the $$\Sigma$$ matrix specified in tag {{cc|<sigma>}} nested in tag {{cc|<my_var>>}}

=== Estimating fixed means and a random genetic effects in a multi-variate model ===

Consider the linear model

$$
\left(
\begin{array}{c}
y_1 \\
y_2
\end{array}
\right)=
\left(
\begin{array}{cc}
X_1 & 0 \\
0 & X_2 \\
\end{array}
\right)
\left(
\begin{array}{c}
b_1 \\
b_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
Z & 0 \\
0 & Z
\end{array}
\right)
\left(
\begin{array}{c}
u_1 \\
u_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
I & 0 \\
0 & I
\end{array}
\right)
\left(
\begin{array}{c}
e_1 \\
e_2
\end{array}
\right)
$$

where all variables are those declared in [[#Estimating a mean and a random genetic effect in a uni-variate model|above]], and subscripts $$1$$ and $$2$$ index trait $$1$$ and $$2$$, respectively.

Note that $$[u_1,u_2]\sim N([0,0],A\otimes \Sigma_a)$$ where $$A$$ is the pedigree-derived relationship matrix and
$$
\Sigma_a=
\left(\begin{array}{cc}
\sigma_{a_1}^2 & \sigma_{a_1,a_2}\\
\sigma_{a_2,a_1} & \sigma_{a_2}^2
\end{array}\right)
$$
Further, $$[e_1,e_2]\sim N([0,0],I\otimes \Sigma_e)$$ with
$$
\Sigma_e=
\left(\begin{array}{cc}
\sigma_{e_1}^2 & \sigma_{e_1,e_2}\\
\sigma_{e_2,e_1} & \sigma_{e_2}^2
\end{array}\right)
$$.

A possible data file for such mode may look like:
#y1,y2,mu,id
25.0,0.8,1,5
33.1,0.5,1,6
36.0,1.5,1,7
28.3,3.6,1,8
and the pedigree files is that provided in example [[#Estimating a mean and a random genetic effect in a uni-variate model]].

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0,0.8
0.8,1.2
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y1 = mu*b1 + id*u1(v(my_var(1)))
y2 = mu*b2 + id*u2(v(my_var(2)))
</eqn>
</model>
</root>
</syntaxhighlight>

== Example code chunks ==

'''The following code chunks are only subset of a full parameter file. It is assumed that all other parts of the instruction file are functional and all necessary input data are available and the that the data file columns have the respective names.'''

=== Providing pedigrees ===

==== Providing a pedigree containing genetic groups ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
phantomparents: 2
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a pedigree containing metafounders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
metafile: mymeta.csv
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a probabilistic pedigree ====

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<pedigrees>
pedigrees: a
<a>
switch: probabilistic
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing several pedigrees ====

<syntaxhighlight lang="xml">
<root>
...
<pedigrees>
pedigrees: a,b
<a>
...
</a>

...

</pedigrees>
...
</root>
</syntaxhighlight>

=== Providing Genotypes ===

==== Providing external allele frequencies ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
pqfile: mypq.csv 
</a>
</genotypes>
...
</root>
</syntaxhighlight>

==== Providing several genotype files ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
...
</root>
</syntaxhighlight>

=== Providing GRMs ===

==== Constructing GRM from genotypes ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Overriding the default GRM construction method ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
method: YA 
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing a GRM from file ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<grms>
grms: x
<x>
file: mygrm.csv
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing several GRMs ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
...
</root>
</syntaxhighlight>

=== Single step models ===

==== ssGBLUP model with GRM build from genotypes====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGBLUP model with GRM supplied externally ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<grms>
grms: x
<x>
file: mygrm.bin
pedigree: a
cross: id.csv
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGTBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
file: pedigree.csv
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
file: mygeno.txt
pedigree: a
cross: ids.csv
...
</a>
</genotypes>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
type: tblup
genotype: a
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssSNPBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
switch: adjustg2a
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with meta-founders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
metafile: mymeta.csv 
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
pqfile: myp.csv 
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with a separate polygenic factor ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: a,g
<a>
<sigma>
file: cov_polygenic.csv 
</sigma>
<gamma>
<A>
pedigree: a
</A>
</gamma>
</a>
<g>
type: snpblup1
genotype: a
aweight: 0.001 
switch: adjustg2a
<sigma>
file: cov_genomic.csv 
</sigma>
<marker_sb1>
<sigma>
file: cov_genomic.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*ug1(v(g(1))+dam*mg1(v(g(2))+individual*ua1(v(a(1))+dam*ma1(v(a(2))
y2=mu*b2+individual*ug2(v(g(3))+dam*mg2(v(g(4))+individual*ua2(v(a(3))+dam*ma2(v(a(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssGBLUP with two genomic factors ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a,b
<a>
...
pedigree: a
</a>

...
pedigree: a

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
<vars>
...
vars: g1,g2
<g1>
...
<gamma>
<H>
...
grm: x
</H>
</gamma>
</g1>
<g2>
...
<gamma>
<H>
...
grm: y
</H>
</gamma>
</g2>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u11(v(g1(1))+id*u21(v(g2(1))
y2=mu*b2+id*u12(v(g1(2))+id*u22(v(g2(2))
</eqn>
</models>
</root>
</syntaxhighlight>

=== Regression on continuous co-variables ===

==== Linear regression ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co))*age1
y2=mu*b2+age(t(co))*age2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== User-defined polynomial expansion ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
x^1
log(sqrt(x))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Using hard-coded Legendre polynomials ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2,3))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
l0
l1
l2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested co-variables ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
weaningweight=mu*b1+age(t(co(p(1,2);n(sex))))*age
intramuscularfatcontent=mu*b2+weight(t(co(p(1,2);n(sex))))*weight
</eqn>
<eqn attributes="strings">
x^1
x^2
</eqn>
</models>
...
</root>
</syntaxhighlight>

=== Random-regression models ===
==== Nested continuous random co-variables ====

{{cc|days}} is a co-variable which is nested within {{cc|individual}} or {{cc|dam}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(n(individual))))*u1(v(g(1))+days(t(co(n(dam))))*m1(v(g(2))
y2=mu*b2+days(t(co(n(individual))))*u2(v(g(3))+days(t(co(n(dam))))*m2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous random co-variables with polynomial expansion ====

Similar to [[#Nested continuous co-variables|Nested continuous co-variables]] but {{cc|days}} is expanded

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(p(1,2,3);n(dam))))*m1(v(g(4,5,6))
y2=mu*b2+days(t(co(p(1,2,3);n(individual))))*u2(v(g(7,8,9))+days(t(co(p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous co-variables with polynomial expansion and an integer co-variable ====

Similar to [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]], but an additional information {{cc|t(i)}} is provided telling {{lmt}} that {{cc|days}} is actually an integer. While the results do not differ from [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]] {{lmt}} can exploit this information for memory efficiency.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(t(i);p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(t(i);p(1,2,3);n(dam))))*m1(v(g(7,8,9))
y2=mu*b2+days(t(co(t(i);p(1,2,3);n(individual))))*u2(v(g(4,5,6))+days(t(co(t(i);p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials of order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
</root>
</syntaxhighlight>

=== Defining equivalent models with genetic groups ===

Note that in the parameterization provided below [[#Defining a model with absorbed genetic groups|absorbed genetic groups]] and [[#Defining a model with genetic groups as extra factor|genetic groups as extra factor]] must yield the same results. However, only when using {{cc|absorbed genetic groups}} the factor level solutions are the actual breeding values. When modelling genetic groups as an extra factor genetic factor solutions and genetic group factor solutions must be added by the user.

==== Defining a model with absorbed genetic groups ====

Note that the only information necessary is the number of phantom parents '''at the top of the pedigree'''({{cc|phantomparents: 10}}) and the information to the variance that the it should be constructed allowing for genetic groups({{cc|switch gg}}).

<syntaxhighlight lang="xml" line highlight="6,19">
<root>
<pedigrees>
pedigrees: a
<a>
file: myped.csv
phantomparents: 10
</a>
<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: a
switch: gg
</A>
</gamma>
</g>
</vars>
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Defining a model with genetic groups as extra random factor ====

Genetic groups are defined as an extra factor, which requires an extra variance({{cc|gg}}) and two pedigrees, the genetic group pedigree({{cc|a}}) and the normal pedigree({{cc|b}}). For a model equivalent to [[#Defining a model with absorbed genetic groups|absorption]] pedigree {{cc|b}} must be a subset of pedigree {{cc|a}}. Further, if breeding values are required {{lmt}} can provide the genetic group regression matrix {{cc|qfile: Q.coocsv}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g,gg
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
<gg>
<sigma>
file: myG.csv <! must contain a 4x4 matrix. should be the same as for "g">
</sigma>
</gg>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1(v(gg(1))+dam(t(gg(a)))*damgg1(v(gg(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2(v(gg(2))+dam(t(gg(a)))*damgg2(v(gg(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== Defining a model with fixed genetic groups ====

Fixed genetic groups are only supported if modeled as an extra factor. Therefore, the model is similar to [[#Defining a model with genetic groups as extra random factor|above]], but the extra variance is omitted. Note that when modeling genetic groups as fixed it is the users responsibility to omit one group from the respective pedigree to ensure that $$X$$ is of full column rank. [[#Linear models in lmt:Column rank of $$X$$|bla]]

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1+dam(t(gg(a)))*damgg1
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2+dam(t(gg(a)))*damgg2
</eqn>
</models>
</root>
</syntaxhighlight>

=== Override the default job parameters ===

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<jobs>
jobs: default
<default>
conv: -9.21 <! log(10e-5)>
</default>
</jobs>
...
</root>
</syntaxhighlight>

=== Use job "solve" instead of "default" ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>

</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Use a direct solver in stead of the default solver ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>
<direct>
</direct>
</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using Gibbs sampling ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: sample
<sample>
sampler: x
</sample>
</jobs>
<samplers>
samplers: x
<x>
<blocked>
samples: 100000
</blocked>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using MC-EM-REML ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: mcemreml
<mcemreml>
conv: -9.21034
rounds: 300
sampler: x
solver: y
</mcemreml>
</jobs>
<solvers>
solvers: y
<y>
<pcgiod>
conv: -16.1181
</pcgiod>
</y>
</solvers>
<samplers>
samplers: x
<x>
<pe>
samples: 50
switch: trace
chains: 36
</pe>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using AI-REML-C ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: airemlc
<airemlc>
</airemlc>
</jobs>
...
</root>
</syntaxhighlight>

=== Estimating variance components using AI-REML-C using single-pass Gibbs sampling to obtain starting values===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: sample,airemlc
<sample>
sampler: x
</sample>
<airemlc>
</airemlc>
</jobs>
<samplers>
samplers: x
<x>
<singlepass>
samples: 200
</singlepass>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Calculating exact prediction error co-variances using a direct solver===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>
<direct>
</direct>
</a>
</solvers>
...
</root>
</syntaxhighlight>

=== Calculating prediction error co-variances for a target individual===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
levels: 1156679414 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>

</a>
</solvers>
...
</root>
</syntaxhighlight>

Examples

2022-06-07T04:58:37Z

127.0.0.1: /* Estimating variance components using AI-REML-C */

The examples provided in this section are meant to provide a practical examples about the {{lmt}} facilities and the parameter file syntax. It is assumed that the reader is familiar with [[Parameterfile1|section]]

== Solving linear mixed model equations ==

=== Estimating a mean in a uni-variate model ===

Estimating a mean is equivalent to obtaining the generalized least square solution $$b=(X'R^{-1}X)^{-1}X'R^{-1}y$$ for model $$y=Xb+e$$, where $$y$$ is a vector of $$n$$ observations, $$X$$ is as single column matrix of $$1$$, $$b$$ is a fixed factor (mean), $$e$$ is the residual and $$y\sim N(Xb,R)$$ where $$R$$ is a $$n \times n$$ co-variance matrix.

From the above it follows that for task of solving for $$b$$ {{lmt}} needs following information:

the data
the residual variance $$R$$
the model
the solver

Assume we have a data file "data.csv" with content:
#y,mu
25.0,1
33.1,1
36.0,1
28.3,1
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records.
A valid {{lmt}} xml parameter file would look like:
<syntaxhighlight lang="xml" line highlight="5,27">
<root>
<models>
<eqn attributes="strings">
y=mu*b
</eqn>
</models>
<data>
datafile: data.csv
missingthreshold: -50.0
</data>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
</vars>
</root>
</syntaxhighlight>

Following the introduced [[Parameterfile1|parameterfile terminology]] tags {{cc|<data>}}, {{cc|<vars>}} and {{cc|<model>}} are automatic-compulsory. Since {{cc|solve}} is the default job and we are using the default solver in default parameterization no further information about the job or solver is required.

The most important aspect is the model definition in tag {{cc|<eqn>}}, nested inside tag {{cc|<model>}} $$y=mu*b$$. The variable names used here are either defined by the data file header, or by the user. That is, $$y$$ and $$mu$$ are defined in the data file header, whereas $$b$$ is a user-defined factor name. Translated this means that the content of the data column named $$y$$ should be regressed on the content of the data column named $$mu$$ with the regression coefficient named $$b$$.

Since there are no further specifications supplied about $$y$$, $$mu$$ and $$b$$, it is assumed that $$y$$ is a continuous variable, $$mu$$ is a classification variable, and $$b$$ is fixed factor.
The necessary variances are defined by the content of the automatic-compulsory tag {{cc|<vars>}}. {{lmt}} requires one compulsory variance, the residual variance, which must be specified via tag {{cc|<res>}}. Therefore tag {{cc|res}} is automatic-compulsory.

The default {{lmt}} variance structure is [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Gamma$$ and $$\Sigma$$ are specified inside tags {{cc|<gamma>}} and {{cc|<sigma>}}, respectively.
However, only tag {{cc|<sigma>}} is [[Parameterfile1#Parsing logic|automatic-compulsory]], whereas tag {{cc|<gamma>}} is [[Parameterfile1#Parsing logic|automatic-optional]]. A missing {{cc|<gamma>}} tag implies that [https://en.wikipedia.org/wiki/Identity_matrix $$\Gamma = I$$]. Note that for {{lmt}} $$\Sigma$$ is always a matrix, that is a scalar $$\sigma^2$$ is treated as a matrix $$1 \times 1$$ matrix.

For the above example, the variance specification inside {{cc|<res>}} implies that $$\Gamma\otimes \Sigma \equiv I\otimes \Sigma$$. Since $$\Sigma$$ is a $$1\times 1$$ matrix with $$\Sigma[1,1]=\sigma_e^2$$, $$R$$ reduces to $$I\sigma_e^2$$.

Note tag {{cc|<matrix>}} nested in tag {{cc|<sigma>}}. The content of tag {{cc|<matrix>}} does not comply with the formatting rules as pointed o ut [[Parameterfile1#Key strings|above]]. That is {{cc|5.0}} is not a valid key string. To let {{lmt}} know that the content of tag {{cc|<matrix>}} should not be evaluated as a key string, with a subsequent error message, [[Parameterfile1#Escaping tag content formatting rules|the tag must have attributes]]. In this example {{cc|1=matrix attributes="matrix"}} escapes the content of tag {{cc|<matrix>}} from the formatting rules.

Further, tag {{cc|<matrix>}} is automatic-optional. This might be confusing because, as pointed out above, $$\Sigma$$ forms an indispensable part of $$\Gamma\otimes \Sigma$$. However, tag {{cc|<matrix>}} belongs to a [[Parameterfile1#Group of mutually exclusive information sources|group of mutually exclusive information sources]] of which members are tag {{cc|<matrix>}} and key string {{cc|file: yourfilename}}. That is, $$\Sigma$$ maybe either embedded in the parameter file or supplied via an external file.

Note that the spelling of most tags used in the above parameter file is determined by {{lmt}} and must be abide by.

=== Estimating a fixed mean and a random genetic effect in a uni-variate model ===

Consider the linear model $$y=Xb+Zu+e$$ where all variables are those declared in [[#Estimating a mean]], $$u$$ is vector of length $$m$$ of random direct genetic effects and $$Z$$ is a design matrix of dimension $$n \times m$$ linking genetic effects to their respective observations. Note that $$u\sim N(0,A\sigma_a^2)$$ where $$A$$ is the pedigree-derived relationship matrix and forms the $$\Gamma$$ part in $$\Gamma\otimes\Sigma$$. A possible data file for such mode may look like:

#y,mu,id
25.0,1,5
33.1,1,6
36.0,1,7
28.3,1,8
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records. Further assume a pedigree in a file called "ped.csv" with content:
1,0,0
2,0,0
3,1,0
4,0,2
5,3,4
6,0,4
7,5,4
8,5,7

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y = mu*b + id*u(v(my_var(1)))
</eqn>
</model>
</root>
</syntaxhighlight>

Compared with the parameter file in example [[#Estimating a mean]] the one above contains only a few extra elements. One this the automatic-optional {{cc|<pedigrees>}} nested inside tag {{cc|<root>}}. This tag contains a keystring {{cc|pedigrees: myped}}, where the user-defined variable behind {{cc|pedigrees:}} is the name of a nominated-compulsory tag nested inside tag {cc|<pedigrees>}}. This concept allows to supply several pedigrees to lmt (e.g. a normal pedigree and a genetic group pedigree). In our example we have only one pedigree named my_ped, with tag {{cc|<my_ped>}} containing the information about this pedigree. Another additional element is the key string {{cc|vars: my_var}} nested in tag {{cc|<vars>}} where the variable of key string {{cc|vars: my_var}} provides the tag names of nominated-compulsory tags, in this example tag {{cc|<my_var>}}.

Tag {{cc|<myvar>}} consist of two structural components: the automatic-compulsory tag {{cc|<sigma>}} and the automatic-optional {{cc|<gamma>}}. Since the the variance of $$u=A\sigma_a^2$$, where $$A=\Gamma$$ and $$\sigma_a^2=\Sigma$$, a {{cc|<gamma>}} tag must be supplied to fully specify the variance. '''Note that if the {{cc|<gamma>}} tag is missing or miss-spelled {{lmt}} will assume that the variance of $$u=I\sigma_a^2$$'''. Tag {{cc|<gamma>}} contains a automatic-compulsory tag {{cc|<A>}} which specifies the $$\Gamma=A$$. Since $$A$$ is build from a pedigree, tag {{cc|<A>}} contains a compulsory key string {{cc|pedigree: my_ped}} which nominates pedigree in tag {{cc|<my_ped>}} to be used for building $$A$$.

Note the difference between the tags {{cc|<sigma>}} nested in tag {{cc|<res>}} and {{cc|<my_var>}}. The former specifies {{cc|<sigma>}} to be provided by tag {{cc|1=<matrix attributes="matrix">}}, whereas the latter specifies {{cc|<sigma>}} to be provided by a file.

The model section in the above parameter file need to communicate to to {{lmt}} that $$u$$ is a random factor with a variance $$A\sigma_a^2$$. This is done by extending the u.d. factor name {{cc|u}} in {{cc|1=y = mu*b + id*u(v(my_var(1)))}} by a specifier {{cc|(v(my_var(1)))}}. Note that without a specifier {{cc|u}} would be regarded as a fixed factor. The specifier {{cc|u(v)}} communicates that {{cc|u}} has a variance assigned. Further, {{cc|v}} has a specifier assigned via {{cc|v(my_var)}} which communicates that the name of the variance is {{cc|my_var}}. The variance in tag {{cc|<my_var>}} contains a {{cc|<gamma>}} and a {{cc|<sigma>}} component. The integer number inside bracket {{cc|my_var(1)}} communicates that $$\sigma_a^2$$ of {{cc|u}} is located in the first diagonal element of $$\Sigma$$.

In summary construct {{cc|u(v(my_var(1)))}} communicates that
*{{cc|u}} has a variance assigned
*the variance is named {{cc|my_var}}
*the variance is located in the first diagonal element of the $$\Sigma$$ matrix specified in tag {{cc|<sigma>}} nested in tag {{cc|<my_var>>}}

=== Estimating fixed means and a random genetic effects in a multi-variate model ===

Consider the linear model

$$
\left(
\begin{array}{c}
y_1 \\
y_2
\end{array}
\right)=
\left(
\begin{array}{cc}
X_1 & 0 \\
0 & X_2 \\
\end{array}
\right)
\left(
\begin{array}{c}
b_1 \\
b_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
Z & 0 \\
0 & Z
\end{array}
\right)
\left(
\begin{array}{c}
u_1 \\
u_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
I & 0 \\
0 & I
\end{array}
\right)
\left(
\begin{array}{c}
e_1 \\
e_2
\end{array}
\right)
$$

where all variables are those declared in [[#Estimating a mean and a random genetic effect in a uni-variate model|above]], and subscripts $$1$$ and $$2$$ index trait $$1$$ and $$2$$, respectively.

Note that $$[u_1,u_2]\sim N([0,0],A\otimes \Sigma_a)$$ where $$A$$ is the pedigree-derived relationship matrix and
$$
\Sigma_a=
\left(\begin{array}{cc}
\sigma_{a_1}^2 & \sigma_{a_1,a_2}\\
\sigma_{a_2,a_1} & \sigma_{a_2}^2
\end{array}\right)
$$
Further, $$[e_1,e_2]\sim N([0,0],I\otimes \Sigma_e)$$ with
$$
\Sigma_e=
\left(\begin{array}{cc}
\sigma_{e_1}^2 & \sigma_{e_1,e_2}\\
\sigma_{e_2,e_1} & \sigma_{e_2}^2
\end{array}\right)
$$.

A possible data file for such mode may look like:
#y1,y2,mu,id
25.0,0.8,1,5
33.1,0.5,1,6
36.0,1.5,1,7
28.3,3.6,1,8
and the pedigree files is that provided in example [[#Estimating a mean and a random genetic effect in a uni-variate model]].

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0,0.8
0.8,1.2
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y1 = mu*b1 + id*u1(v(my_var(1)))
y2 = mu*b2 + id*u2(v(my_var(2)))
</eqn>
</model>
</root>
</syntaxhighlight>

== Example code chunks ==

'''The following code chunks are only subset of a full parameter file. It is assumed that all other parts of the instruction file are functional and all necessary input data are available and the that the data file columns have the respective names.'''

=== Providing pedigrees ===

==== Providing a pedigree containing genetic groups ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
phantomparents: 2
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a pedigree containing metafounders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
metafile: mymeta.csv
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a probabilistic pedigree ====

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<pedigrees>
pedigrees: a
<a>
switch: probabilistic
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing several pedigrees ====

<syntaxhighlight lang="xml">
<root>
...
<pedigrees>
pedigrees: a,b
<a>
...
</a>

...

</pedigrees>
...
</root>
</syntaxhighlight>

=== Providing Genotypes ===

==== Providing external allele frequencies ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
pqfile: mypq.csv 
</a>
</genotypes>
...
</root>
</syntaxhighlight>

==== Providing several genotype files ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
...
</root>
</syntaxhighlight>

=== Providing GRMs ===

==== Constructing GRM from genotypes ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Overriding the default GRM construction method ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
method: YA 
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing a GRM from file ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<grms>
grms: x
<x>
file: mygrm.csv
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing several GRMs ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
...
</root>
</syntaxhighlight>

=== Single step models ===

==== ssGBLUP model with GRM build from genotypes====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGBLUP model with GRM supplied externally ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<grms>
grms: x
<x>
file: mygrm.bin
pedigree: a
cross: id.csv
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGTBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
file: pedigree.csv
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
file: mygeno.txt
pedigree: a
cross: ids.csv
...
</a>
</genotypes>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
type: tblup
genotype: a
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssSNPBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
switch: adjustg2a
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with meta-founders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
metafile: mymeta.csv 
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
pqfile: myp.csv 
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with a separate polygenic factor ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: a,g
<a>
<sigma>
file: cov_polygenic.csv 
</sigma>
<gamma>
<A>
pedigree: a
</A>
</gamma>
</a>
<g>
type: snpblup1
genotype: a
aweight: 0.001 
switch: adjustg2a
<sigma>
file: cov_genomic.csv 
</sigma>
<marker_sb1>
<sigma>
file: cov_genomic.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*ug1(v(g(1))+dam*mg1(v(g(2))+individual*ua1(v(a(1))+dam*ma1(v(a(2))
y2=mu*b2+individual*ug2(v(g(3))+dam*mg2(v(g(4))+individual*ua2(v(a(3))+dam*ma2(v(a(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssGBLUP with two genomic factors ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a,b
<a>
...
pedigree: a
</a>

...
pedigree: a

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
<vars>
...
vars: g1,g2
<g1>
...
<gamma>
<H>
...
grm: x
</H>
</gamma>
</g1>
<g2>
...
<gamma>
<H>
...
grm: y
</H>
</gamma>
</g2>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u11(v(g1(1))+id*u21(v(g2(1))
y2=mu*b2+id*u12(v(g1(2))+id*u22(v(g2(2))
</eqn>
</models>
</root>
</syntaxhighlight>

=== Regression on continuous co-variables ===

==== Linear regression ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co))*age1
y2=mu*b2+age(t(co))*age2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== User-defined polynomial expansion ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
x^1
log(sqrt(x))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Using hard-coded Legendre polynomials ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2,3))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
l0
l1
l2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested co-variables ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
weaningweight=mu*b1+age(t(co(p(1,2);n(sex))))*age
intramuscularfatcontent=mu*b2+weight(t(co(p(1,2);n(sex))))*weight
</eqn>
<eqn attributes="strings">
x^1
x^2
</eqn>
</models>
...
</root>
</syntaxhighlight>

=== Random-regression models ===
==== Nested continuous random co-variables ====

{{cc|days}} is a co-variable which is nested within {{cc|individual}} or {{cc|dam}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(n(individual))))*u1(v(g(1))+days(t(co(n(dam))))*m1(v(g(2))
y2=mu*b2+days(t(co(n(individual))))*u2(v(g(3))+days(t(co(n(dam))))*m2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous random co-variables with polynomial expansion ====

Similar to [[#Nested continuous co-variables|Nested continuous co-variables]] but {{cc|days}} is expanded

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(p(1,2,3);n(dam))))*m1(v(g(4,5,6))
y2=mu*b2+days(t(co(p(1,2,3);n(individual))))*u2(v(g(7,8,9))+days(t(co(p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous co-variables with polynomial expansion and an integer co-variable ====

Similar to [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]], but an additional information {{cc|t(i)}} is provided telling {{lmt}} that {{cc|days}} is actually an integer. While the results do not differ from [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]] {{lmt}} can exploit this information for memory efficiency.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(t(i);p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(t(i);p(1,2,3);n(dam))))*m1(v(g(7,8,9))
y2=mu*b2+days(t(co(t(i);p(1,2,3);n(individual))))*u2(v(g(4,5,6))+days(t(co(t(i);p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials of order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
</root>
</syntaxhighlight>

=== Defining equivalent models with genetic groups ===

Note that in the parameterization provided below [[#Defining a model with absorbed genetic groups|absorbed genetic groups]] and [[#Defining a model with genetic groups as extra factor|genetic groups as extra factor]] must yield the same results. However, only when using {{cc|absorbed genetic groups}} the factor level solutions are the actual breeding values. When modelling genetic groups as an extra factor genetic factor solutions and genetic group factor solutions must be added by the user.

==== Defining a model with absorbed genetic groups ====

Note that the only information necessary is the number of phantom parents '''at the top of the pedigree'''({{cc|phantomparents: 10}}) and the information to the variance that the it should be constructed allowing for genetic groups({{cc|switch gg}}).

<syntaxhighlight lang="xml" line highlight="6,19">
<root>
<pedigrees>
pedigrees: a
<a>
file: myped.csv
phantomparents: 10
</a>
<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: a
switch: gg
</A>
</gamma>
</g>
</vars>
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Defining a model with genetic groups as extra random factor ====

Genetic groups are defined as an extra factor, which requires an extra variance({{cc|gg}}) and two pedigrees, the genetic group pedigree({{cc|a}}) and the normal pedigree({{cc|b}}). For a model equivalent to [[#Defining a model with absorbed genetic groups|absorption]] pedigree {{cc|b}} must be a subset of pedigree {{cc|a}}. Further, if breeding values are required {{lmt}} can provide the genetic group regression matrix {{cc|qfile: Q.coocsv}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g,gg
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
<gg>
<sigma>
file: myG.csv <! must contain a 4x4 matrix. should be the same as for "g">
</sigma>
</gg>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1(v(gg(1))+dam(t(gg(a)))*damgg1(v(gg(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2(v(gg(2))+dam(t(gg(a)))*damgg2(v(gg(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== Defining a model with fixed genetic groups ====

Fixed genetic groups are only supported if modeled as an extra factor. Therefore, the model is similar to [[#Defining a model with genetic groups as extra random factor|above]], but the extra variance is omitted. Note that when modeling genetic groups as fixed it is the users responsibility to omit one group from the respective pedigree to ensure that $$X$$ is of full column rank. [[#Linear models in lmt:Column rank of $$X$$|bla]]

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1+dam(t(gg(a)))*damgg1
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2+dam(t(gg(a)))*damgg2
</eqn>
</models>
</root>
</syntaxhighlight>

=== Override the default job parameters ===

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<jobs>
jobs: default
<default>
conv: -9.21 <! log(10e-5)>
</default>
</jobs>
...
</root>
</syntaxhighlight>

=== Use job "solve" instead of "default" ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>

</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Use a direct solver in stead of the default solver ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>
<direct>
</direct>
</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using Gibbs sampling ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: sample
<sample>
sampler: x
</sample>
</jobs>
<samplers>
samplers: x
<x>
<blocked>
samples: 100000
</blocked>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using MC-EM-REML ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: mcemreml
<mcemreml>
conv: -9.21034
rounds: 300
sampler: x
solver: y
</mcemreml>
</jobs>
<solvers>
solvers: y
<y>
<pcgiod>
conv: -16.1181
</pcgiod>
</y>
</solvers>
<samplers>
samplers: x
<x>
<pe>
samples: 50
switch: trace
chains: 36
</pe>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using AI-REML-C ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: airemlc
<airemlc>
</airemlc>
</jobs>
...
</root>
</syntaxhighlight>

=== Estimating variance components using AI-REML-C using single-pass Gibbs sampling to obtain starting values===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: sample,airemlc
<sample>
sampler: x
</sample>
<airemlc>
</airemlc>
</jobs>
<samplers>
samplers: x
<x>
<singlepass>
</singlepass>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Calculating exact prediction error co-variances using a direct solver===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>
<direct>
</direct>
</a>
</solvers>
...
</root>
</syntaxhighlight>

=== Calculating prediction error co-variances for a target individual===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
levels: 1156679414 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>

</a>
</solvers>
...
</root>
</syntaxhighlight>

Parameter file elements

2022-06-07T04:54:27Z

127.0.0.1: /* mcemreml> */

Below is a list of all possible parameter file xml elements. For each element an example is provided as well as information about the element's host element, the element's type and the element's content. '''Note that all words(element names, key string words, key string variables) in bold are hard-coded, all in italic are user-defined (this does not apply to the example box)'''. The spelling of hard-coded words must be abide by, the spelling of user-defined words is user-defined.

=<'''model'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<model>
<eqn attribute="strings">
..
</eqn>
<poly attribute="strings">
..
</poly>
</model>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}compulsory
{{!}}hosts information about the equations and the polynomials.
}}

content:

*compulsory element '''<eqn attributes="strings">'''
*optional element '''<poly attributes="strings">'''
==<'''eqn'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<model>
<eqn attribute="strings">
y1=x*b1+z*u1(v(g(1))
y2=x*b2+z*u2(v(g(2))
y3=x*b3+a(t(co(p(1,2);n(k))))*c1+z*u3(v(g(3)))
</eqn>
..
</model>
</root>
</syntaxhighlight>
{{!}}'''model'''
{{!}}compulsory
{{!}}hosts information about the equations.
}}

content:

*[[linear mixed models in lmt#Model_syntax|model strings]] which are escaped from the formatting rules by adding '''attributes="strings"''' to the start tag.

==<'''poly'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<model>
<poly attribute="strings">
x^0
x^2
3*x^2+sqrt(sin(x))
</poly>
..
</model>
</root>
</syntaxhighlight>
{{!}}'''model'''
{{!}}optional
{{!}}hosts user defined polynomials and references to hard-coded polynomials. Note that there can only be one polynomial per line. Model strings will reference polynomials by their line number.
}}

content

*[[linear mixed models in lmt#Polynomials|polynomial strings]] which are escaped from the formatting rules by adding '''attributes="strings"''' to the start tag.

=<'''pedigrees'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<pedigrees>
pedigrees: a,b
...
</pedigrees>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}automatic-optional
{{!}}hosts one to several elements each containing information about a specific pedigree}}

content:
*key strings
{{tablekeys2|
{{!}}'''pedigrees'''
{{!}}'''pedigrees''': ''a,b''
{{!}}compulsory
{{!}}csv word-list
{{!}}''pedigree names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements}}
*nominated-compulsory elements
==<''pedigree name''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<pedigrees>
pedigrees: myped
..
<myped>
file: myped.csv
switch: selfing
phantomparents: 2
qfile: myq.coocsv
</myped>
..
</pedigrees>
</root>
</syntaxhighlight>
{{!}}'''pedigrees'''
{{!}}nominated-compulsory
{{!}}hosts information about a specific pedigree identified by ''pedigree name''
}}
content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''myped.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}list content determines the name of the file containing the pedigree
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''selfing'''
{{!}}optional
{{!}}csv-word-list
{{!}}'''selfing,probabilistic'''
{{!}}none
{{!}}list content determines pedigree properties.
*'''selfing''': both parents can have the same id
*'''probabilistic''': each individual can have more than 1 pair of parents
{{!}}-
{{!}}'''phantomparents'''
{{!}}'''phantomparents''': 2
{{!}}optional
{{!}}single numeric value
{{!}}positive integer
{{!}}none
{{!}}integer number determines the number of individuals at the top of the pedigree which are phantom parents
{{!}}-
{{!}}'''qfile'''
{{!}}'''qfile''': myq.coocsv
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}provides name of file to which the genetic regression matrix should be written. Supported file name suffixes are ".bin" for binary block file, ".blkcsv" for csv blockfile and ".coocsv" for csv coordinate format.
{{!}}-
{{!}}'''metafile'''
{{!}}'''metafile''': meta.csv
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}provides name of the file containing the metafounder co-variance matrix.
}}

=<'''genotypes'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<genotypes>
genotypes: a,b
...
</genotypes>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}automatic-optional
{{!}}hosts one to several elements each containing information about different sets of genotypes
}}

content:
*key strings
{{tablekeys2|
{{!}}'''genotypes'''
{{!}}'''genotypes''': ''a,b''
{{!}}compulsory
{{!}}csv word-list
{{!}}''genotype names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements
}}
*nominated-compulsory elements
==<''genotype name''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<genotypes>
genotypes: mygn
..
<mygn>
file: genotypes.txt
pedigree: myped
cross: crossref.csv
</mygn>
..
</genotypes>
</root>
</syntaxhighlight>
{{!}}'''genotypes'''
{{!}}nominated-compulsory
{{!}}hosts information about a specific set of genotypes identified by ''genotype name''
}}
content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''genotype.txt''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the genotypes
{{!}}-
{{!}}'''cross'''
{{!}}'''cross''': ''mycross.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the pedigree ids related to the genotypes
{{!}}-
{{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}optional
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree previously invoked pedigree related to the content of the cross-reference file
{{!}}-
{{!}}'''pqfile'''
{{!}}'''pqfile''': ''mypq.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the allele frequencies. Note that the file content is used as a substitute for the column means of the marker matrix. It must therefore contain 2p.
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''ignorefixed'''
{{!}}optional
{{!}}csv word-list
{{!}}'''ignorefixed,ignoremissing'''
{{!}}none
{{!}}
*ignorefixed: fixed markers are ignored '''but may lead to program crash or spurious results latter on'''
*ignoremissing: marker coded as missing(3) are set to 0.
}}

=<'''grms'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<grms>
grms: a,b
...
</grms>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}automatic-optional
{{!}}hosts one to several elements each containing information about a specific grm
}}

content:
*key strings
{{tablekeys2|
{{!}}'''grms'''
{{!}}'''grms''': ''x,y''
{{!}}compulsory
{{!}}csv word-list
{{!}}''grm names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements
}}
*nominated-compulsory elements
==<''grm name''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<grms>
grms: mygrm
..
<mygrm>
genotype: mygn
method: YA
</mygrm>
..
</genotypes>
</root>
</syntaxhighlight>
{{!}}'''grms'''
{{!}}nominated-compulsory
{{!}}hosts information about a specific grm identified by ''grm name''
}}
content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''mygrm.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the grm. mutually exclusive with keyword '''genotype'''.
{{!}}-
{{!}}'''genotype'''
{{!}}'''genotype''': ''mygn''
{{!}}compulsory
{{!}}word
{{!}}''genotype name''
{{!}}none
{{!}}content determines the genotype element to be used for building the grm. mutually exclusive with keyword '''file'''.
{{!}}-
{{!}}'''cross'''
{{!}}'''cross''': ''mycross.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the pedigree ids related to the genotypes. if this information has already been supplied to the genotypes it cannot be supplied here.
{{!}}-
{{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}optional
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree previously invoked pedigree related to the content of the cross-reference file. if this information has already been supplied to the genotypes it cannot be supplied here.
{{!}}-
{{!}}'''method'''
{{!}}'''method''':'''YA'''
{{!}}optional
{{!}}alternative words
{{!}}'''VR<nowiki>|</nowiki>YA'''
{{!}}'''VR'''
{{!}}content determines the method to be used for building a grm from genotypes
*'''VR''': VanRaden Method 1 is used
*'''YA''': VanRaden Method 2(method Yang) is used
{{!}}-
{{!}}'''outfile'''
{{!}}'''outfile''': ''mygrm.bin''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file where the grm should be written to. will only take effect if the grm was build from genotypes. if the genotypes had a pedigree assigned a cross-reference file will be written out as well which contains the original pedigree ids of the genotyped individuals in the order of the rows/columns of the grm. the file name of the cross-reference file is that of the grm with the prefix '''cross_'''.
}}

=<'''vars'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
vars: g,p
...
</vars>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}compulsory
{{!}}hosts one to several elements each containing information about a specific variance.
}}

content:
*key strings
{{tablekeys2|
{{!}}'''vars'''
{{!}}'''vars''': ''g,p''
{{!}}compulsory
{{!}}csv word-list
{{!}}''variance names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements
}}
*nominated-compulsory elements
*compulsory element '''<res>'''
=='''Kronecker products'''==
Variance structures below are Kronecker products $$\Gamma \otimes \Sigma$$. If no '''type''' keystring is provided this is the default.
==='''<res>'''===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
<res>
<sigma>
..
</sigma>
</res>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''vars'''
{{!}}compulsory
{{!}}hosts information about the residual variance structure.
}}

content:
*compulsory element [[#<sigma>|'''<sigma>''']]
*optional element [[#<gamma>|'''<gamma>''']]

===''<variance name>''===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
..
</sigma>
<gamma>
..
</gamma>
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''vars'''
{{!}}nominated-compulsory
{{!}}hosts information about variance structure identified by ''variance name''.
}}

content:
*compulsory element [[#<sigma>|'''<sigma>''']]
*optional element [[#<gamma>|'''<gamma>''']]

*key strings
{{tablekeys2|
1={{!}}'''type'''
{{!}}'''type''': ''kronecker''
{{!}}optional
{{!}}word
{{!}}''kronecker,snpblup_1''
{{!}}kronecker
{{!}}determines whether the variance structure deviates from a Kronecker product.
}}

===='''<sigma>'''====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
..
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''variance name''
{{!}}compulsory
{{!}}hosts information about $$\Sigma$$ as part of [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]].
}}

content:

*key strings
{{tablekeys2|
1={{!}}'''file'''
{{!}}'''file''': ''mymatrix.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the $$\Sigma$$ matrix. is mutually exclusive with '''<nowiki><matrix attributes="array"></nowiki>'''.
{{!}}-
{{!}}'''type'''
{{!}}'''type''': '''block'''
{{!}}optional
{{!}}word
{{!}}'''block'''
{{!}}none
{{!}}determines that $$\Sigma$$ is equal to [[Supported_features#Supported_variance_structures|$$\Theta$$]]
{{!}}-
{{!}}'''scale'''
{{!}}'''scale''': ''0.05''
{{!}}optional
{{!}}single numeric value
{{!}}real number>0.0
{{!}}none
{{!}}multiplies $$\Sigma$$ once by the provided value after reading.
{{!}}-
{{!}}'''priordf'''
{{!}}'''priordf''': ''10''
{{!}}optional
{{!}}single numeric value
{{!}}real number>=0.0
{{!}}0.0
{{!}}prior degree of freedom when doing Gibbs sampling
{{!}}-
{{!}}'''maskfile'''
{{!}}'''maskfile''': ''mymatrixmask.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing a T/F matrix of the same dimension as the respective $$\Sigma$$ matrix. Is mutually exclusive with '''<nowiki><maskmatrix attributes="array"></nowiki>'''.
}}

*optional element '''<matrix attributes="array">'''
=====<'''matrix attributes="array"'''>=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
<matrix attributes="array">
5.0,0.5
0.5,1.8
</matrix>
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''sigma'''
{{!}}optional
{{!}}hosts the content of a single $$\Sigma$$ matrix. Is mutually exclusive with key string '''file: '''.
}}
=====<'''maskmatrix attributes="array"'''>=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
<maskmatrix attributes="array">
T,F
F,T
</matrix>
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''sigma'''
{{!}}optional
{{!}}hosts the content of a single indicator matrix of the same dimensions as the respective $$\Sigma$$ matrix. Is mutually exclusive with key string '''maskfile: '''.
}}

===='''<gamma>'''====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
..
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''variance name''
{{!}}optional
{{!}}hosts information about $$\Gamma$$ as part of [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]]. If absent $$\Gamma$$ defaults to $$I$$.
}}

content:

*mutually exclusive elements '''<A>, <H>, <G> and <E>'''

====='''<A>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<A>
pedigree: myped
</A>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma$$ being constructed as the numerator relationship matrix A using pedigree ''pedigree name''.
}}

content:
*key strings
{{tablekeys2|
{{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}optional
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree previously invoked to be used to construct A.
{{!}}-
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''gg'''
{{!}}optional
{{!}}csv word-list
{{!}}'''gg'''
{{!}}none
{{!}}
*gg: the pedigree contains genetic groups which will be fitted as random
}}

====='''<H>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<H>
type: tblup
pedigree: myped
genotype: mygn
aweight: 0.05
switch: adjustg2a
</H>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma$$ being constructed as combined single step relationship matrix H using pedigree ''pedigree name'' and genomic information. the genomic information can be supplied
*via a grm element for single step H-BLUP models
*via a genotype element for single step T-BLUP models
Note that for '''type:tblup''' it is not necessary to have an automatic-optional [[#<grms>|<grms>]] element in the parameter file. Doing so will cause the construction and RAM-storage of $$G$$ although it is not need for building H, thus maybe leading to substantial increase in processing time and RAM demand.
}}

content:
*key strings
{{tablekeys2|
1={{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}compulsory
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree element to be used to construct H.
{{!}}-
{{!}}'''type'''
{{!}}'''type''': '''tblup'''
{{!}}optional
{{!}}word
{{!}}'''tblup<nowiki>|</nowiki>gblup'''
{{!}}'''gblup'''
{{!}}content determines the way the inverse of H is constructed.
{{!}}-
{{!}}'''grm'''
{{!}}'''grm''': ''mygrm''
{{!}}conditional-compulsory
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the grm element to be used to construct H. compulsory for '''type: hblup'''.
{{!}}-
{{!}}'''genotype'''
{{!}}'''genotype''': ''mygn''
{{!}}conditional-compulsory
{{!}}word
{{!}}''genotype name''
{{!}}none
{{!}}content determines the genotype element to be used to construct H. compulsory for '''type: tblup'''.
{{!}}-
{{!}}'''aweight'''
{{!}}'''aweight: 0.05'''
{{!}}optional
{{!}}single numeric value
{{!}}0.0<=aweight<=1.0
{{!}}0.0
{{!}}blending of $$G$$ with $$A_{gg}$$ by $$G_w=aweight\times A_{gg}+(1-aweight)\times G$$
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''adjustg2a'''
{{!}}optional
{{!}}csv word-list
{{!}}'''adjustg2a,gg,diag'''
{{!}}none
{{!}}
*adjustg2a: adjustment of $$G$$ towards $$A_{gg}$$ using method
*gg: the pedigree contains genetic groups which will be fitted as random
*diag: calculate H diagonal elements and write to file (only supported for gblup).
{{!}}-
{{!}}'''grmdadd'''
{{!}}'''grmdadd''': ''0.05''
{{!}}optional
{{!}}single numeric value
{{!}}real number >=0.0
{{!}}none
{{!}} value added to the diagonal of $$G$$ to ensure invertibility. The policy is
*if '''aweight'''>0.0, nothing will be added to the diagonals
*if '''aweight''' is not supplied or is zero:
** if '''grmdadd''' is not supplied 0.001 will be added to the diagonals
** otherwise '''grmdadd''' will be used
}}

====='''<G>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<G>
grm: mygrm
</G>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma$$ being constructed from a genomic relationsship matrix.
}}

content:
*key strings
{{tablekeys2|
1={{!}}'''grmdadd'''
{{!}}'''grmdadd''': ''0.05''
{{!}}optional
{{!}}single numeric value
{{!}}real number >=0.0
{{!}}none
{{!}} value added to the diagonal of $$G$$ to ensure invertibility.
}}

====='''<E>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<E>
file: mygamma.csv
</E>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma^{-1}$$ being uploaded from a file.
}}

content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''mygamma.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the file which contains $$\Gamma^{-1}$$.
{{!}}-
{{!}}'''type'''
{{!}}'''type''': '''dense'''
{{!}}optional
{{!}}word
{{!}}'''dense<nowiki>|</nowiki>sparse_csr_ut'''
{{!}}'''sparse_csr_ut'''
{{!}}content determines the file storage of $$\Gamma^{-1}$$
*dense: full squared symmetric matrix
*sparse_csr_ut: squared symmetric sparse upper triangular matrix in [https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_row_(CSR,_CRS_or_Yale_format) csr] format
}}

=='''snpblup1'''==

===''<variance name>''===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
genotype: mygn
aweight: 0.05
switch: adjustg2a
<sigma>
..
</sigma>
<gamma>
..
</gamma>
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''vars'''
{{!}}nominated-compulsory
{{!}}hosts information about variance structure identified by ''variance name''.
}}

content:
*compulsory element '''<sigma>'''
*compulsory element [[#<marker_sb1>|'''<marker_sb1>''']]

*key strings
{{tablekeys2|
1={{!}}'''type'''
{{!}}'''type''': ''kronecker''
{{!}}optional
{{!}}word
{{!}}''kronecker,snpblup_1''
{{!}}kronecker
{{!}}determines whether the variance structure deviates from a Kronecker product.
{{!}}-
{{!}}'''genotype'''
{{!}}'''genotype''': ''mygn''
{{!}}conditional-compulsory
{{!}}word
{{!}}''genotype name''
{{!}}none
{{!}}content determines the genotype element to be used to construct H. compulsory for '''type: tblup'''.
{{!}}-
{{!}}'''aweight'''
{{!}}'''aweight: 0.05'''
{{!}}optional
{{!}}single numeric value
{{!}}0.0<=aweight<=1.0
{{!}}0.0
{{!}}blending of $$G$$ with $$A_{gg}$$ by $$G_w=aweight\times A_{gg}+(1-aweight)\times G$$
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''adjustg2a'''
{{!}}optional
{{!}}csv word-list
{{!}}'''adjustg2a,gg,diag'''
{{!}}none
{{!}}
*adjustg2a: adjustment of $$G$$ towards $$A_{gg}$$ using method
*gg: the pedigree contains genetic groups which will be fitted as random
*diag: calculate H diagonal elements and write to file (only supported for gblup).
}}

===='''<sigma>'''====

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
<sigma>
..
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''variance name''
{{!}}compulsory
{{!}}hosts information about $$\Sigma$$ for the poly-genetic part of the variance structure.
}}

content:

see [[#<sigma>|'''<sigma''']]

===='''<marker_sb1>'''====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
..
<marker_sb1>
..
</marker_sb1>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''marker''
{{!}}compulsory
{{!}}hosts information about the co-variance between and within markers following [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]].
}}

content:

*compulsory element '''<sigma>'''
*optional element '''<gamma>'''

====='''<sigma>'''=====

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
..
<marker_sb1>
<sigma>
..
</sigma>
..
</marker_sb1>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''marker''
{{!}}compulsory
{{!}}hosts information about $$\Sigma$$ as part of [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]] for the marker part of the variance structure. Note that $$\Sigma$$ will be scaled by (1-aweight).
}}

see [[#<sigma>|'''<sigma>''']]

=<'''jobs'''>=

{{tableele2|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: solve,yh
...
</jobs>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}optional
{{!}}hosts one to several elements each containing information about a specific job
{{!}}run default job(solve) in default parameterization(default pcgiod parameterization)
}}

content:
*key strings
{{tablekeys2|
{{!}}'''jobs'''
{{!}}'''jobs''': '''solve,yhat'''
{{!}}compulsory
{{!}}csv word-list
{{!}}'''solve,sample,pevsample,mcemreml,yhat'''
{{!}}none
{{!}}job sequence is determined by the list sequence. list content determines nominated-compulsory elements
}}

*nominated-compulsory elements
**'''<default>'''
**'''<solve>'''
**'''<sample>'''
**'''<pevsample>'''
**'''<pevsolve>'''
**'''<mcemreml>'''
**'''<airemlc>'''
**'''<yhat>'''

==<'''default'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
..
<default>
conv: -18.42
</default>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''default'''
}}

content: see [[#<pcgiod>|<pcgiod>]] for a list of all possible key strings

==<'''solve'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
..
<solve>
solver: mysolver
</solve>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''solve'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''solver'''
{{!}}'''solver''': ''mysolver''
{{!}}compulsory
{{!}}word
{{!}}''solver name''
{{!}}none
{{!}}''solver name'' must be the name of a previously defined solver
}}

==<'''sample'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: sample,..
<sample>
sampler: mysampler
</sample>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''sample'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''sampler'''
{{!}}'''sampler''': ''mysampler''
{{!}}compulsory
{{!}}word
{{!}}''sampler name''
{{!}}none
{{!}}''sampler name'' must be the name of a previously defined sampler
}}

==<'''pevsample'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: pevsample,..
<pevsample>
sampler: mysampler
</pevsample>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''pevsample'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''sampler'''
{{!}}'''sampler''': ''mysampler''
{{!}}compulsory
{{!}}word
{{!}}''sampler name''
{{!}}none
{{!}}''sampler name'' must be the name of a previously defined sampler of type pev
}}

==<'''pevsolve'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: pevsolve,..
<pevsolve>
solver: mysolver
</pevsolver>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''pevsolve'''
}}

content:

*key strings
{{tablekeys2|
1={{!}}'''solver'''
{{!}}'''solver''': ''mysolver''
{{!}}compulsory
{{!}}word
{{!}}''solver name''
{{!}}none
{{!}}''solver name'' must be the name of a previously defined solver
{{!}}-
{{!}}'''factor'''
{{!}}'''factor''': ''gen''
{{!}}compulsory
{{!}}word
{{!}}''factor name''
{{!}}none
{{!}}''factor name'' must be the name of a random factor
{{!}}-
{{!}}'''levels'''
{{!}}'''levels''': ''5,10,20''
{{!}}optional
{{!}}csv integer list
{{!}}''factor level ids''
{{!}}none
{{!}}original factor level ids(.e.g. pedigree ids etc). If not supplied the prediction error co-variance blocks of all factor levels associated to the nominated factor will be calculated. Mutually exclusive with '''levelfile'''.
{{!}}-
{{!}}'''levelfile'''
{{!}}'''levelfile''': ''myfile.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}file containing original factor level ids(.e.g. pedigree ids etc). If not supplied the prediction error co-variance blocks of all factor levels associated to the nominated factor will be calculated. Mutually exclusive with '''levels'''.
{{!}}-
{{!}}'''nrhs'''
{{!}}'''nrhs''': ''50''
{{!}}optional
{{!}}integer
{{!}}''number of right-hand sides''
{{!}}1000
{{!}}number of right-hand-sides to be solved for simultaneously. Has only effect if the direct solver is used. The default may exceed the available RAM.
}}

==<'''airemlc'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: airemlc,..
<airemlc>
rounds: 50
..
</airemlc>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''airemlc'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''rounds'''
{{!}}'''rounds''': ''10''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}20
{{!}}provides the number of aireml-rounds to run
{{!}}-
{{!}}'''convtype'''
{{!}}'''convtype''': '''ng'''
{{!}}optional
{{!}}word
{{!}}'''cd<nowiki>|</nowiki>ng<nowiki>|</nowiki>ll<nowiki>|</nowiki>any<nowiki>|</nowiki>all'''
{{!}}'''cd'''
{{!}}provides the convergence criterion to use
* ll: log of relative change in log-likelihood
* ng: log of the norm of the gradient vector
* cd: log of the relative change of the parameter vector
* all: all of the above
* any: any of the above
{{!}}-
{{!}}'''convll'''
{{!}}'''convll''': ''-10.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''-6.907755''
{{!}}provides the convergence threshold for convergence criterion '''ll'''
{{!}}-
{{!}}'''convng'''
{{!}}'''convng''': ''-10.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''-16.1181''
{{!}}provides the convergence threshold for convergence criterion '''ng'''
{{!}}-
{{!}}'''convcd'''
{{!}}'''convcd''': ''-10.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''-16.1181''
{{!}}provides the convergence threshold for convergence criterion '''cd'''
{{!}}-
{{!}}'''nscale'''
{{!}}'''nscale''': ''0.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''1.0''
{{!}}scales the length of the Newton step.
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''residuals'''
{{!}}optional
{{!}}csv word-list
{{!}}any real number
{{!}}'''writeai,residuals,solutions'''
{{!}}
*'''writeai''': write ai matrix and gradient vector to files ai_ai.csv and ai_ja.csv.
*'''residuals''': after convergence write the residuals to file aic_residuals.csv
*'''solutions''': after convergence write the MME solutions to file results.csv
}}

==<'''mcemreml'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: mcemreml,..
<mcemreml>
rounds: 500
sampler: mysampler
solver: mysolver
</mcemreml>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''mcemreml'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''rounds'''
{{!}}'''rounds''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}500
{{!}}provides maximum the number of mcemreml-rounds to run
{{!}}-
{{!}}'''conv'''
{{!}}'''conv''': ''-16.21''
{{!}}optional
{{!}}numeric value
{{!}}real number
{{!}} -6.907755
{{!}}provides the convergence threshold
{{!}}-
{{!}}'''sampler'''
{{!}}'''sampler''': ''mysampler''
{{!}}compulsory
{{!}}word
{{!}}''sampler name''
{{!}}none
{{!}}''sampler name'' must be the name of a previously defined sampler
{{!}}-
{{!}}'''solver'''
{{!}}'''solver''': ''mysolver''
{{!}}compulsory
{{!}}word
{{!}}''solver name''
{{!}}none
{{!}}''solver name'' must be the name of a previously defined solver
}}

==<'''yhat'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: yhat,..
<yhat>
</yhat>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''yhat'''
}}
Currently '''yhat''' has no key strings or nested elements defined.

=<'''samplers'''>=

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,b,..
...
</samplers>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}optional
{{!}}hosts one to several elements each containing information about a specific sampler
}}

content:
*key strings
{{tablekeys2|
{{!}}'''samplers'''
{{!}}'''samplers''': ''a''
{{!}}compulsory
{{!}}csv word-list
{{!}}''sampler names''
{{!}}none
{{!}}list content determines nominated-compulsory elements
}}
*conditional-compulsory elements

==<''sampler name''>==

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
..
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}'''samplers'''
{{!}}conditional-compulsory
{{!}}hosts one of several mutually exclusive elements defining the type of sampler ''sampler name''
}}

content:
*compulsory mutually exclusive elements
**'''<singlepass>'''
**'''<blocked>'''
**'''<pev>'''

===<'''singlepass'''>===

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
<singlepass>
samples: 10000
burnin: 1000
</singlepass>
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}''sampler name''
{{!}}compulsory
{{!}}defines parameters of a sampler of type '''singlepass'''
}}

*key strings
{{tablekeys2|
{{!}}'''samples'''
{{!}}'''samples''': ''100000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the total number of samples to draw
{{!}}-
{{!}}'''burnin'''
{{!}}'''burnin''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}0
{{!}}provides the number of samples to be discarded as burnin
}}

===<'''blocked'''>===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
<blocked>
samples: 10000
burnin: 1000
</blocked>
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}''sampler name''
{{!}}compulsory
{{!}}defines parameters of a sampler of type '''blocked'''
}}

*key strings
{{tablekeys2|
{{!}}'''samples'''
{{!}}'''samples''': ''100000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the total number of samples to draw
{{!}}-
{{!}}'''burnin'''
{{!}}'''burnin''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}0
{{!}}provides the number of samples to be discarded as burnin
}}

===<'''pev'''>===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
<pev>
samples: 10000
burnin: 1000
chains: 10
</pev>
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}''sampler name''
{{!}}compulsory
{{!}}defines parameters of a sampler of type '''pev'''
}}

*key strings
{{tablekeys2|
{{!}}'''samples'''
{{!}}'''samples''': ''100000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the total number of samples to draw
{{!}}-
{{!}}'''burnin'''
{{!}}'''burnin''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}0
{{!}}provides the number of samples to be discarded as burnin
{{!}}-
{{!}}'''chains'''
{{!}}'''chains''': ''10''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}1
{{!}}provides the number of parallel chains to run
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''trace'''
{{!}}optional
{{!}}word
{{!}}'''trace'''
{{!}}none
{{!}}changes sampler from sampling prediction error variances to sampling traces required for emreml
}}

=<'''solvers'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,b,..
...
</solvers>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}optional
{{!}}hosts one to several elements each containing information about a specific solver
}}

content:
*key strings
{{tablekeys2|
{{!}}'''solvers'''
{{!}}'''solvers''': ''a''
{{!}}compulsory
{{!}}csv word-list
{{!}}''solver names''
{{!}}none
{{!}}list content determines nominated-compulsory elements
}}
*conditional-compulsory elements

==<''solver name''>==

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,..
<a>
..
</a>
</solvers>
</root>
</syntaxhighlight>
{{!}}'''solvers'''
{{!}}conditional-compulsory
{{!}}hosts one of several mutually exclusive elements defining the type of solver ''solver name''
}}

content:
*compulsory mutually exclusive elements with default element
**'''<pcgiod>''', default
**'''<direct>'''

===<'''pcgiod'''>===

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,..
<a>
<pcgiod>
rounds: 1000
conv: -20.0
</pcgiod>
</a>
</solvers>
</root>
</syntaxhighlight>
{{!}}''solver name''
{{!}}compulsory
{{!}}defines parameters of a solver of type '''pcgiod'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''rounds'''
{{!}}'''rounds''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the maximum number of rounds to run
{{!}}-
{{!}}'''conv'''
{{!}}'''conv''': ''-15.0''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}} -18.42
{{!}}provides the convergence threshold
{{!}}-
{{!}}'''convtype'''
{{!}}'''convtype''': '''cd'''
{{!}}optional
{{!}}word
{{!}}'''cr<nowiki>|</nowiki>cd'''
{{!}} '''cr'''
{{!}}provides the convergence parameter type
}}

===<'''direct'''>===

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,..
<a>
<direct>
</direct>
</a>
</solvers>
</root>
</syntaxhighlight>
{{!}}''solver name''
{{!}}compulsory
{{!}}defines parameters of a solver of type '''direct'''
}}

content: no content defined

Parameter file elements

2022-06-07T04:52:56Z

127.0.0.1: /* mcemreml> */

Below is a list of all possible parameter file xml elements. For each element an example is provided as well as information about the element's host element, the element's type and the element's content. '''Note that all words(element names, key string words, key string variables) in bold are hard-coded, all in italic are user-defined (this does not apply to the example box)'''. The spelling of hard-coded words must be abide by, the spelling of user-defined words is user-defined.

=<'''model'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<model>
<eqn attribute="strings">
..
</eqn>
<poly attribute="strings">
..
</poly>
</model>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}compulsory
{{!}}hosts information about the equations and the polynomials.
}}

content:

*compulsory element '''<eqn attributes="strings">'''
*optional element '''<poly attributes="strings">'''
==<'''eqn'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<model>
<eqn attribute="strings">
y1=x*b1+z*u1(v(g(1))
y2=x*b2+z*u2(v(g(2))
y3=x*b3+a(t(co(p(1,2);n(k))))*c1+z*u3(v(g(3)))
</eqn>
..
</model>
</root>
</syntaxhighlight>
{{!}}'''model'''
{{!}}compulsory
{{!}}hosts information about the equations.
}}

content:

*[[linear mixed models in lmt#Model_syntax|model strings]] which are escaped from the formatting rules by adding '''attributes="strings"''' to the start tag.

==<'''poly'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<model>
<poly attribute="strings">
x^0
x^2
3*x^2+sqrt(sin(x))
</poly>
..
</model>
</root>
</syntaxhighlight>
{{!}}'''model'''
{{!}}optional
{{!}}hosts user defined polynomials and references to hard-coded polynomials. Note that there can only be one polynomial per line. Model strings will reference polynomials by their line number.
}}

content

*[[linear mixed models in lmt#Polynomials|polynomial strings]] which are escaped from the formatting rules by adding '''attributes="strings"''' to the start tag.

=<'''pedigrees'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<pedigrees>
pedigrees: a,b
...
</pedigrees>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}automatic-optional
{{!}}hosts one to several elements each containing information about a specific pedigree}}

content:
*key strings
{{tablekeys2|
{{!}}'''pedigrees'''
{{!}}'''pedigrees''': ''a,b''
{{!}}compulsory
{{!}}csv word-list
{{!}}''pedigree names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements}}
*nominated-compulsory elements
==<''pedigree name''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<pedigrees>
pedigrees: myped
..
<myped>
file: myped.csv
switch: selfing
phantomparents: 2
qfile: myq.coocsv
</myped>
..
</pedigrees>
</root>
</syntaxhighlight>
{{!}}'''pedigrees'''
{{!}}nominated-compulsory
{{!}}hosts information about a specific pedigree identified by ''pedigree name''
}}
content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''myped.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}list content determines the name of the file containing the pedigree
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''selfing'''
{{!}}optional
{{!}}csv-word-list
{{!}}'''selfing,probabilistic'''
{{!}}none
{{!}}list content determines pedigree properties.
*'''selfing''': both parents can have the same id
*'''probabilistic''': each individual can have more than 1 pair of parents
{{!}}-
{{!}}'''phantomparents'''
{{!}}'''phantomparents''': 2
{{!}}optional
{{!}}single numeric value
{{!}}positive integer
{{!}}none
{{!}}integer number determines the number of individuals at the top of the pedigree which are phantom parents
{{!}}-
{{!}}'''qfile'''
{{!}}'''qfile''': myq.coocsv
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}provides name of file to which the genetic regression matrix should be written. Supported file name suffixes are ".bin" for binary block file, ".blkcsv" for csv blockfile and ".coocsv" for csv coordinate format.
{{!}}-
{{!}}'''metafile'''
{{!}}'''metafile''': meta.csv
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}provides name of the file containing the metafounder co-variance matrix.
}}

=<'''genotypes'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<genotypes>
genotypes: a,b
...
</genotypes>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}automatic-optional
{{!}}hosts one to several elements each containing information about different sets of genotypes
}}

content:
*key strings
{{tablekeys2|
{{!}}'''genotypes'''
{{!}}'''genotypes''': ''a,b''
{{!}}compulsory
{{!}}csv word-list
{{!}}''genotype names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements
}}
*nominated-compulsory elements
==<''genotype name''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<genotypes>
genotypes: mygn
..
<mygn>
file: genotypes.txt
pedigree: myped
cross: crossref.csv
</mygn>
..
</genotypes>
</root>
</syntaxhighlight>
{{!}}'''genotypes'''
{{!}}nominated-compulsory
{{!}}hosts information about a specific set of genotypes identified by ''genotype name''
}}
content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''genotype.txt''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the genotypes
{{!}}-
{{!}}'''cross'''
{{!}}'''cross''': ''mycross.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the pedigree ids related to the genotypes
{{!}}-
{{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}optional
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree previously invoked pedigree related to the content of the cross-reference file
{{!}}-
{{!}}'''pqfile'''
{{!}}'''pqfile''': ''mypq.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the allele frequencies. Note that the file content is used as a substitute for the column means of the marker matrix. It must therefore contain 2p.
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''ignorefixed'''
{{!}}optional
{{!}}csv word-list
{{!}}'''ignorefixed,ignoremissing'''
{{!}}none
{{!}}
*ignorefixed: fixed markers are ignored '''but may lead to program crash or spurious results latter on'''
*ignoremissing: marker coded as missing(3) are set to 0.
}}

=<'''grms'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<grms>
grms: a,b
...
</grms>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}automatic-optional
{{!}}hosts one to several elements each containing information about a specific grm
}}

content:
*key strings
{{tablekeys2|
{{!}}'''grms'''
{{!}}'''grms''': ''x,y''
{{!}}compulsory
{{!}}csv word-list
{{!}}''grm names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements
}}
*nominated-compulsory elements
==<''grm name''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<grms>
grms: mygrm
..
<mygrm>
genotype: mygn
method: YA
</mygrm>
..
</genotypes>
</root>
</syntaxhighlight>
{{!}}'''grms'''
{{!}}nominated-compulsory
{{!}}hosts information about a specific grm identified by ''grm name''
}}
content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''mygrm.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the grm. mutually exclusive with keyword '''genotype'''.
{{!}}-
{{!}}'''genotype'''
{{!}}'''genotype''': ''mygn''
{{!}}compulsory
{{!}}word
{{!}}''genotype name''
{{!}}none
{{!}}content determines the genotype element to be used for building the grm. mutually exclusive with keyword '''file'''.
{{!}}-
{{!}}'''cross'''
{{!}}'''cross''': ''mycross.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the pedigree ids related to the genotypes. if this information has already been supplied to the genotypes it cannot be supplied here.
{{!}}-
{{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}optional
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree previously invoked pedigree related to the content of the cross-reference file. if this information has already been supplied to the genotypes it cannot be supplied here.
{{!}}-
{{!}}'''method'''
{{!}}'''method''':'''YA'''
{{!}}optional
{{!}}alternative words
{{!}}'''VR<nowiki>|</nowiki>YA'''
{{!}}'''VR'''
{{!}}content determines the method to be used for building a grm from genotypes
*'''VR''': VanRaden Method 1 is used
*'''YA''': VanRaden Method 2(method Yang) is used
{{!}}-
{{!}}'''outfile'''
{{!}}'''outfile''': ''mygrm.bin''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file where the grm should be written to. will only take effect if the grm was build from genotypes. if the genotypes had a pedigree assigned a cross-reference file will be written out as well which contains the original pedigree ids of the genotyped individuals in the order of the rows/columns of the grm. the file name of the cross-reference file is that of the grm with the prefix '''cross_'''.
}}

=<'''vars'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
vars: g,p
...
</vars>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}compulsory
{{!}}hosts one to several elements each containing information about a specific variance.
}}

content:
*key strings
{{tablekeys2|
{{!}}'''vars'''
{{!}}'''vars''': ''g,p''
{{!}}compulsory
{{!}}csv word-list
{{!}}''variance names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements
}}
*nominated-compulsory elements
*compulsory element '''<res>'''
=='''Kronecker products'''==
Variance structures below are Kronecker products $$\Gamma \otimes \Sigma$$. If no '''type''' keystring is provided this is the default.
==='''<res>'''===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
<res>
<sigma>
..
</sigma>
</res>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''vars'''
{{!}}compulsory
{{!}}hosts information about the residual variance structure.
}}

content:
*compulsory element [[#<sigma>|'''<sigma>''']]
*optional element [[#<gamma>|'''<gamma>''']]

===''<variance name>''===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
..
</sigma>
<gamma>
..
</gamma>
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''vars'''
{{!}}nominated-compulsory
{{!}}hosts information about variance structure identified by ''variance name''.
}}

content:
*compulsory element [[#<sigma>|'''<sigma>''']]
*optional element [[#<gamma>|'''<gamma>''']]

*key strings
{{tablekeys2|
1={{!}}'''type'''
{{!}}'''type''': ''kronecker''
{{!}}optional
{{!}}word
{{!}}''kronecker,snpblup_1''
{{!}}kronecker
{{!}}determines whether the variance structure deviates from a Kronecker product.
}}

===='''<sigma>'''====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
..
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''variance name''
{{!}}compulsory
{{!}}hosts information about $$\Sigma$$ as part of [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]].
}}

content:

*key strings
{{tablekeys2|
1={{!}}'''file'''
{{!}}'''file''': ''mymatrix.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the $$\Sigma$$ matrix. is mutually exclusive with '''<nowiki><matrix attributes="array"></nowiki>'''.
{{!}}-
{{!}}'''type'''
{{!}}'''type''': '''block'''
{{!}}optional
{{!}}word
{{!}}'''block'''
{{!}}none
{{!}}determines that $$\Sigma$$ is equal to [[Supported_features#Supported_variance_structures|$$\Theta$$]]
{{!}}-
{{!}}'''scale'''
{{!}}'''scale''': ''0.05''
{{!}}optional
{{!}}single numeric value
{{!}}real number>0.0
{{!}}none
{{!}}multiplies $$\Sigma$$ once by the provided value after reading.
{{!}}-
{{!}}'''priordf'''
{{!}}'''priordf''': ''10''
{{!}}optional
{{!}}single numeric value
{{!}}real number>=0.0
{{!}}0.0
{{!}}prior degree of freedom when doing Gibbs sampling
{{!}}-
{{!}}'''maskfile'''
{{!}}'''maskfile''': ''mymatrixmask.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing a T/F matrix of the same dimension as the respective $$\Sigma$$ matrix. Is mutually exclusive with '''<nowiki><maskmatrix attributes="array"></nowiki>'''.
}}

*optional element '''<matrix attributes="array">'''
=====<'''matrix attributes="array"'''>=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
<matrix attributes="array">
5.0,0.5
0.5,1.8
</matrix>
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''sigma'''
{{!}}optional
{{!}}hosts the content of a single $$\Sigma$$ matrix. Is mutually exclusive with key string '''file: '''.
}}
=====<'''maskmatrix attributes="array"'''>=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
<maskmatrix attributes="array">
T,F
F,T
</matrix>
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''sigma'''
{{!}}optional
{{!}}hosts the content of a single indicator matrix of the same dimensions as the respective $$\Sigma$$ matrix. Is mutually exclusive with key string '''maskfile: '''.
}}

===='''<gamma>'''====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
..
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''variance name''
{{!}}optional
{{!}}hosts information about $$\Gamma$$ as part of [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]]. If absent $$\Gamma$$ defaults to $$I$$.
}}

content:

*mutually exclusive elements '''<A>, <H>, <G> and <E>'''

====='''<A>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<A>
pedigree: myped
</A>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma$$ being constructed as the numerator relationship matrix A using pedigree ''pedigree name''.
}}

content:
*key strings
{{tablekeys2|
{{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}optional
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree previously invoked to be used to construct A.
{{!}}-
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''gg'''
{{!}}optional
{{!}}csv word-list
{{!}}'''gg'''
{{!}}none
{{!}}
*gg: the pedigree contains genetic groups which will be fitted as random
}}

====='''<H>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<H>
type: tblup
pedigree: myped
genotype: mygn
aweight: 0.05
switch: adjustg2a
</H>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma$$ being constructed as combined single step relationship matrix H using pedigree ''pedigree name'' and genomic information. the genomic information can be supplied
*via a grm element for single step H-BLUP models
*via a genotype element for single step T-BLUP models
Note that for '''type:tblup''' it is not necessary to have an automatic-optional [[#<grms>|<grms>]] element in the parameter file. Doing so will cause the construction and RAM-storage of $$G$$ although it is not need for building H, thus maybe leading to substantial increase in processing time and RAM demand.
}}

content:
*key strings
{{tablekeys2|
1={{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}compulsory
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree element to be used to construct H.
{{!}}-
{{!}}'''type'''
{{!}}'''type''': '''tblup'''
{{!}}optional
{{!}}word
{{!}}'''tblup<nowiki>|</nowiki>gblup'''
{{!}}'''gblup'''
{{!}}content determines the way the inverse of H is constructed.
{{!}}-
{{!}}'''grm'''
{{!}}'''grm''': ''mygrm''
{{!}}conditional-compulsory
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the grm element to be used to construct H. compulsory for '''type: hblup'''.
{{!}}-
{{!}}'''genotype'''
{{!}}'''genotype''': ''mygn''
{{!}}conditional-compulsory
{{!}}word
{{!}}''genotype name''
{{!}}none
{{!}}content determines the genotype element to be used to construct H. compulsory for '''type: tblup'''.
{{!}}-
{{!}}'''aweight'''
{{!}}'''aweight: 0.05'''
{{!}}optional
{{!}}single numeric value
{{!}}0.0<=aweight<=1.0
{{!}}0.0
{{!}}blending of $$G$$ with $$A_{gg}$$ by $$G_w=aweight\times A_{gg}+(1-aweight)\times G$$
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''adjustg2a'''
{{!}}optional
{{!}}csv word-list
{{!}}'''adjustg2a,gg,diag'''
{{!}}none
{{!}}
*adjustg2a: adjustment of $$G$$ towards $$A_{gg}$$ using method
*gg: the pedigree contains genetic groups which will be fitted as random
*diag: calculate H diagonal elements and write to file (only supported for gblup).
{{!}}-
{{!}}'''grmdadd'''
{{!}}'''grmdadd''': ''0.05''
{{!}}optional
{{!}}single numeric value
{{!}}real number >=0.0
{{!}}none
{{!}} value added to the diagonal of $$G$$ to ensure invertibility. The policy is
*if '''aweight'''>0.0, nothing will be added to the diagonals
*if '''aweight''' is not supplied or is zero:
** if '''grmdadd''' is not supplied 0.001 will be added to the diagonals
** otherwise '''grmdadd''' will be used
}}

====='''<G>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<G>
grm: mygrm
</G>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma$$ being constructed from a genomic relationsship matrix.
}}

content:
*key strings
{{tablekeys2|
1={{!}}'''grmdadd'''
{{!}}'''grmdadd''': ''0.05''
{{!}}optional
{{!}}single numeric value
{{!}}real number >=0.0
{{!}}none
{{!}} value added to the diagonal of $$G$$ to ensure invertibility.
}}

====='''<E>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<E>
file: mygamma.csv
</E>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma^{-1}$$ being uploaded from a file.
}}

content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''mygamma.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the file which contains $$\Gamma^{-1}$$.
{{!}}-
{{!}}'''type'''
{{!}}'''type''': '''dense'''
{{!}}optional
{{!}}word
{{!}}'''dense<nowiki>|</nowiki>sparse_csr_ut'''
{{!}}'''sparse_csr_ut'''
{{!}}content determines the file storage of $$\Gamma^{-1}$$
*dense: full squared symmetric matrix
*sparse_csr_ut: squared symmetric sparse upper triangular matrix in [https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_row_(CSR,_CRS_or_Yale_format) csr] format
}}

=='''snpblup1'''==

===''<variance name>''===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
genotype: mygn
aweight: 0.05
switch: adjustg2a
<sigma>
..
</sigma>
<gamma>
..
</gamma>
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''vars'''
{{!}}nominated-compulsory
{{!}}hosts information about variance structure identified by ''variance name''.
}}

content:
*compulsory element '''<sigma>'''
*compulsory element [[#<marker_sb1>|'''<marker_sb1>''']]

*key strings
{{tablekeys2|
1={{!}}'''type'''
{{!}}'''type''': ''kronecker''
{{!}}optional
{{!}}word
{{!}}''kronecker,snpblup_1''
{{!}}kronecker
{{!}}determines whether the variance structure deviates from a Kronecker product.
{{!}}-
{{!}}'''genotype'''
{{!}}'''genotype''': ''mygn''
{{!}}conditional-compulsory
{{!}}word
{{!}}''genotype name''
{{!}}none
{{!}}content determines the genotype element to be used to construct H. compulsory for '''type: tblup'''.
{{!}}-
{{!}}'''aweight'''
{{!}}'''aweight: 0.05'''
{{!}}optional
{{!}}single numeric value
{{!}}0.0<=aweight<=1.0
{{!}}0.0
{{!}}blending of $$G$$ with $$A_{gg}$$ by $$G_w=aweight\times A_{gg}+(1-aweight)\times G$$
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''adjustg2a'''
{{!}}optional
{{!}}csv word-list
{{!}}'''adjustg2a,gg,diag'''
{{!}}none
{{!}}
*adjustg2a: adjustment of $$G$$ towards $$A_{gg}$$ using method
*gg: the pedigree contains genetic groups which will be fitted as random
*diag: calculate H diagonal elements and write to file (only supported for gblup).
}}

===='''<sigma>'''====

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
<sigma>
..
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''variance name''
{{!}}compulsory
{{!}}hosts information about $$\Sigma$$ for the poly-genetic part of the variance structure.
}}

content:

see [[#<sigma>|'''<sigma''']]

===='''<marker_sb1>'''====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
..
<marker_sb1>
..
</marker_sb1>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''marker''
{{!}}compulsory
{{!}}hosts information about the co-variance between and within markers following [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]].
}}

content:

*compulsory element '''<sigma>'''
*optional element '''<gamma>'''

====='''<sigma>'''=====

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
..
<marker_sb1>
<sigma>
..
</sigma>
..
</marker_sb1>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''marker''
{{!}}compulsory
{{!}}hosts information about $$\Sigma$$ as part of [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]] for the marker part of the variance structure. Note that $$\Sigma$$ will be scaled by (1-aweight).
}}

see [[#<sigma>|'''<sigma>''']]

=<'''jobs'''>=

{{tableele2|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: solve,yh
...
</jobs>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}optional
{{!}}hosts one to several elements each containing information about a specific job
{{!}}run default job(solve) in default parameterization(default pcgiod parameterization)
}}

content:
*key strings
{{tablekeys2|
{{!}}'''jobs'''
{{!}}'''jobs''': '''solve,yhat'''
{{!}}compulsory
{{!}}csv word-list
{{!}}'''solve,sample,pevsample,mcemreml,yhat'''
{{!}}none
{{!}}job sequence is determined by the list sequence. list content determines nominated-compulsory elements
}}

*nominated-compulsory elements
**'''<default>'''
**'''<solve>'''
**'''<sample>'''
**'''<pevsample>'''
**'''<pevsolve>'''
**'''<mcemreml>'''
**'''<airemlc>'''
**'''<yhat>'''

==<'''default'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
..
<default>
conv: -18.42
</default>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''default'''
}}

content: see [[#<pcgiod>|<pcgiod>]] for a list of all possible key strings

==<'''solve'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
..
<solve>
solver: mysolver
</solve>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''solve'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''solver'''
{{!}}'''solver''': ''mysolver''
{{!}}compulsory
{{!}}word
{{!}}''solver name''
{{!}}none
{{!}}''solver name'' must be the name of a previously defined solver
}}

==<'''sample'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: sample,..
<sample>
sampler: mysampler
</sample>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''sample'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''sampler'''
{{!}}'''sampler''': ''mysampler''
{{!}}compulsory
{{!}}word
{{!}}''sampler name''
{{!}}none
{{!}}''sampler name'' must be the name of a previously defined sampler
}}

==<'''pevsample'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: pevsample,..
<pevsample>
sampler: mysampler
</pevsample>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''pevsample'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''sampler'''
{{!}}'''sampler''': ''mysampler''
{{!}}compulsory
{{!}}word
{{!}}''sampler name''
{{!}}none
{{!}}''sampler name'' must be the name of a previously defined sampler of type pev
}}

==<'''pevsolve'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: pevsolve,..
<pevsolve>
solver: mysolver
</pevsolver>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''pevsolve'''
}}

content:

*key strings
{{tablekeys2|
1={{!}}'''solver'''
{{!}}'''solver''': ''mysolver''
{{!}}compulsory
{{!}}word
{{!}}''solver name''
{{!}}none
{{!}}''solver name'' must be the name of a previously defined solver
{{!}}-
{{!}}'''factor'''
{{!}}'''factor''': ''gen''
{{!}}compulsory
{{!}}word
{{!}}''factor name''
{{!}}none
{{!}}''factor name'' must be the name of a random factor
{{!}}-
{{!}}'''levels'''
{{!}}'''levels''': ''5,10,20''
{{!}}optional
{{!}}csv integer list
{{!}}''factor level ids''
{{!}}none
{{!}}original factor level ids(.e.g. pedigree ids etc). If not supplied the prediction error co-variance blocks of all factor levels associated to the nominated factor will be calculated. Mutually exclusive with '''levelfile'''.
{{!}}-
{{!}}'''levelfile'''
{{!}}'''levelfile''': ''myfile.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}file containing original factor level ids(.e.g. pedigree ids etc). If not supplied the prediction error co-variance blocks of all factor levels associated to the nominated factor will be calculated. Mutually exclusive with '''levels'''.
{{!}}-
{{!}}'''nrhs'''
{{!}}'''nrhs''': ''50''
{{!}}optional
{{!}}integer
{{!}}''number of right-hand sides''
{{!}}1000
{{!}}number of right-hand-sides to be solved for simultaneously. Has only effect if the direct solver is used. The default may exceed the available RAM.
}}

==<'''airemlc'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: airemlc,..
<airemlc>
rounds: 50
..
</airemlc>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''airemlc'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''rounds'''
{{!}}'''rounds''': ''10''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}20
{{!}}provides the number of aireml-rounds to run
{{!}}-
{{!}}'''convtype'''
{{!}}'''convtype''': '''ng'''
{{!}}optional
{{!}}word
{{!}}'''cd<nowiki>|</nowiki>ng<nowiki>|</nowiki>ll<nowiki>|</nowiki>any<nowiki>|</nowiki>all'''
{{!}}'''cd'''
{{!}}provides the convergence criterion to use
* ll: log of relative change in log-likelihood
* ng: log of the norm of the gradient vector
* cd: log of the relative change of the parameter vector
* all: all of the above
* any: any of the above
{{!}}-
{{!}}'''convll'''
{{!}}'''convll''': ''-10.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''-6.907755''
{{!}}provides the convergence threshold for convergence criterion '''ll'''
{{!}}-
{{!}}'''convng'''
{{!}}'''convng''': ''-10.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''-16.1181''
{{!}}provides the convergence threshold for convergence criterion '''ng'''
{{!}}-
{{!}}'''convcd'''
{{!}}'''convcd''': ''-10.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''-16.1181''
{{!}}provides the convergence threshold for convergence criterion '''cd'''
{{!}}-
{{!}}'''nscale'''
{{!}}'''nscale''': ''0.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''1.0''
{{!}}scales the length of the Newton step.
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''residuals'''
{{!}}optional
{{!}}csv word-list
{{!}}any real number
{{!}}'''writeai,residuals,solutions'''
{{!}}
*'''writeai''': write ai matrix and gradient vector to files ai_ai.csv and ai_ja.csv.
*'''residuals''': after convergence write the residuals to file aic_residuals.csv
*'''solutions''': after convergence write the MME solutions to file results.csv
}}

==<'''mcemreml'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: mcemreml,..
<mcemreml>
rounds: 500
sampler: mysampler
solver: mysolver
</mcemreml>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''mcemreml'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''rounds'''
{{!}}'''rounds''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}500
{{!}}provides maximum the number of mcemreml-rounds to run
{{!}}-
{{!}}'''conv'''
{{!}}'''conv''': ''-16.21''
{{!}}optional
{{!}}numeric value
{{!}}real number
{{!}}-6.907755
{{!}}provides the convergence threshold
{{!}}-
{{!}}'''sampler'''
{{!}}'''sampler''': ''mysampler''
{{!}}compulsory
{{!}}word
{{!}}''sampler name''
{{!}}none
{{!}}''sampler name'' must be the name of a previously defined sampler
{{!}}-
{{!}}'''solver'''
{{!}}'''solver''': ''mysolver''
{{!}}compulsory
{{!}}word
{{!}}''solver name''
{{!}}none
{{!}}''solver name'' must be the name of a previously defined solver
}}

==<'''yhat'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: yhat,..
<yhat>
</yhat>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''yhat'''
}}
Currently '''yhat''' has no key strings or nested elements defined.

=<'''samplers'''>=

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,b,..
...
</samplers>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}optional
{{!}}hosts one to several elements each containing information about a specific sampler
}}

content:
*key strings
{{tablekeys2|
{{!}}'''samplers'''
{{!}}'''samplers''': ''a''
{{!}}compulsory
{{!}}csv word-list
{{!}}''sampler names''
{{!}}none
{{!}}list content determines nominated-compulsory elements
}}
*conditional-compulsory elements

==<''sampler name''>==

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
..
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}'''samplers'''
{{!}}conditional-compulsory
{{!}}hosts one of several mutually exclusive elements defining the type of sampler ''sampler name''
}}

content:
*compulsory mutually exclusive elements
**'''<singlepass>'''
**'''<blocked>'''
**'''<pev>'''

===<'''singlepass'''>===

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
<singlepass>
samples: 10000
burnin: 1000
</singlepass>
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}''sampler name''
{{!}}compulsory
{{!}}defines parameters of a sampler of type '''singlepass'''
}}

*key strings
{{tablekeys2|
{{!}}'''samples'''
{{!}}'''samples''': ''100000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the total number of samples to draw
{{!}}-
{{!}}'''burnin'''
{{!}}'''burnin''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}0
{{!}}provides the number of samples to be discarded as burnin
}}

===<'''blocked'''>===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
<blocked>
samples: 10000
burnin: 1000
</blocked>
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}''sampler name''
{{!}}compulsory
{{!}}defines parameters of a sampler of type '''blocked'''
}}

*key strings
{{tablekeys2|
{{!}}'''samples'''
{{!}}'''samples''': ''100000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the total number of samples to draw
{{!}}-
{{!}}'''burnin'''
{{!}}'''burnin''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}0
{{!}}provides the number of samples to be discarded as burnin
}}

===<'''pev'''>===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
<pev>
samples: 10000
burnin: 1000
chains: 10
</pev>
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}''sampler name''
{{!}}compulsory
{{!}}defines parameters of a sampler of type '''pev'''
}}

*key strings
{{tablekeys2|
{{!}}'''samples'''
{{!}}'''samples''': ''100000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the total number of samples to draw
{{!}}-
{{!}}'''burnin'''
{{!}}'''burnin''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}0
{{!}}provides the number of samples to be discarded as burnin
{{!}}-
{{!}}'''chains'''
{{!}}'''chains''': ''10''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}1
{{!}}provides the number of parallel chains to run
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''trace'''
{{!}}optional
{{!}}word
{{!}}'''trace'''
{{!}}none
{{!}}changes sampler from sampling prediction error variances to sampling traces required for emreml
}}

=<'''solvers'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,b,..
...
</solvers>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}optional
{{!}}hosts one to several elements each containing information about a specific solver
}}

content:
*key strings
{{tablekeys2|
{{!}}'''solvers'''
{{!}}'''solvers''': ''a''
{{!}}compulsory
{{!}}csv word-list
{{!}}''solver names''
{{!}}none
{{!}}list content determines nominated-compulsory elements
}}
*conditional-compulsory elements

==<''solver name''>==

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,..
<a>
..
</a>
</solvers>
</root>
</syntaxhighlight>
{{!}}'''solvers'''
{{!}}conditional-compulsory
{{!}}hosts one of several mutually exclusive elements defining the type of solver ''solver name''
}}

content:
*compulsory mutually exclusive elements with default element
**'''<pcgiod>''', default
**'''<direct>'''

===<'''pcgiod'''>===

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,..
<a>
<pcgiod>
rounds: 1000
conv: -20.0
</pcgiod>
</a>
</solvers>
</root>
</syntaxhighlight>
{{!}}''solver name''
{{!}}compulsory
{{!}}defines parameters of a solver of type '''pcgiod'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''rounds'''
{{!}}'''rounds''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the maximum number of rounds to run
{{!}}-
{{!}}'''conv'''
{{!}}'''conv''': ''-15.0''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}} -18.42
{{!}}provides the convergence threshold
{{!}}-
{{!}}'''convtype'''
{{!}}'''convtype''': '''cd'''
{{!}}optional
{{!}}word
{{!}}'''cr<nowiki>|</nowiki>cd'''
{{!}} '''cr'''
{{!}}provides the convergence parameter type
}}

===<'''direct'''>===

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,..
<a>
<direct>
</direct>
</a>
</solvers>
</root>
</syntaxhighlight>
{{!}}''solver name''
{{!}}compulsory
{{!}}defines parameters of a solver of type '''direct'''
}}

content: no content defined

Examples

2022-06-07T04:47:38Z

127.0.0.1: /* Estimating variance components using MC-EM-REML */

The examples provided in this section are meant to provide a practical examples about the {{lmt}} facilities and the parameter file syntax. It is assumed that the reader is familiar with [[Parameterfile1|section]]

== Solving linear mixed model equations ==

=== Estimating a mean in a uni-variate model ===

Estimating a mean is equivalent to obtaining the generalized least square solution $$b=(X'R^{-1}X)^{-1}X'R^{-1}y$$ for model $$y=Xb+e$$, where $$y$$ is a vector of $$n$$ observations, $$X$$ is as single column matrix of $$1$$, $$b$$ is a fixed factor (mean), $$e$$ is the residual and $$y\sim N(Xb,R)$$ where $$R$$ is a $$n \times n$$ co-variance matrix.

From the above it follows that for task of solving for $$b$$ {{lmt}} needs following information:

the data
the residual variance $$R$$
the model
the solver

Assume we have a data file "data.csv" with content:
#y,mu
25.0,1
33.1,1
36.0,1
28.3,1
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records.
A valid {{lmt}} xml parameter file would look like:
<syntaxhighlight lang="xml" line highlight="5,27">
<root>
<models>
<eqn attributes="strings">
y=mu*b
</eqn>
</models>
<data>
datafile: data.csv
missingthreshold: -50.0
</data>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
</vars>
</root>
</syntaxhighlight>

Following the introduced [[Parameterfile1|parameterfile terminology]] tags {{cc|<data>}}, {{cc|<vars>}} and {{cc|<model>}} are automatic-compulsory. Since {{cc|solve}} is the default job and we are using the default solver in default parameterization no further information about the job or solver is required.

The most important aspect is the model definition in tag {{cc|<eqn>}}, nested inside tag {{cc|<model>}} $$y=mu*b$$. The variable names used here are either defined by the data file header, or by the user. That is, $$y$$ and $$mu$$ are defined in the data file header, whereas $$b$$ is a user-defined factor name. Translated this means that the content of the data column named $$y$$ should be regressed on the content of the data column named $$mu$$ with the regression coefficient named $$b$$.

Since there are no further specifications supplied about $$y$$, $$mu$$ and $$b$$, it is assumed that $$y$$ is a continuous variable, $$mu$$ is a classification variable, and $$b$$ is fixed factor.
The necessary variances are defined by the content of the automatic-compulsory tag {{cc|<vars>}}. {{lmt}} requires one compulsory variance, the residual variance, which must be specified via tag {{cc|<res>}}. Therefore tag {{cc|res}} is automatic-compulsory.

The default {{lmt}} variance structure is [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Gamma$$ and $$\Sigma$$ are specified inside tags {{cc|<gamma>}} and {{cc|<sigma>}}, respectively.
However, only tag {{cc|<sigma>}} is [[Parameterfile1#Parsing logic|automatic-compulsory]], whereas tag {{cc|<gamma>}} is [[Parameterfile1#Parsing logic|automatic-optional]]. A missing {{cc|<gamma>}} tag implies that [https://en.wikipedia.org/wiki/Identity_matrix $$\Gamma = I$$]. Note that for {{lmt}} $$\Sigma$$ is always a matrix, that is a scalar $$\sigma^2$$ is treated as a matrix $$1 \times 1$$ matrix.

For the above example, the variance specification inside {{cc|<res>}} implies that $$\Gamma\otimes \Sigma \equiv I\otimes \Sigma$$. Since $$\Sigma$$ is a $$1\times 1$$ matrix with $$\Sigma[1,1]=\sigma_e^2$$, $$R$$ reduces to $$I\sigma_e^2$$.

Note tag {{cc|<matrix>}} nested in tag {{cc|<sigma>}}. The content of tag {{cc|<matrix>}} does not comply with the formatting rules as pointed o ut [[Parameterfile1#Key strings|above]]. That is {{cc|5.0}} is not a valid key string. To let {{lmt}} know that the content of tag {{cc|<matrix>}} should not be evaluated as a key string, with a subsequent error message, [[Parameterfile1#Escaping tag content formatting rules|the tag must have attributes]]. In this example {{cc|1=matrix attributes="matrix"}} escapes the content of tag {{cc|<matrix>}} from the formatting rules.

Further, tag {{cc|<matrix>}} is automatic-optional. This might be confusing because, as pointed out above, $$\Sigma$$ forms an indispensable part of $$\Gamma\otimes \Sigma$$. However, tag {{cc|<matrix>}} belongs to a [[Parameterfile1#Group of mutually exclusive information sources|group of mutually exclusive information sources]] of which members are tag {{cc|<matrix>}} and key string {{cc|file: yourfilename}}. That is, $$\Sigma$$ maybe either embedded in the parameter file or supplied via an external file.

Note that the spelling of most tags used in the above parameter file is determined by {{lmt}} and must be abide by.

=== Estimating a fixed mean and a random genetic effect in a uni-variate model ===

Consider the linear model $$y=Xb+Zu+e$$ where all variables are those declared in [[#Estimating a mean]], $$u$$ is vector of length $$m$$ of random direct genetic effects and $$Z$$ is a design matrix of dimension $$n \times m$$ linking genetic effects to their respective observations. Note that $$u\sim N(0,A\sigma_a^2)$$ where $$A$$ is the pedigree-derived relationship matrix and forms the $$\Gamma$$ part in $$\Gamma\otimes\Sigma$$. A possible data file for such mode may look like:

#y,mu,id
25.0,1,5
33.1,1,6
36.0,1,7
28.3,1,8
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records. Further assume a pedigree in a file called "ped.csv" with content:
1,0,0
2,0,0
3,1,0
4,0,2
5,3,4
6,0,4
7,5,4
8,5,7

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y = mu*b + id*u(v(my_var(1)))
</eqn>
</model>
</root>
</syntaxhighlight>

Compared with the parameter file in example [[#Estimating a mean]] the one above contains only a few extra elements. One this the automatic-optional {{cc|<pedigrees>}} nested inside tag {{cc|<root>}}. This tag contains a keystring {{cc|pedigrees: myped}}, where the user-defined variable behind {{cc|pedigrees:}} is the name of a nominated-compulsory tag nested inside tag {cc|<pedigrees>}}. This concept allows to supply several pedigrees to lmt (e.g. a normal pedigree and a genetic group pedigree). In our example we have only one pedigree named my_ped, with tag {{cc|<my_ped>}} containing the information about this pedigree. Another additional element is the key string {{cc|vars: my_var}} nested in tag {{cc|<vars>}} where the variable of key string {{cc|vars: my_var}} provides the tag names of nominated-compulsory tags, in this example tag {{cc|<my_var>}}.

Tag {{cc|<myvar>}} consist of two structural components: the automatic-compulsory tag {{cc|<sigma>}} and the automatic-optional {{cc|<gamma>}}. Since the the variance of $$u=A\sigma_a^2$$, where $$A=\Gamma$$ and $$\sigma_a^2=\Sigma$$, a {{cc|<gamma>}} tag must be supplied to fully specify the variance. '''Note that if the {{cc|<gamma>}} tag is missing or miss-spelled {{lmt}} will assume that the variance of $$u=I\sigma_a^2$$'''. Tag {{cc|<gamma>}} contains a automatic-compulsory tag {{cc|<A>}} which specifies the $$\Gamma=A$$. Since $$A$$ is build from a pedigree, tag {{cc|<A>}} contains a compulsory key string {{cc|pedigree: my_ped}} which nominates pedigree in tag {{cc|<my_ped>}} to be used for building $$A$$.

Note the difference between the tags {{cc|<sigma>}} nested in tag {{cc|<res>}} and {{cc|<my_var>}}. The former specifies {{cc|<sigma>}} to be provided by tag {{cc|1=<matrix attributes="matrix">}}, whereas the latter specifies {{cc|<sigma>}} to be provided by a file.

The model section in the above parameter file need to communicate to to {{lmt}} that $$u$$ is a random factor with a variance $$A\sigma_a^2$$. This is done by extending the u.d. factor name {{cc|u}} in {{cc|1=y = mu*b + id*u(v(my_var(1)))}} by a specifier {{cc|(v(my_var(1)))}}. Note that without a specifier {{cc|u}} would be regarded as a fixed factor. The specifier {{cc|u(v)}} communicates that {{cc|u}} has a variance assigned. Further, {{cc|v}} has a specifier assigned via {{cc|v(my_var)}} which communicates that the name of the variance is {{cc|my_var}}. The variance in tag {{cc|<my_var>}} contains a {{cc|<gamma>}} and a {{cc|<sigma>}} component. The integer number inside bracket {{cc|my_var(1)}} communicates that $$\sigma_a^2$$ of {{cc|u}} is located in the first diagonal element of $$\Sigma$$.

In summary construct {{cc|u(v(my_var(1)))}} communicates that
*{{cc|u}} has a variance assigned
*the variance is named {{cc|my_var}}
*the variance is located in the first diagonal element of the $$\Sigma$$ matrix specified in tag {{cc|<sigma>}} nested in tag {{cc|<my_var>>}}

=== Estimating fixed means and a random genetic effects in a multi-variate model ===

Consider the linear model

$$
\left(
\begin{array}{c}
y_1 \\
y_2
\end{array}
\right)=
\left(
\begin{array}{cc}
X_1 & 0 \\
0 & X_2 \\
\end{array}
\right)
\left(
\begin{array}{c}
b_1 \\
b_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
Z & 0 \\
0 & Z
\end{array}
\right)
\left(
\begin{array}{c}
u_1 \\
u_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
I & 0 \\
0 & I
\end{array}
\right)
\left(
\begin{array}{c}
e_1 \\
e_2
\end{array}
\right)
$$

where all variables are those declared in [[#Estimating a mean and a random genetic effect in a uni-variate model|above]], and subscripts $$1$$ and $$2$$ index trait $$1$$ and $$2$$, respectively.

Note that $$[u_1,u_2]\sim N([0,0],A\otimes \Sigma_a)$$ where $$A$$ is the pedigree-derived relationship matrix and
$$
\Sigma_a=
\left(\begin{array}{cc}
\sigma_{a_1}^2 & \sigma_{a_1,a_2}\\
\sigma_{a_2,a_1} & \sigma_{a_2}^2
\end{array}\right)
$$
Further, $$[e_1,e_2]\sim N([0,0],I\otimes \Sigma_e)$$ with
$$
\Sigma_e=
\left(\begin{array}{cc}
\sigma_{e_1}^2 & \sigma_{e_1,e_2}\\
\sigma_{e_2,e_1} & \sigma_{e_2}^2
\end{array}\right)
$$.

A possible data file for such mode may look like:
#y1,y2,mu,id
25.0,0.8,1,5
33.1,0.5,1,6
36.0,1.5,1,7
28.3,3.6,1,8
and the pedigree files is that provided in example [[#Estimating a mean and a random genetic effect in a uni-variate model]].

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0,0.8
0.8,1.2
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y1 = mu*b1 + id*u1(v(my_var(1)))
y2 = mu*b2 + id*u2(v(my_var(2)))
</eqn>
</model>
</root>
</syntaxhighlight>

== Example code chunks ==

'''The following code chunks are only subset of a full parameter file. It is assumed that all other parts of the instruction file are functional and all necessary input data are available and the that the data file columns have the respective names.'''

=== Providing pedigrees ===

==== Providing a pedigree containing genetic groups ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
phantomparents: 2
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a pedigree containing metafounders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
metafile: mymeta.csv
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a probabilistic pedigree ====

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<pedigrees>
pedigrees: a
<a>
switch: probabilistic
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing several pedigrees ====

<syntaxhighlight lang="xml">
<root>
...
<pedigrees>
pedigrees: a,b
<a>
...
</a>

...

</pedigrees>
...
</root>
</syntaxhighlight>

=== Providing Genotypes ===

==== Providing external allele frequencies ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
pqfile: mypq.csv 
</a>
</genotypes>
...
</root>
</syntaxhighlight>

==== Providing several genotype files ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
...
</root>
</syntaxhighlight>

=== Providing GRMs ===

==== Constructing GRM from genotypes ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Overriding the default GRM construction method ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
method: YA 
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing a GRM from file ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<grms>
grms: x
<x>
file: mygrm.csv
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing several GRMs ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
...
</root>
</syntaxhighlight>

=== Single step models ===

==== ssGBLUP model with GRM build from genotypes====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGBLUP model with GRM supplied externally ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<grms>
grms: x
<x>
file: mygrm.bin
pedigree: a
cross: id.csv
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGTBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
file: pedigree.csv
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
file: mygeno.txt
pedigree: a
cross: ids.csv
...
</a>
</genotypes>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
type: tblup
genotype: a
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssSNPBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
switch: adjustg2a
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with meta-founders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
metafile: mymeta.csv 
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
pqfile: myp.csv 
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with a separate polygenic factor ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: a,g
<a>
<sigma>
file: cov_polygenic.csv 
</sigma>
<gamma>
<A>
pedigree: a
</A>
</gamma>
</a>
<g>
type: snpblup1
genotype: a
aweight: 0.001 
switch: adjustg2a
<sigma>
file: cov_genomic.csv 
</sigma>
<marker_sb1>
<sigma>
file: cov_genomic.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*ug1(v(g(1))+dam*mg1(v(g(2))+individual*ua1(v(a(1))+dam*ma1(v(a(2))
y2=mu*b2+individual*ug2(v(g(3))+dam*mg2(v(g(4))+individual*ua2(v(a(3))+dam*ma2(v(a(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssGBLUP with two genomic factors ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a,b
<a>
...
pedigree: a
</a>

...
pedigree: a

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
<vars>
...
vars: g1,g2
<g1>
...
<gamma>
<H>
...
grm: x
</H>
</gamma>
</g1>
<g2>
...
<gamma>
<H>
...
grm: y
</H>
</gamma>
</g2>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u11(v(g1(1))+id*u21(v(g2(1))
y2=mu*b2+id*u12(v(g1(2))+id*u22(v(g2(2))
</eqn>
</models>
</root>
</syntaxhighlight>

=== Regression on continuous co-variables ===

==== Linear regression ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co))*age1
y2=mu*b2+age(t(co))*age2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== User-defined polynomial expansion ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
x^1
log(sqrt(x))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Using hard-coded Legendre polynomials ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2,3))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
l0
l1
l2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested co-variables ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
weaningweight=mu*b1+age(t(co(p(1,2);n(sex))))*age
intramuscularfatcontent=mu*b2+weight(t(co(p(1,2);n(sex))))*weight
</eqn>
<eqn attributes="strings">
x^1
x^2
</eqn>
</models>
...
</root>
</syntaxhighlight>

=== Random-regression models ===
==== Nested continuous random co-variables ====

{{cc|days}} is a co-variable which is nested within {{cc|individual}} or {{cc|dam}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(n(individual))))*u1(v(g(1))+days(t(co(n(dam))))*m1(v(g(2))
y2=mu*b2+days(t(co(n(individual))))*u2(v(g(3))+days(t(co(n(dam))))*m2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous random co-variables with polynomial expansion ====

Similar to [[#Nested continuous co-variables|Nested continuous co-variables]] but {{cc|days}} is expanded

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(p(1,2,3);n(dam))))*m1(v(g(4,5,6))
y2=mu*b2+days(t(co(p(1,2,3);n(individual))))*u2(v(g(7,8,9))+days(t(co(p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous co-variables with polynomial expansion and an integer co-variable ====

Similar to [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]], but an additional information {{cc|t(i)}} is provided telling {{lmt}} that {{cc|days}} is actually an integer. While the results do not differ from [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]] {{lmt}} can exploit this information for memory efficiency.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(t(i);p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(t(i);p(1,2,3);n(dam))))*m1(v(g(7,8,9))
y2=mu*b2+days(t(co(t(i);p(1,2,3);n(individual))))*u2(v(g(4,5,6))+days(t(co(t(i);p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials of order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
</root>
</syntaxhighlight>

=== Defining equivalent models with genetic groups ===

Note that in the parameterization provided below [[#Defining a model with absorbed genetic groups|absorbed genetic groups]] and [[#Defining a model with genetic groups as extra factor|genetic groups as extra factor]] must yield the same results. However, only when using {{cc|absorbed genetic groups}} the factor level solutions are the actual breeding values. When modelling genetic groups as an extra factor genetic factor solutions and genetic group factor solutions must be added by the user.

==== Defining a model with absorbed genetic groups ====

Note that the only information necessary is the number of phantom parents '''at the top of the pedigree'''({{cc|phantomparents: 10}}) and the information to the variance that the it should be constructed allowing for genetic groups({{cc|switch gg}}).

<syntaxhighlight lang="xml" line highlight="6,19">
<root>
<pedigrees>
pedigrees: a
<a>
file: myped.csv
phantomparents: 10
</a>
<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: a
switch: gg
</A>
</gamma>
</g>
</vars>
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Defining a model with genetic groups as extra random factor ====

Genetic groups are defined as an extra factor, which requires an extra variance({{cc|gg}}) and two pedigrees, the genetic group pedigree({{cc|a}}) and the normal pedigree({{cc|b}}). For a model equivalent to [[#Defining a model with absorbed genetic groups|absorption]] pedigree {{cc|b}} must be a subset of pedigree {{cc|a}}. Further, if breeding values are required {{lmt}} can provide the genetic group regression matrix {{cc|qfile: Q.coocsv}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g,gg
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
<gg>
<sigma>
file: myG.csv <! must contain a 4x4 matrix. should be the same as for "g">
</sigma>
</gg>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1(v(gg(1))+dam(t(gg(a)))*damgg1(v(gg(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2(v(gg(2))+dam(t(gg(a)))*damgg2(v(gg(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== Defining a model with fixed genetic groups ====

Fixed genetic groups are only supported if modeled as an extra factor. Therefore, the model is similar to [[#Defining a model with genetic groups as extra random factor|above]], but the extra variance is omitted. Note that when modeling genetic groups as fixed it is the users responsibility to omit one group from the respective pedigree to ensure that $$X$$ is of full column rank. [[#Linear models in lmt:Column rank of $$X$$|bla]]

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1+dam(t(gg(a)))*damgg1
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2+dam(t(gg(a)))*damgg2
</eqn>
</models>
</root>
</syntaxhighlight>

=== Override the default job parameters ===

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<jobs>
jobs: default
<default>
conv: -9.21 <! log(10e-5)>
</default>
</jobs>
...
</root>
</syntaxhighlight>

=== Use job "solve" instead of "default" ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>

</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Use a direct solver in stead of the default solver ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>
<direct>
</direct>
</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using Gibbs sampling ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: sample
<sample>
sampler: x
</sample>
</jobs>
<samplers>
samplers: x
<x>
<blocked>
samples: 100000
</blocked>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using MC-EM-REML ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: mcemreml
<mcemreml>
conv: -9.21034
rounds: 300
sampler: x
solver: y
</mcemreml>
</jobs>
<solvers>
solvers: y
<y>
<pcgiod>
conv: -16.1181
</pcgiod>
</y>
</solvers>
<samplers>
samplers: x
<x>
<pe>
samples: 50
switch: trace
chains: 36
</pe>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using AI-REML-C ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: airemlc
<airemlc>
</airemlc>
</jobs>
...
</root>
</syntaxhighlight>

=== Calculating exact prediction error co-variances using a direct solver===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>
<direct>
</direct>
</a>
</solvers>
...
</root>
</syntaxhighlight>

=== Calculating prediction error co-variances for a target individual===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
levels: 1156679414 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>

</a>
</solvers>
...
</root>
</syntaxhighlight>

Examples

2022-06-07T04:43:45Z

127.0.0.1: /* Estimating variance components using Gibbs sampling */

The examples provided in this section are meant to provide a practical examples about the {{lmt}} facilities and the parameter file syntax. It is assumed that the reader is familiar with [[Parameterfile1|section]]

== Solving linear mixed model equations ==

=== Estimating a mean in a uni-variate model ===

Estimating a mean is equivalent to obtaining the generalized least square solution $$b=(X'R^{-1}X)^{-1}X'R^{-1}y$$ for model $$y=Xb+e$$, where $$y$$ is a vector of $$n$$ observations, $$X$$ is as single column matrix of $$1$$, $$b$$ is a fixed factor (mean), $$e$$ is the residual and $$y\sim N(Xb,R)$$ where $$R$$ is a $$n \times n$$ co-variance matrix.

From the above it follows that for task of solving for $$b$$ {{lmt}} needs following information:

the data
the residual variance $$R$$
the model
the solver

Assume we have a data file "data.csv" with content:
#y,mu
25.0,1
33.1,1
36.0,1
28.3,1
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records.
A valid {{lmt}} xml parameter file would look like:
<syntaxhighlight lang="xml" line highlight="5,27">
<root>
<models>
<eqn attributes="strings">
y=mu*b
</eqn>
</models>
<data>
datafile: data.csv
missingthreshold: -50.0
</data>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
</vars>
</root>
</syntaxhighlight>

Following the introduced [[Parameterfile1|parameterfile terminology]] tags {{cc|<data>}}, {{cc|<vars>}} and {{cc|<model>}} are automatic-compulsory. Since {{cc|solve}} is the default job and we are using the default solver in default parameterization no further information about the job or solver is required.

The most important aspect is the model definition in tag {{cc|<eqn>}}, nested inside tag {{cc|<model>}} $$y=mu*b$$. The variable names used here are either defined by the data file header, or by the user. That is, $$y$$ and $$mu$$ are defined in the data file header, whereas $$b$$ is a user-defined factor name. Translated this means that the content of the data column named $$y$$ should be regressed on the content of the data column named $$mu$$ with the regression coefficient named $$b$$.

Since there are no further specifications supplied about $$y$$, $$mu$$ and $$b$$, it is assumed that $$y$$ is a continuous variable, $$mu$$ is a classification variable, and $$b$$ is fixed factor.
The necessary variances are defined by the content of the automatic-compulsory tag {{cc|<vars>}}. {{lmt}} requires one compulsory variance, the residual variance, which must be specified via tag {{cc|<res>}}. Therefore tag {{cc|res}} is automatic-compulsory.

The default {{lmt}} variance structure is [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Gamma$$ and $$\Sigma$$ are specified inside tags {{cc|<gamma>}} and {{cc|<sigma>}}, respectively.
However, only tag {{cc|<sigma>}} is [[Parameterfile1#Parsing logic|automatic-compulsory]], whereas tag {{cc|<gamma>}} is [[Parameterfile1#Parsing logic|automatic-optional]]. A missing {{cc|<gamma>}} tag implies that [https://en.wikipedia.org/wiki/Identity_matrix $$\Gamma = I$$]. Note that for {{lmt}} $$\Sigma$$ is always a matrix, that is a scalar $$\sigma^2$$ is treated as a matrix $$1 \times 1$$ matrix.

For the above example, the variance specification inside {{cc|<res>}} implies that $$\Gamma\otimes \Sigma \equiv I\otimes \Sigma$$. Since $$\Sigma$$ is a $$1\times 1$$ matrix with $$\Sigma[1,1]=\sigma_e^2$$, $$R$$ reduces to $$I\sigma_e^2$$.

Note tag {{cc|<matrix>}} nested in tag {{cc|<sigma>}}. The content of tag {{cc|<matrix>}} does not comply with the formatting rules as pointed o ut [[Parameterfile1#Key strings|above]]. That is {{cc|5.0}} is not a valid key string. To let {{lmt}} know that the content of tag {{cc|<matrix>}} should not be evaluated as a key string, with a subsequent error message, [[Parameterfile1#Escaping tag content formatting rules|the tag must have attributes]]. In this example {{cc|1=matrix attributes="matrix"}} escapes the content of tag {{cc|<matrix>}} from the formatting rules.

Further, tag {{cc|<matrix>}} is automatic-optional. This might be confusing because, as pointed out above, $$\Sigma$$ forms an indispensable part of $$\Gamma\otimes \Sigma$$. However, tag {{cc|<matrix>}} belongs to a [[Parameterfile1#Group of mutually exclusive information sources|group of mutually exclusive information sources]] of which members are tag {{cc|<matrix>}} and key string {{cc|file: yourfilename}}. That is, $$\Sigma$$ maybe either embedded in the parameter file or supplied via an external file.

Note that the spelling of most tags used in the above parameter file is determined by {{lmt}} and must be abide by.

=== Estimating a fixed mean and a random genetic effect in a uni-variate model ===

Consider the linear model $$y=Xb+Zu+e$$ where all variables are those declared in [[#Estimating a mean]], $$u$$ is vector of length $$m$$ of random direct genetic effects and $$Z$$ is a design matrix of dimension $$n \times m$$ linking genetic effects to their respective observations. Note that $$u\sim N(0,A\sigma_a^2)$$ where $$A$$ is the pedigree-derived relationship matrix and forms the $$\Gamma$$ part in $$\Gamma\otimes\Sigma$$. A possible data file for such mode may look like:

#y,mu,id
25.0,1,5
33.1,1,6
36.0,1,7
28.3,1,8
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records. Further assume a pedigree in a file called "ped.csv" with content:
1,0,0
2,0,0
3,1,0
4,0,2
5,3,4
6,0,4
7,5,4
8,5,7

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y = mu*b + id*u(v(my_var(1)))
</eqn>
</model>
</root>
</syntaxhighlight>

Compared with the parameter file in example [[#Estimating a mean]] the one above contains only a few extra elements. One this the automatic-optional {{cc|<pedigrees>}} nested inside tag {{cc|<root>}}. This tag contains a keystring {{cc|pedigrees: myped}}, where the user-defined variable behind {{cc|pedigrees:}} is the name of a nominated-compulsory tag nested inside tag {cc|<pedigrees>}}. This concept allows to supply several pedigrees to lmt (e.g. a normal pedigree and a genetic group pedigree). In our example we have only one pedigree named my_ped, with tag {{cc|<my_ped>}} containing the information about this pedigree. Another additional element is the key string {{cc|vars: my_var}} nested in tag {{cc|<vars>}} where the variable of key string {{cc|vars: my_var}} provides the tag names of nominated-compulsory tags, in this example tag {{cc|<my_var>}}.

Tag {{cc|<myvar>}} consist of two structural components: the automatic-compulsory tag {{cc|<sigma>}} and the automatic-optional {{cc|<gamma>}}. Since the the variance of $$u=A\sigma_a^2$$, where $$A=\Gamma$$ and $$\sigma_a^2=\Sigma$$, a {{cc|<gamma>}} tag must be supplied to fully specify the variance. '''Note that if the {{cc|<gamma>}} tag is missing or miss-spelled {{lmt}} will assume that the variance of $$u=I\sigma_a^2$$'''. Tag {{cc|<gamma>}} contains a automatic-compulsory tag {{cc|<A>}} which specifies the $$\Gamma=A$$. Since $$A$$ is build from a pedigree, tag {{cc|<A>}} contains a compulsory key string {{cc|pedigree: my_ped}} which nominates pedigree in tag {{cc|<my_ped>}} to be used for building $$A$$.

Note the difference between the tags {{cc|<sigma>}} nested in tag {{cc|<res>}} and {{cc|<my_var>}}. The former specifies {{cc|<sigma>}} to be provided by tag {{cc|1=<matrix attributes="matrix">}}, whereas the latter specifies {{cc|<sigma>}} to be provided by a file.

The model section in the above parameter file need to communicate to to {{lmt}} that $$u$$ is a random factor with a variance $$A\sigma_a^2$$. This is done by extending the u.d. factor name {{cc|u}} in {{cc|1=y = mu*b + id*u(v(my_var(1)))}} by a specifier {{cc|(v(my_var(1)))}}. Note that without a specifier {{cc|u}} would be regarded as a fixed factor. The specifier {{cc|u(v)}} communicates that {{cc|u}} has a variance assigned. Further, {{cc|v}} has a specifier assigned via {{cc|v(my_var)}} which communicates that the name of the variance is {{cc|my_var}}. The variance in tag {{cc|<my_var>}} contains a {{cc|<gamma>}} and a {{cc|<sigma>}} component. The integer number inside bracket {{cc|my_var(1)}} communicates that $$\sigma_a^2$$ of {{cc|u}} is located in the first diagonal element of $$\Sigma$$.

In summary construct {{cc|u(v(my_var(1)))}} communicates that
*{{cc|u}} has a variance assigned
*the variance is named {{cc|my_var}}
*the variance is located in the first diagonal element of the $$\Sigma$$ matrix specified in tag {{cc|<sigma>}} nested in tag {{cc|<my_var>>}}

=== Estimating fixed means and a random genetic effects in a multi-variate model ===

Consider the linear model

$$
\left(
\begin{array}{c}
y_1 \\
y_2
\end{array}
\right)=
\left(
\begin{array}{cc}
X_1 & 0 \\
0 & X_2 \\
\end{array}
\right)
\left(
\begin{array}{c}
b_1 \\
b_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
Z & 0 \\
0 & Z
\end{array}
\right)
\left(
\begin{array}{c}
u_1 \\
u_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
I & 0 \\
0 & I
\end{array}
\right)
\left(
\begin{array}{c}
e_1 \\
e_2
\end{array}
\right)
$$

where all variables are those declared in [[#Estimating a mean and a random genetic effect in a uni-variate model|above]], and subscripts $$1$$ and $$2$$ index trait $$1$$ and $$2$$, respectively.

Note that $$[u_1,u_2]\sim N([0,0],A\otimes \Sigma_a)$$ where $$A$$ is the pedigree-derived relationship matrix and
$$
\Sigma_a=
\left(\begin{array}{cc}
\sigma_{a_1}^2 & \sigma_{a_1,a_2}\\
\sigma_{a_2,a_1} & \sigma_{a_2}^2
\end{array}\right)
$$
Further, $$[e_1,e_2]\sim N([0,0],I\otimes \Sigma_e)$$ with
$$
\Sigma_e=
\left(\begin{array}{cc}
\sigma_{e_1}^2 & \sigma_{e_1,e_2}\\
\sigma_{e_2,e_1} & \sigma_{e_2}^2
\end{array}\right)
$$.

A possible data file for such mode may look like:
#y1,y2,mu,id
25.0,0.8,1,5
33.1,0.5,1,6
36.0,1.5,1,7
28.3,3.6,1,8
and the pedigree files is that provided in example [[#Estimating a mean and a random genetic effect in a uni-variate model]].

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0,0.8
0.8,1.2
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y1 = mu*b1 + id*u1(v(my_var(1)))
y2 = mu*b2 + id*u2(v(my_var(2)))
</eqn>
</model>
</root>
</syntaxhighlight>

== Example code chunks ==

'''The following code chunks are only subset of a full parameter file. It is assumed that all other parts of the instruction file are functional and all necessary input data are available and the that the data file columns have the respective names.'''

=== Providing pedigrees ===

==== Providing a pedigree containing genetic groups ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
phantomparents: 2
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a pedigree containing metafounders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
metafile: mymeta.csv
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a probabilistic pedigree ====

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<pedigrees>
pedigrees: a
<a>
switch: probabilistic
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing several pedigrees ====

<syntaxhighlight lang="xml">
<root>
...
<pedigrees>
pedigrees: a,b
<a>
...
</a>

...

</pedigrees>
...
</root>
</syntaxhighlight>

=== Providing Genotypes ===

==== Providing external allele frequencies ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
pqfile: mypq.csv 
</a>
</genotypes>
...
</root>
</syntaxhighlight>

==== Providing several genotype files ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
...
</root>
</syntaxhighlight>

=== Providing GRMs ===

==== Constructing GRM from genotypes ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Overriding the default GRM construction method ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
method: YA 
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing a GRM from file ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<grms>
grms: x
<x>
file: mygrm.csv
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing several GRMs ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
...
</root>
</syntaxhighlight>

=== Single step models ===

==== ssGBLUP model with GRM build from genotypes====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGBLUP model with GRM supplied externally ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<grms>
grms: x
<x>
file: mygrm.bin
pedigree: a
cross: id.csv
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGTBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
file: pedigree.csv
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
file: mygeno.txt
pedigree: a
cross: ids.csv
...
</a>
</genotypes>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
type: tblup
genotype: a
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssSNPBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
switch: adjustg2a
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with meta-founders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
metafile: mymeta.csv 
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
pqfile: myp.csv 
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with a separate polygenic factor ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: a,g
<a>
<sigma>
file: cov_polygenic.csv 
</sigma>
<gamma>
<A>
pedigree: a
</A>
</gamma>
</a>
<g>
type: snpblup1
genotype: a
aweight: 0.001 
switch: adjustg2a
<sigma>
file: cov_genomic.csv 
</sigma>
<marker_sb1>
<sigma>
file: cov_genomic.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*ug1(v(g(1))+dam*mg1(v(g(2))+individual*ua1(v(a(1))+dam*ma1(v(a(2))
y2=mu*b2+individual*ug2(v(g(3))+dam*mg2(v(g(4))+individual*ua2(v(a(3))+dam*ma2(v(a(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssGBLUP with two genomic factors ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a,b
<a>
...
pedigree: a
</a>

...
pedigree: a

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
<vars>
...
vars: g1,g2
<g1>
...
<gamma>
<H>
...
grm: x
</H>
</gamma>
</g1>
<g2>
...
<gamma>
<H>
...
grm: y
</H>
</gamma>
</g2>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u11(v(g1(1))+id*u21(v(g2(1))
y2=mu*b2+id*u12(v(g1(2))+id*u22(v(g2(2))
</eqn>
</models>
</root>
</syntaxhighlight>

=== Regression on continuous co-variables ===

==== Linear regression ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co))*age1
y2=mu*b2+age(t(co))*age2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== User-defined polynomial expansion ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
x^1
log(sqrt(x))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Using hard-coded Legendre polynomials ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2,3))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
l0
l1
l2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested co-variables ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
weaningweight=mu*b1+age(t(co(p(1,2);n(sex))))*age
intramuscularfatcontent=mu*b2+weight(t(co(p(1,2);n(sex))))*weight
</eqn>
<eqn attributes="strings">
x^1
x^2
</eqn>
</models>
...
</root>
</syntaxhighlight>

=== Random-regression models ===
==== Nested continuous random co-variables ====

{{cc|days}} is a co-variable which is nested within {{cc|individual}} or {{cc|dam}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(n(individual))))*u1(v(g(1))+days(t(co(n(dam))))*m1(v(g(2))
y2=mu*b2+days(t(co(n(individual))))*u2(v(g(3))+days(t(co(n(dam))))*m2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous random co-variables with polynomial expansion ====

Similar to [[#Nested continuous co-variables|Nested continuous co-variables]] but {{cc|days}} is expanded

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(p(1,2,3);n(dam))))*m1(v(g(4,5,6))
y2=mu*b2+days(t(co(p(1,2,3);n(individual))))*u2(v(g(7,8,9))+days(t(co(p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous co-variables with polynomial expansion and an integer co-variable ====

Similar to [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]], but an additional information {{cc|t(i)}} is provided telling {{lmt}} that {{cc|days}} is actually an integer. While the results do not differ from [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]] {{lmt}} can exploit this information for memory efficiency.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(t(i);p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(t(i);p(1,2,3);n(dam))))*m1(v(g(7,8,9))
y2=mu*b2+days(t(co(t(i);p(1,2,3);n(individual))))*u2(v(g(4,5,6))+days(t(co(t(i);p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials of order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
</root>
</syntaxhighlight>

=== Defining equivalent models with genetic groups ===

Note that in the parameterization provided below [[#Defining a model with absorbed genetic groups|absorbed genetic groups]] and [[#Defining a model with genetic groups as extra factor|genetic groups as extra factor]] must yield the same results. However, only when using {{cc|absorbed genetic groups}} the factor level solutions are the actual breeding values. When modelling genetic groups as an extra factor genetic factor solutions and genetic group factor solutions must be added by the user.

==== Defining a model with absorbed genetic groups ====

Note that the only information necessary is the number of phantom parents '''at the top of the pedigree'''({{cc|phantomparents: 10}}) and the information to the variance that the it should be constructed allowing for genetic groups({{cc|switch gg}}).

<syntaxhighlight lang="xml" line highlight="6,19">
<root>
<pedigrees>
pedigrees: a
<a>
file: myped.csv
phantomparents: 10
</a>
<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: a
switch: gg
</A>
</gamma>
</g>
</vars>
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Defining a model with genetic groups as extra random factor ====

Genetic groups are defined as an extra factor, which requires an extra variance({{cc|gg}}) and two pedigrees, the genetic group pedigree({{cc|a}}) and the normal pedigree({{cc|b}}). For a model equivalent to [[#Defining a model with absorbed genetic groups|absorption]] pedigree {{cc|b}} must be a subset of pedigree {{cc|a}}. Further, if breeding values are required {{lmt}} can provide the genetic group regression matrix {{cc|qfile: Q.coocsv}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g,gg
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
<gg>
<sigma>
file: myG.csv <! must contain a 4x4 matrix. should be the same as for "g">
</sigma>
</gg>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1(v(gg(1))+dam(t(gg(a)))*damgg1(v(gg(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2(v(gg(2))+dam(t(gg(a)))*damgg2(v(gg(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== Defining a model with fixed genetic groups ====

Fixed genetic groups are only supported if modeled as an extra factor. Therefore, the model is similar to [[#Defining a model with genetic groups as extra random factor|above]], but the extra variance is omitted. Note that when modeling genetic groups as fixed it is the users responsibility to omit one group from the respective pedigree to ensure that $$X$$ is of full column rank. [[#Linear models in lmt:Column rank of $$X$$|bla]]

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1+dam(t(gg(a)))*damgg1
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2+dam(t(gg(a)))*damgg2
</eqn>
</models>
</root>
</syntaxhighlight>

=== Override the default job parameters ===

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<jobs>
jobs: default
<default>
conv: -9.21 <! log(10e-5)>
</default>
</jobs>
...
</root>
</syntaxhighlight>

=== Use job "solve" instead of "default" ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>

</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Use a direct solver in stead of the default solver ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>
<direct>
</direct>
</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using Gibbs sampling ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: sample
<sample>
sampler: x
</sample>
</jobs>
<samplers>
samplers: x
<x>
<blocked>
samples: 100000
</blocked>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using MC-EM-REML ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: mcemreml
<mcemreml>
sampler: x
solver: y
</mcemreml>
</jobs>
<solvers>
solvers: y
<y>
<pcgiod>
conv: -16.1181
</pcgiod>
</y>
</solvers>
<samplers>
samplers: x
<x>
<pe>
samples: 50
switch: trace
chains: 36
</pe>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using AI-REML-C ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: airemlc
<airemlc>
</airemlc>
</jobs>
...
</root>
</syntaxhighlight>

=== Calculating exact prediction error co-variances using a direct solver===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>
<direct>
</direct>
</a>
</solvers>
...
</root>
</syntaxhighlight>

=== Calculating prediction error co-variances for a target individual===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
levels: 1156679414 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>

</a>
</solvers>
...
</root>
</syntaxhighlight>

Algorithms

2022-06-07T04:40:03Z

127.0.0.1: /* Fixation of $$\Sigma$$ matrix elements */

==Solving Linear Mixed model Equations==
{{lmt}} supports two types of solver for solving MME's: a direct solver and an iterative solver
===Iterative solver===
The iterative solver uses the [https://en.wikipedia.org/wiki/Conjugate_gradient_method#The_preconditioned_conjugate_gradient_method preconditioned conjugate gradient method] and is {{lmt}}'s default solver. It does not require the explicit construction of any mixed model equation, and is therefore less resource demanding than the direct solver. That is, many models which cannot be solved using the direct solver can still be solved using the iterative solver. Even for small models the iterative solver usually outperforms the direct solver in terms of total processing time.

Whether the iterative solver has converged in round $$i$$ can be evaluated with convergence criterions $$log_e\left(\sqrt{\frac{||(Cx_i-b)||}{||b||}}\right)<t$$ or $$log_e\left(\sqrt{\frac{||(x_{i}-x_{i-1})||'}{||x_{i-1}||}}\right)<t$$, where $$C$$ is the mixed-model coefficient matrix, $$x_i$$ is the solution vector in round $$i$$, $$b$$ is the right-hand side and $$t$$ is the convergence threshold which defaults to -18.42, which is $$log_e(10^{-9})$$.

===Direct solver===
The direct solver requires the mixed model coefficient matrix to be build and all Kronecker products to be resolved. This can be quite memory demanding and should therefore be used carefully. The direct solver uses a [https://en.wikipedia.org/wiki/Cholesky_decomposition Cholesky decomposition] and [https://en.wikipedia.org/wiki/Triangular_matrix#Forward_and_back_substitution forward-backward-substitution] to solve the mixed model equation system, where especially the decomposition step can be very resource demanding and time consuming.

==Variance component estimation==
For random factors {{lmt}} supports variance of structure [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Sigma$$ is an dense symmetric positive definite matrix to be estimated. For residuals {{lmt}} supports variance structures $$I\otimes\Sigma$$ and $$\Theta_L(I_{n_{observations}})\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_{n_{observations}}$$ is an identity matrix of dimensions equal to the total number of observations across all traits. Note that the number of records associated to a particular $$\Sigma_i$$ should be sufficient to facilitate its estimation.

===Gibbs sampling===
====Single pass Gibbs sampling====
{{lmt}}'s single pass Gibbs sampling algorithm is described in <ref name="Sorensen2002" />. In short, all location parameters are drawn from their joint conditional posterior distribution. Note that this requires solving the mixed model equation system once per iteration which usually leads to a substantial increase in processing time. Note that ssSNBPLUP models are not supported.

====Blocked Gibbs sampling====
For random factors {{lmt}}'s blocked Gibbs sampler draws correlated location parameters within factor level from their joint conditional posterior distribution. Location parameters of fixed factors are drawn in scalar mode from their fully conditional posterior. Note that ssGTBLUP and ssSNPBLUP models are not supported.
===Restricted Maximum Likelyhood===
====MC-EM-REML====
{{lmt}} provides a monte-carlo expectation-maximisation REML algorithms which uses the preconditioned gradient solver for solving the mixed model equations and a blocked Gibbs sampler to sample the necessary traces<ref name="Harville2004" />. Note that ssSNPBLUP and ssGTBLUP models are not supported.

The MC-EM-REML convergence criterion is $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.

====Average information (AI)-REML====
{{lmt}} provides the calculation of variance components using average information REML <ref name="Johnson1995" />, <ref name="Gilmour1995" /> and <ref name="Jensen1997" />.
REML estimates of co-variance matrices can be derived using the phenotypic co-variance matrix $$V$$ or the mixed-model equations system coefficient matrix C.

{{lmt}} provides three different AI-REML convergence criterions:

* the relative change of the log-likelihood calculated as $$log_e\left(\sqrt{\frac{||(l_{i}-l_{i-1})||}{||l_{i-1}||}}\right)$$ where $$l$$ is the log-likelihood and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{||g_{i}||}\right)$$ where $$g$$ is the gradient vector and $$i$$ is the iteration counter.

=====AI-REML-C=====
{{lmt}} supports AI-REML-C, which relies on the construction and factorization of the mixed-model equations system coefficient matrix C.

Note that ssSNPBLUP and ssGTBLUP models are not supported. Further, it is not advisable to use airemlc for ssGBLUP models.

===Fixation of Sigma matrix elements===
Elements of $$\Sigma$$ matrices can be exempted from re-estimation in two ways:
#providing a boolean [[Parameter_file_elements#<sigma>|mask matrix]] $$B$$ where elements set to "T" are related to elements in $$\Sigma$$ which should be regarded as fixed, or by
#setting a diagonal element in $$\Sigma$$ desired to be fixed to 1.0 to 1.0, or by
#setting an off-diagonal element in $$\Sigma$$ desired to be fixed to 0.0 to 0.0.

Note that in case exemption is communicated via options 2 and 3 the $$\Sigma$$ matrix provided at start must still be positive definite. Further note that using option 1 overrides all information contained in $$\Sigma$$. That is if $$\Sigma[1,1]$$ is set to 1.0 but $$B$$[1,1] is set to false, $$\Sigma$$[1,1] is not exempt.

==Elements of the inverse of the mixed model coefficient matrix==
In principle {{lmt}} can generate any element of the inverse mixed model coefficient matrix. However, the user interface is currently limited to the diagonal elements for fixed factors and the diagonal blocks for random factors. These elements can either be sampled or obtained accurately via solving.
===Gibbs Sampling===
Following the approach of Harville(1999)<ref name="Harville1999" /> {{lmt}} can sample for fixed factors the diagonal elements of the inverse of the mixed model coefficient matrix, for random factors the diagonal blocks of the inverse of the coefficient matrix where the block size is determined by the dimension of the related $$\Sigma$$ matrix. The blocks are the prediction error co-variance matrices of the factor levels of correlated sub-factors. When sampling prediction error variances {{lmt}} can run many Gibbs chains in parallel allowing to exploit multi-core hardware architecture. However, it is recommended to specify not more chains than the number of available '''real''' cores excluding hyper-threading technology.
===Solving===
{{lmt}} can obtain elements of the inverse of the coefficient matrix via solving the mixed model equations. This method is currently only supported for the diagonal prediction error co-variance blocks of random factors, where the block size is determined by the dimension of the related $$\Sigma$$ matrix. For this algorithm {{lmt}} can utilize either the [[#Iterative solver]] or the [[#Direct solver]].

==Iterative inbreeding==
{{lmt}} supports the iterative calculation of inbreeding coefficients as described in VanRaden(1992)<ref name="VanRaden1992" />.

==References==
<references>
<ref name="Sorensen2002">D. Sorensen and D. Gianola; Likelihood, Bayesian, and MCMC Methods in Quantitative Genetics; 2002; 584-588</ref>
<ref name="Harville1999">David A. Harville; Use of the Gibbs sampler to invert large, possibly sparse, positive definite matrices; Linear Algebra and its Applications; 1999</ref>
<ref name="Harville2004">David A. Harville; Making REML computationally feasible for large data sets: use of the Gibbs sampler; Journal of Statistical Computation & Simulation; 2004</ref>
<ref name="Jensen1997">J. Jensen et. al.; Residual maximum likelihood estimation of (co) variance components in multivariate mixed linear models using average information; Indian Society of Agricultural Statistics; 1997</ref>
<ref name="Gilmour1995">A. Gilmour et. al.; Average information REML: an efficient algorithm for variance parameter estimation in linear mixed models; Biometrics; 1995</ref>
<ref name="Johnson1995">D.L. Johnson and R. Thompson; Restricted maximum likelihood estimation of variance components for univariate animal models using sparse matrix techniques and average information; Journal of Dairy Science; 1995</ref>
<ref name="VanRaden1992">PM VanRanden; Accounting for Inbreeding and Crossbreeding in Genetic Evaluation of Large Populations; Journal of Dairy Science; 1992</ref>
</references>

Algorithms

2022-06-07T04:39:28Z

127.0.0.1: /* Average information (AI)-REML */

==Solving Linear Mixed model Equations==
{{lmt}} supports two types of solver for solving MME's: a direct solver and an iterative solver
===Iterative solver===
The iterative solver uses the [https://en.wikipedia.org/wiki/Conjugate_gradient_method#The_preconditioned_conjugate_gradient_method preconditioned conjugate gradient method] and is {{lmt}}'s default solver. It does not require the explicit construction of any mixed model equation, and is therefore less resource demanding than the direct solver. That is, many models which cannot be solved using the direct solver can still be solved using the iterative solver. Even for small models the iterative solver usually outperforms the direct solver in terms of total processing time.

Whether the iterative solver has converged in round $$i$$ can be evaluated with convergence criterions $$log_e\left(\sqrt{\frac{||(Cx_i-b)||}{||b||}}\right)<t$$ or $$log_e\left(\sqrt{\frac{||(x_{i}-x_{i-1})||'}{||x_{i-1}||}}\right)<t$$, where $$C$$ is the mixed-model coefficient matrix, $$x_i$$ is the solution vector in round $$i$$, $$b$$ is the right-hand side and $$t$$ is the convergence threshold which defaults to -18.42, which is $$log_e(10^{-9})$$.

===Direct solver===
The direct solver requires the mixed model coefficient matrix to be build and all Kronecker products to be resolved. This can be quite memory demanding and should therefore be used carefully. The direct solver uses a [https://en.wikipedia.org/wiki/Cholesky_decomposition Cholesky decomposition] and [https://en.wikipedia.org/wiki/Triangular_matrix#Forward_and_back_substitution forward-backward-substitution] to solve the mixed model equation system, where especially the decomposition step can be very resource demanding and time consuming.

==Variance component estimation==
For random factors {{lmt}} supports variance of structure [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Sigma$$ is an dense symmetric positive definite matrix to be estimated. For residuals {{lmt}} supports variance structures $$I\otimes\Sigma$$ and $$\Theta_L(I_{n_{observations}})\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_{n_{observations}}$$ is an identity matrix of dimensions equal to the total number of observations across all traits. Note that the number of records associated to a particular $$\Sigma_i$$ should be sufficient to facilitate its estimation.

===Gibbs sampling===
====Single pass Gibbs sampling====
{{lmt}}'s single pass Gibbs sampling algorithm is described in <ref name="Sorensen2002" />. In short, all location parameters are drawn from their joint conditional posterior distribution. Note that this requires solving the mixed model equation system once per iteration which usually leads to a substantial increase in processing time. Note that ssSNBPLUP models are not supported.

====Blocked Gibbs sampling====
For random factors {{lmt}}'s blocked Gibbs sampler draws correlated location parameters within factor level from their joint conditional posterior distribution. Location parameters of fixed factors are drawn in scalar mode from their fully conditional posterior. Note that ssGTBLUP and ssSNPBLUP models are not supported.
===Restricted Maximum Likelyhood===
====MC-EM-REML====
{{lmt}} provides a monte-carlo expectation-maximisation REML algorithms which uses the preconditioned gradient solver for solving the mixed model equations and a blocked Gibbs sampler to sample the necessary traces<ref name="Harville2004" />. Note that ssSNPBLUP and ssGTBLUP models are not supported.

The MC-EM-REML convergence criterion is $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.

====Average information (AI)-REML====
{{lmt}} provides the calculation of variance components using average information REML <ref name="Johnson1995" />, <ref name="Gilmour1995" /> and <ref name="Jensen1997" />.
REML estimates of co-variance matrices can be derived using the phenotypic co-variance matrix $$V$$ or the mixed-model equations system coefficient matrix C.

{{lmt}} provides three different AI-REML convergence criterions:

* the relative change of the log-likelihood calculated as $$log_e\left(\sqrt{\frac{||(l_{i}-l_{i-1})||}{||l_{i-1}||}}\right)$$ where $$l$$ is the log-likelihood and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{||g_{i}||}\right)$$ where $$g$$ is the gradient vector and $$i$$ is the iteration counter.

=====AI-REML-C=====
{{lmt}} supports AI-REML-C, which relies on the construction and factorization of the mixed-model equations system coefficient matrix C.

Note that ssSNPBLUP and ssGTBLUP models are not supported. Further, it is not advisable to use airemlc for ssGBLUP models.

===Fixation of $$\Sigma$$ matrix elements===
Elements of $$\Sigma$$ matrices can be exempted from re-estimation in two ways:
#providing a boolean [[Parameter_file_elements#<sigma>|mask matrix]] $$B$$ where elements set to "T" are related to elements in $$\Sigma$$ which should be regarded as fixed, or by
#setting a diagonal element in $$\Sigma$$ desired to be fixed to 1.0 to 1.0, or by
#setting an off-diagonal element in $$\Sigma$$ desired to be fixed to 0.0 to 0.0.

Note that in case exemption is communicated via options 2 and 3 the $$\Sigma$$ matrix provided at start must still be positive definite. Further note that using option 1 overrides all information contained in $$\Sigma$$. That is if $$\Sigma[1,1]$$ is set to 1.0 but $$B$$[1,1] is set to false, $$\Sigma$$[1,1] is not exempt.

==Elements of the inverse of the mixed model coefficient matrix==
In principle {{lmt}} can generate any element of the inverse mixed model coefficient matrix. However, the user interface is currently limited to the diagonal elements for fixed factors and the diagonal blocks for random factors. These elements can either be sampled or obtained accurately via solving.
===Gibbs Sampling===
Following the approach of Harville(1999)<ref name="Harville1999" /> {{lmt}} can sample for fixed factors the diagonal elements of the inverse of the mixed model coefficient matrix, for random factors the diagonal blocks of the inverse of the coefficient matrix where the block size is determined by the dimension of the related $$\Sigma$$ matrix. The blocks are the prediction error co-variance matrices of the factor levels of correlated sub-factors. When sampling prediction error variances {{lmt}} can run many Gibbs chains in parallel allowing to exploit multi-core hardware architecture. However, it is recommended to specify not more chains than the number of available '''real''' cores excluding hyper-threading technology.
===Solving===
{{lmt}} can obtain elements of the inverse of the coefficient matrix via solving the mixed model equations. This method is currently only supported for the diagonal prediction error co-variance blocks of random factors, where the block size is determined by the dimension of the related $$\Sigma$$ matrix. For this algorithm {{lmt}} can utilize either the [[#Iterative solver]] or the [[#Direct solver]].

==Iterative inbreeding==
{{lmt}} supports the iterative calculation of inbreeding coefficients as described in VanRaden(1992)<ref name="VanRaden1992" />.

==References==
<references>
<ref name="Sorensen2002">D. Sorensen and D. Gianola; Likelihood, Bayesian, and MCMC Methods in Quantitative Genetics; 2002; 584-588</ref>
<ref name="Harville1999">David A. Harville; Use of the Gibbs sampler to invert large, possibly sparse, positive definite matrices; Linear Algebra and its Applications; 1999</ref>
<ref name="Harville2004">David A. Harville; Making REML computationally feasible for large data sets: use of the Gibbs sampler; Journal of Statistical Computation & Simulation; 2004</ref>
<ref name="Jensen1997">J. Jensen et. al.; Residual maximum likelihood estimation of (co) variance components in multivariate mixed linear models using average information; Indian Society of Agricultural Statistics; 1997</ref>
<ref name="Gilmour1995">A. Gilmour et. al.; Average information REML: an efficient algorithm for variance parameter estimation in linear mixed models; Biometrics; 1995</ref>
<ref name="Johnson1995">D.L. Johnson and R. Thompson; Restricted maximum likelihood estimation of variance components for univariate animal models using sparse matrix techniques and average information; Journal of Dairy Science; 1995</ref>
<ref name="VanRaden1992">PM VanRanden; Accounting for Inbreeding and Crossbreeding in Genetic Evaluation of Large Populations; Journal of Dairy Science; 1992</ref>
</references>

Algorithms

2022-06-07T04:39:07Z

127.0.0.1: /* MC-EM-REML */

==Solving Linear Mixed model Equations==
{{lmt}} supports two types of solver for solving MME's: a direct solver and an iterative solver
===Iterative solver===
The iterative solver uses the [https://en.wikipedia.org/wiki/Conjugate_gradient_method#The_preconditioned_conjugate_gradient_method preconditioned conjugate gradient method] and is {{lmt}}'s default solver. It does not require the explicit construction of any mixed model equation, and is therefore less resource demanding than the direct solver. That is, many models which cannot be solved using the direct solver can still be solved using the iterative solver. Even for small models the iterative solver usually outperforms the direct solver in terms of total processing time.

Whether the iterative solver has converged in round $$i$$ can be evaluated with convergence criterions $$log_e\left(\sqrt{\frac{||(Cx_i-b)||}{||b||}}\right)<t$$ or $$log_e\left(\sqrt{\frac{||(x_{i}-x_{i-1})||'}{||x_{i-1}||}}\right)<t$$, where $$C$$ is the mixed-model coefficient matrix, $$x_i$$ is the solution vector in round $$i$$, $$b$$ is the right-hand side and $$t$$ is the convergence threshold which defaults to -18.42, which is $$log_e(10^{-9})$$.

===Direct solver===
The direct solver requires the mixed model coefficient matrix to be build and all Kronecker products to be resolved. This can be quite memory demanding and should therefore be used carefully. The direct solver uses a [https://en.wikipedia.org/wiki/Cholesky_decomposition Cholesky decomposition] and [https://en.wikipedia.org/wiki/Triangular_matrix#Forward_and_back_substitution forward-backward-substitution] to solve the mixed model equation system, where especially the decomposition step can be very resource demanding and time consuming.

==Variance component estimation==
For random factors {{lmt}} supports variance of structure [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Sigma$$ is an dense symmetric positive definite matrix to be estimated. For residuals {{lmt}} supports variance structures $$I\otimes\Sigma$$ and $$\Theta_L(I_{n_{observations}})\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_{n_{observations}}$$ is an identity matrix of dimensions equal to the total number of observations across all traits. Note that the number of records associated to a particular $$\Sigma_i$$ should be sufficient to facilitate its estimation.

===Gibbs sampling===
====Single pass Gibbs sampling====
{{lmt}}'s single pass Gibbs sampling algorithm is described in <ref name="Sorensen2002" />. In short, all location parameters are drawn from their joint conditional posterior distribution. Note that this requires solving the mixed model equation system once per iteration which usually leads to a substantial increase in processing time. Note that ssSNBPLUP models are not supported.

====Blocked Gibbs sampling====
For random factors {{lmt}}'s blocked Gibbs sampler draws correlated location parameters within factor level from their joint conditional posterior distribution. Location parameters of fixed factors are drawn in scalar mode from their fully conditional posterior. Note that ssGTBLUP and ssSNPBLUP models are not supported.
===Restricted Maximum Likelyhood===
====MC-EM-REML====
{{lmt}} provides a monte-carlo expectation-maximisation REML algorithms which uses the preconditioned gradient solver for solving the mixed model equations and a blocked Gibbs sampler to sample the necessary traces<ref name="Harville2004" />. Note that ssSNPBLUP and ssGTBLUP models are not supported.

The MC-EM-REML convergence criterion is $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.

====Average information (AI)-REML====
{{lmt}} provides the calculation of variance components using average information REML <ref name="Johnson1995" />, <ref name="Gilmour1995" /> and <ref name="Jensen1997" />.
REML estimates of co-variance matrices can be derived using the phenotypic co-variance matrix $$V$$ or the mixed-model equations system coefficient matrix C.

{{lmt}} provides three different AI-REML convergence criterions:

* the relative change of the log-likelihood calculated as $$log_e\left(\sqrt{\frac{||(l_{i}-l_{i-1})||'}{||l_{i-1}||}}\right)$$ where $$l$$ is the log-likelihood and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||'}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{||g_{i}||}\right)$$ where $$g$$ is the gradient vector and $$i$$ is the iteration counter.

=====AI-REML-C=====
{{lmt}} supports AI-REML-C, which relies on the construction and factorization of the mixed-model equations system coefficient matrix C.

Note that ssSNPBLUP and ssGTBLUP models are not supported. Further, it is not advisable to use airemlc for ssGBLUP models.

===Fixation of $$\Sigma$$ matrix elements===
Elements of $$\Sigma$$ matrices can be exempted from re-estimation in two ways:
#providing a boolean [[Parameter_file_elements#<sigma>|mask matrix]] $$B$$ where elements set to "T" are related to elements in $$\Sigma$$ which should be regarded as fixed, or by
#setting a diagonal element in $$\Sigma$$ desired to be fixed to 1.0 to 1.0, or by
#setting an off-diagonal element in $$\Sigma$$ desired to be fixed to 0.0 to 0.0.

Note that in case exemption is communicated via options 2 and 3 the $$\Sigma$$ matrix provided at start must still be positive definite. Further note that using option 1 overrides all information contained in $$\Sigma$$. That is if $$\Sigma[1,1]$$ is set to 1.0 but $$B$$[1,1] is set to false, $$\Sigma$$[1,1] is not exempt.

==Elements of the inverse of the mixed model coefficient matrix==
In principle {{lmt}} can generate any element of the inverse mixed model coefficient matrix. However, the user interface is currently limited to the diagonal elements for fixed factors and the diagonal blocks for random factors. These elements can either be sampled or obtained accurately via solving.
===Gibbs Sampling===
Following the approach of Harville(1999)<ref name="Harville1999" /> {{lmt}} can sample for fixed factors the diagonal elements of the inverse of the mixed model coefficient matrix, for random factors the diagonal blocks of the inverse of the coefficient matrix where the block size is determined by the dimension of the related $$\Sigma$$ matrix. The blocks are the prediction error co-variance matrices of the factor levels of correlated sub-factors. When sampling prediction error variances {{lmt}} can run many Gibbs chains in parallel allowing to exploit multi-core hardware architecture. However, it is recommended to specify not more chains than the number of available '''real''' cores excluding hyper-threading technology.
===Solving===
{{lmt}} can obtain elements of the inverse of the coefficient matrix via solving the mixed model equations. This method is currently only supported for the diagonal prediction error co-variance blocks of random factors, where the block size is determined by the dimension of the related $$\Sigma$$ matrix. For this algorithm {{lmt}} can utilize either the [[#Iterative solver]] or the [[#Direct solver]].

==Iterative inbreeding==
{{lmt}} supports the iterative calculation of inbreeding coefficients as described in VanRaden(1992)<ref name="VanRaden1992" />.

==References==
<references>
<ref name="Sorensen2002">D. Sorensen and D. Gianola; Likelihood, Bayesian, and MCMC Methods in Quantitative Genetics; 2002; 584-588</ref>
<ref name="Harville1999">David A. Harville; Use of the Gibbs sampler to invert large, possibly sparse, positive definite matrices; Linear Algebra and its Applications; 1999</ref>
<ref name="Harville2004">David A. Harville; Making REML computationally feasible for large data sets: use of the Gibbs sampler; Journal of Statistical Computation & Simulation; 2004</ref>
<ref name="Jensen1997">J. Jensen et. al.; Residual maximum likelihood estimation of (co) variance components in multivariate mixed linear models using average information; Indian Society of Agricultural Statistics; 1997</ref>
<ref name="Gilmour1995">A. Gilmour et. al.; Average information REML: an efficient algorithm for variance parameter estimation in linear mixed models; Biometrics; 1995</ref>
<ref name="Johnson1995">D.L. Johnson and R. Thompson; Restricted maximum likelihood estimation of variance components for univariate animal models using sparse matrix techniques and average information; Journal of Dairy Science; 1995</ref>
<ref name="VanRaden1992">PM VanRanden; Accounting for Inbreeding and Crossbreeding in Genetic Evaluation of Large Populations; Journal of Dairy Science; 1992</ref>
</references>

Algorithms

2022-06-07T04:38:30Z

127.0.0.1: /* MC-EM-REML */

==Solving Linear Mixed model Equations==
{{lmt}} supports two types of solver for solving MME's: a direct solver and an iterative solver
===Iterative solver===
The iterative solver uses the [https://en.wikipedia.org/wiki/Conjugate_gradient_method#The_preconditioned_conjugate_gradient_method preconditioned conjugate gradient method] and is {{lmt}}'s default solver. It does not require the explicit construction of any mixed model equation, and is therefore less resource demanding than the direct solver. That is, many models which cannot be solved using the direct solver can still be solved using the iterative solver. Even for small models the iterative solver usually outperforms the direct solver in terms of total processing time.

Whether the iterative solver has converged in round $$i$$ can be evaluated with convergence criterions $$log_e\left(\sqrt{\frac{||(Cx_i-b)||}{||b||}}\right)<t$$ or $$log_e\left(\sqrt{\frac{||(x_{i}-x_{i-1})||'}{||x_{i-1}||}}\right)<t$$, where $$C$$ is the mixed-model coefficient matrix, $$x_i$$ is the solution vector in round $$i$$, $$b$$ is the right-hand side and $$t$$ is the convergence threshold which defaults to -18.42, which is $$log_e(10^{-9})$$.

===Direct solver===
The direct solver requires the mixed model coefficient matrix to be build and all Kronecker products to be resolved. This can be quite memory demanding and should therefore be used carefully. The direct solver uses a [https://en.wikipedia.org/wiki/Cholesky_decomposition Cholesky decomposition] and [https://en.wikipedia.org/wiki/Triangular_matrix#Forward_and_back_substitution forward-backward-substitution] to solve the mixed model equation system, where especially the decomposition step can be very resource demanding and time consuming.

==Variance component estimation==
For random factors {{lmt}} supports variance of structure [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Sigma$$ is an dense symmetric positive definite matrix to be estimated. For residuals {{lmt}} supports variance structures $$I\otimes\Sigma$$ and $$\Theta_L(I_{n_{observations}})\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_{n_{observations}}$$ is an identity matrix of dimensions equal to the total number of observations across all traits. Note that the number of records associated to a particular $$\Sigma_i$$ should be sufficient to facilitate its estimation.

===Gibbs sampling===
====Single pass Gibbs sampling====
{{lmt}}'s single pass Gibbs sampling algorithm is described in <ref name="Sorensen2002" />. In short, all location parameters are drawn from their joint conditional posterior distribution. Note that this requires solving the mixed model equation system once per iteration which usually leads to a substantial increase in processing time. Note that ssSNBPLUP models are not supported.

====Blocked Gibbs sampling====
For random factors {{lmt}}'s blocked Gibbs sampler draws correlated location parameters within factor level from their joint conditional posterior distribution. Location parameters of fixed factors are drawn in scalar mode from their fully conditional posterior. Note that ssGTBLUP and ssSNPBLUP models are not supported.
===Restricted Maximum Likelyhood===
====MC-EM-REML====
{{lmt}} provides a monte-carlo expectation-maximisation REML algorithms which uses the preconditioned gradient solver for solving the mixed model equations and a blocked Gibbs sampler to sample the necessary traces<ref name="Harville2004" />. Note that ssSNPBLUP and ssGTBLUP models are not supported.

The MC-EM-REML convergence criterion is $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||'}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.

====Average information (AI)-REML====
{{lmt}} provides the calculation of variance components using average information REML <ref name="Johnson1995" />, <ref name="Gilmour1995" /> and <ref name="Jensen1997" />.
REML estimates of co-variance matrices can be derived using the phenotypic co-variance matrix $$V$$ or the mixed-model equations system coefficient matrix C.

{{lmt}} provides three different AI-REML convergence criterions:

* the relative change of the log-likelihood calculated as $$log_e\left(\sqrt{\frac{||(l_{i}-l_{i-1})||'}{||l_{i-1}||}}\right)$$ where $$l$$ is the log-likelihood and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{\frac{||(p_{i}-p_{i-1})||'}{||p_{i-1}||}}\right)$$ where $$p$$ is the parameter vector and $$i$$ is the iteration counter.
* $$log_e\left(\sqrt{||g_{i}||}\right)$$ where $$g$$ is the gradient vector and $$i$$ is the iteration counter.

=====AI-REML-C=====
{{lmt}} supports AI-REML-C, which relies on the construction and factorization of the mixed-model equations system coefficient matrix C.

Note that ssSNPBLUP and ssGTBLUP models are not supported. Further, it is not advisable to use airemlc for ssGBLUP models.

===Fixation of $$\Sigma$$ matrix elements===
Elements of $$\Sigma$$ matrices can be exempted from re-estimation in two ways:
#providing a boolean [[Parameter_file_elements#<sigma>|mask matrix]] $$B$$ where elements set to "T" are related to elements in $$\Sigma$$ which should be regarded as fixed, or by
#setting a diagonal element in $$\Sigma$$ desired to be fixed to 1.0 to 1.0, or by
#setting an off-diagonal element in $$\Sigma$$ desired to be fixed to 0.0 to 0.0.

Note that in case exemption is communicated via options 2 and 3 the $$\Sigma$$ matrix provided at start must still be positive definite. Further note that using option 1 overrides all information contained in $$\Sigma$$. That is if $$\Sigma[1,1]$$ is set to 1.0 but $$B$$[1,1] is set to false, $$\Sigma$$[1,1] is not exempt.

==Elements of the inverse of the mixed model coefficient matrix==
In principle {{lmt}} can generate any element of the inverse mixed model coefficient matrix. However, the user interface is currently limited to the diagonal elements for fixed factors and the diagonal blocks for random factors. These elements can either be sampled or obtained accurately via solving.
===Gibbs Sampling===
Following the approach of Harville(1999)<ref name="Harville1999" /> {{lmt}} can sample for fixed factors the diagonal elements of the inverse of the mixed model coefficient matrix, for random factors the diagonal blocks of the inverse of the coefficient matrix where the block size is determined by the dimension of the related $$\Sigma$$ matrix. The blocks are the prediction error co-variance matrices of the factor levels of correlated sub-factors. When sampling prediction error variances {{lmt}} can run many Gibbs chains in parallel allowing to exploit multi-core hardware architecture. However, it is recommended to specify not more chains than the number of available '''real''' cores excluding hyper-threading technology.
===Solving===
{{lmt}} can obtain elements of the inverse of the coefficient matrix via solving the mixed model equations. This method is currently only supported for the diagonal prediction error co-variance blocks of random factors, where the block size is determined by the dimension of the related $$\Sigma$$ matrix. For this algorithm {{lmt}} can utilize either the [[#Iterative solver]] or the [[#Direct solver]].

==Iterative inbreeding==
{{lmt}} supports the iterative calculation of inbreeding coefficients as described in VanRaden(1992)<ref name="VanRaden1992" />.

==References==
<references>
<ref name="Sorensen2002">D. Sorensen and D. Gianola; Likelihood, Bayesian, and MCMC Methods in Quantitative Genetics; 2002; 584-588</ref>
<ref name="Harville1999">David A. Harville; Use of the Gibbs sampler to invert large, possibly sparse, positive definite matrices; Linear Algebra and its Applications; 1999</ref>
<ref name="Harville2004">David A. Harville; Making REML computationally feasible for large data sets: use of the Gibbs sampler; Journal of Statistical Computation & Simulation; 2004</ref>
<ref name="Jensen1997">J. Jensen et. al.; Residual maximum likelihood estimation of (co) variance components in multivariate mixed linear models using average information; Indian Society of Agricultural Statistics; 1997</ref>
<ref name="Gilmour1995">A. Gilmour et. al.; Average information REML: an efficient algorithm for variance parameter estimation in linear mixed models; Biometrics; 1995</ref>
<ref name="Johnson1995">D.L. Johnson and R. Thompson; Restricted maximum likelihood estimation of variance components for univariate animal models using sparse matrix techniques and average information; Journal of Dairy Science; 1995</ref>
<ref name="VanRaden1992">PM VanRanden; Accounting for Inbreeding and Crossbreeding in Genetic Evaluation of Large Populations; Journal of Dairy Science; 1992</ref>
</references>

Output files

2022-06-07T04:22:03Z

127.0.0.1: /* Variance component estimation using MC-EM-REML */

==Default output files==
===General output files===
====lmt.log====
General log file always generated. Provides information of the current state of operation.
===Operation dependent output files===
====Solving the mixed model equation system====
=====results.csv=====
The file contains the solutions for the mixed model equation system. The file has four columns:
*factor name,
*sub-factor name,
*factor level id, and
*solution.

Note that {{cc|factor name}}s are derived according to the lmt factor naming convention, and {{cc|sub-factor name}}s are user-defined and are extracted from the equation system. Further, the {{cc|factor level id}} is the original as provided by the data, pedigree, etc. For variables undergoing polynomial expansions, e.g. sub-factor {{cc|c}} in

y=x*b+age(t(co(p(1,2))))*c+id*u(v(my_var(1)))

the sub-factor name will be expanded as well to {{cc|sub-factor name_id}}, where "id" is the polynomial id. For the above example {{cc|c}} would be expanded to {{cc|c_1}} and {{cc|c_2}}.

The file has as many records the system has equations. Fixed factor levels which have been omitted due to rank deficiencies are not printed.
=====PCG solver output files=====
======so_conv.csv======
Contains the iteration statistics with columns
*iteration number
*alpha
*beta
*$$||r_i M r_i||$$, where $$M$$ is the preconditioner matrix and $$r_i=Cx_i-b$$ for a system $$Cx=b$$
*convergence criterion CD
*convergence criterion CR
*second per iteration

====Variance component estimation using Gibbs sampling====

=====<u.d. variance name>_sigma_SA.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as MC-EM-REML iterations.
Estimates for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}}, assuming 10,000 samples, a burn-in of 1,000 samples and a thinning of 50 samples, can be obtained by

<syntaxhighlight lang="R" line>
d<-as.matrix(fread("g_sigma_SA.csv")))
n<-floor(sqrt(ncol(d)*2))
gMean<-matrix(0,n,n);gSd<-gMean
gMean[upper.tri(g,diag=TRUE)]<-colMeans(d[seq(1000,nrow(d),20),]);
gSd[upper.tri(g,diag=TRUE)]<-apply(d[seq(1000,nrow(d),20),],2,sd);
</syntaxhighlight>

====Variance component estimation using MC-EM-REML====

=====mcemreml_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*seconds for the last MC-Em iteration
*seconds for solving the equation system
*seconds for sampling the traces
*convergence criterion '''cd'''

=====<u.d. variance name>_sigma_SA.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as MC-EM-REML iterations. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_SA.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d),];
</syntaxhighlight>

====Variance component estimation using AI-REML-C====

=====aic_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*iteration number
*convergence criterion '''ng'''
*convergence criterion '''cd'''
*convergence criterion '''ll'''
*log-likelihood
*Newton over-relaxation parameter
*number of Newton over-relaxation iterations
*seconds for the last AI-REML iteration

=====<u.d. variance name>_sigma_UPDATE.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as AI-REML-C iterations plus one. The row before the last contains the co-variance estimates at convergence. The last row contains the approximate standard errors of the parameter estimates. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_UPDATE.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d)-1,];
</syntaxhighlight>

===Intermediate output files===
====Files from processing pedigrees====
====="u.d. pedigree name"_sorted.csv=====
File contains a 3(ordinary pedigree) or 4(probabilistic pedigree) column matrix containing the sorted and renumbered pedigree generated from the original pedigree.
====="u.d. pedigree name"_crossref.csv=====
File contains a vector of original ids of individuals in '''"u.d. pedigree name"_sorted.csv'''. That is, the original id of individual #1 in '''"u.d. pedigree name"_sorted.csv''' is located in record 1 of this file, etc.

====="u.d. pedigree name".bin=====
Block file in binary format containing for blocks:
*a: real vector of diagonal elements of $$A$$
*ai: real vector of diagonal elements of $$A^{-1}$$
*m: real vector of mendelian sampling terms
*pe: 3 column integer matrix of the sorted and renumbered pedigree underlying $$A$$
==Requested output files==
===Files from processing pedigrees===
====Genetic group regression matrix====
lmt can write the genetic group regression matrix(aka $$Q$$) of a pedigree containing phantom parents to a user-defined file. For the necessary key string see [[Parameter_file_elements#<pedigree_name>|here]].

A $$Q$$ matrix written to {{cc|Q.coocsv}} format maybe read into R

<syntaxhighlight lang="R" line>
dim<-scan("Q.coocsv",n=2,sep=",")
Q<-matrix(0,d[1],d[2])
dat<-fread("Q.coocsv",skip=1)
Q[cbind(d$V1,d$V2)]<-d$V3
</syntaxhighlight>

===Files from running AI-REML jobs===
====AI matrix, gradient vector and parameter vector====
Upon provision of the respective [[parameter_file_elements#airemlc|switch]] in the instruction file {{lmt}} writes the AI matrix, gradient vector and parameter vector to files {{cc|ai_ai.csv}}, {{cc|ai_ja.csv}} and {{cc|ai_pa.csv}}, respectively. Files {{cc|ai_ai.csv}} and {{cc|ai_ja.csv}} contain as many records as AI-REML iterations. File {{cc|ai_pa.csv}} contains contains as many records as AI-REML iterations + 1, where the first record is the parameter vector at the start.

Each row of file {{cc|ai_ai.csv}} contains the upper-triangular of the AI in column-major order. The AI matrix of say iteration 2 can be reconstructed by

<syntaxhighlight lang="R" line>
d<-fread("ai_ai.csv"))
n<-floor(sqrt(ncol(d)*2))
ai<-matrix(0,n,n);ai[upper.tri(ai,diag=TRUE)]<-d[2,];
</syntaxhighlight>

Output files

2022-06-07T04:17:57Z

127.0.0.1: /* _sigma_SA.csv */

==Default output files==
===General output files===
====lmt.log====
General log file always generated. Provides information of the current state of operation.
===Operation dependent output files===
====Solving the mixed model equation system====
=====results.csv=====
The file contains the solutions for the mixed model equation system. The file has four columns:
*factor name,
*sub-factor name,
*factor level id, and
*solution.

Note that {{cc|factor name}}s are derived according to the lmt factor naming convention, and {{cc|sub-factor name}}s are user-defined and are extracted from the equation system. Further, the {{cc|factor level id}} is the original as provided by the data, pedigree, etc. For variables undergoing polynomial expansions, e.g. sub-factor {{cc|c}} in

y=x*b+age(t(co(p(1,2))))*c+id*u(v(my_var(1)))

the sub-factor name will be expanded as well to {{cc|sub-factor name_id}}, where "id" is the polynomial id. For the above example {{cc|c}} would be expanded to {{cc|c_1}} and {{cc|c_2}}.

The file has as many records the system has equations. Fixed factor levels which have been omitted due to rank deficiencies are not printed.
=====PCG solver output files=====
======so_conv.csv======
Contains the iteration statistics with columns
*iteration number
*alpha
*beta
*$$||r_i M r_i||$$, where $$M$$ is the preconditioner matrix and $$r_i=Cx_i-b$$ for a system $$Cx=b$$
*convergence criterion CD
*convergence criterion CR
*second per iteration

====Variance component estimation using MC-EM-REML====

=====mcemreml_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*seconds for the last MC-Em iteration
*seconds for solving the equation system
*seconds for sampling the traces
*convergence criterion '''cd'''

=====<u.d. variance name>_sigma_SA.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as MC-EM-REML iterations. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_SA.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d),];
</syntaxhighlight>

====Variance component estimation using AI-REML-C====

=====aic_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*iteration number
*convergence criterion '''ng'''
*convergence criterion '''cd'''
*convergence criterion '''ll'''
*log-likelihood
*Newton over-relaxation parameter
*number of Newton over-relaxation iterations
*seconds for the last AI-REML iteration

=====<u.d. variance name>_sigma_UPDATE.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as AI-REML-C iterations plus one. The row before the last contains the co-variance estimates at convergence. The last row contains the approximate standard errors of the parameter estimates. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_UPDATE.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d)-1,];
</syntaxhighlight>

===Intermediate output files===
====Files from processing pedigrees====
====="u.d. pedigree name"_sorted.csv=====
File contains a 3(ordinary pedigree) or 4(probabilistic pedigree) column matrix containing the sorted and renumbered pedigree generated from the original pedigree.
====="u.d. pedigree name"_crossref.csv=====
File contains a vector of original ids of individuals in '''"u.d. pedigree name"_sorted.csv'''. That is, the original id of individual #1 in '''"u.d. pedigree name"_sorted.csv''' is located in record 1 of this file, etc.

====="u.d. pedigree name".bin=====
Block file in binary format containing for blocks:
*a: real vector of diagonal elements of $$A$$
*ai: real vector of diagonal elements of $$A^{-1}$$
*m: real vector of mendelian sampling terms
*pe: 3 column integer matrix of the sorted and renumbered pedigree underlying $$A$$
==Requested output files==
===Files from processing pedigrees===
====Genetic group regression matrix====
lmt can write the genetic group regression matrix(aka $$Q$$) of a pedigree containing phantom parents to a user-defined file. For the necessary key string see [[Parameter_file_elements#<pedigree_name>|here]].

A $$Q$$ matrix written to {{cc|Q.coocsv}} format maybe read into R

<syntaxhighlight lang="R" line>
dim<-scan("Q.coocsv",n=2,sep=",")
Q<-matrix(0,d[1],d[2])
dat<-fread("Q.coocsv",skip=1)
Q[cbind(d$V1,d$V2)]<-d$V3
</syntaxhighlight>

===Files from running AI-REML jobs===
====AI matrix, gradient vector and parameter vector====
Upon provision of the respective [[parameter_file_elements#airemlc|switch]] in the instruction file {{lmt}} writes the AI matrix, gradient vector and parameter vector to files {{cc|ai_ai.csv}}, {{cc|ai_ja.csv}} and {{cc|ai_pa.csv}}, respectively. Files {{cc|ai_ai.csv}} and {{cc|ai_ja.csv}} contain as many records as AI-REML iterations. File {{cc|ai_pa.csv}} contains contains as many records as AI-REML iterations + 1, where the first record is the parameter vector at the start.

Each row of file {{cc|ai_ai.csv}} contains the upper-triangular of the AI in column-major order. The AI matrix of say iteration 2 can be reconstructed by

<syntaxhighlight lang="R" line>
d<-fread("ai_ai.csv"))
n<-floor(sqrt(ncol(d)*2))
ai<-matrix(0,n,n);ai[upper.tri(ai,diag=TRUE)]<-d[2,];
</syntaxhighlight>

Output files

2022-06-07T04:16:56Z

127.0.0.1: /* _sigma_SA.csv */

==Default output files==
===General output files===
====lmt.log====
General log file always generated. Provides information of the current state of operation.
===Operation dependent output files===
====Solving the mixed model equation system====
=====results.csv=====
The file contains the solutions for the mixed model equation system. The file has four columns:
*factor name,
*sub-factor name,
*factor level id, and
*solution.

Note that {{cc|factor name}}s are derived according to the lmt factor naming convention, and {{cc|sub-factor name}}s are user-defined and are extracted from the equation system. Further, the {{cc|factor level id}} is the original as provided by the data, pedigree, etc. For variables undergoing polynomial expansions, e.g. sub-factor {{cc|c}} in

y=x*b+age(t(co(p(1,2))))*c+id*u(v(my_var(1)))

the sub-factor name will be expanded as well to {{cc|sub-factor name_id}}, where "id" is the polynomial id. For the above example {{cc|c}} would be expanded to {{cc|c_1}} and {{cc|c_2}}.

The file has as many records the system has equations. Fixed factor levels which have been omitted due to rank deficiencies are not printed.
=====PCG solver output files=====
======so_conv.csv======
Contains the iteration statistics with columns
*iteration number
*alpha
*beta
*$$||r_i M r_i||$$, where $$M$$ is the preconditioner matrix and $$r_i=Cx_i-b$$ for a system $$Cx=b$$
*convergence criterion CD
*convergence criterion CR
*second per iteration

====Variance component estimation using MC-EM-REML====

=====mcemreml_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*seconds for the last MC-Em iteration
*seconds for solving the equation system
*seconds for sampling the traces
*convergence criterion '''cd'''

=====<u.d. variance name>_sigma_SA.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as MC-EM-REML iterations. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_SA.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d)-1,];
</syntaxhighlight>

====Variance component estimation using AI-REML-C====

=====aic_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*iteration number
*convergence criterion '''ng'''
*convergence criterion '''cd'''
*convergence criterion '''ll'''
*log-likelihood
*Newton over-relaxation parameter
*number of Newton over-relaxation iterations
*seconds for the last AI-REML iteration

=====<u.d. variance name>_sigma_UPDATE.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as AI-REML-C iterations plus one. The row before the last contains the co-variance estimates at convergence. The last row contains the approximate standard errors of the parameter estimates. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_UPDATE.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d)-1,];
</syntaxhighlight>

===Intermediate output files===
====Files from processing pedigrees====
====="u.d. pedigree name"_sorted.csv=====
File contains a 3(ordinary pedigree) or 4(probabilistic pedigree) column matrix containing the sorted and renumbered pedigree generated from the original pedigree.
====="u.d. pedigree name"_crossref.csv=====
File contains a vector of original ids of individuals in '''"u.d. pedigree name"_sorted.csv'''. That is, the original id of individual #1 in '''"u.d. pedigree name"_sorted.csv''' is located in record 1 of this file, etc.

====="u.d. pedigree name".bin=====
Block file in binary format containing for blocks:
*a: real vector of diagonal elements of $$A$$
*ai: real vector of diagonal elements of $$A^{-1}$$
*m: real vector of mendelian sampling terms
*pe: 3 column integer matrix of the sorted and renumbered pedigree underlying $$A$$
==Requested output files==
===Files from processing pedigrees===
====Genetic group regression matrix====
lmt can write the genetic group regression matrix(aka $$Q$$) of a pedigree containing phantom parents to a user-defined file. For the necessary key string see [[Parameter_file_elements#<pedigree_name>|here]].

A $$Q$$ matrix written to {{cc|Q.coocsv}} format maybe read into R

<syntaxhighlight lang="R" line>
dim<-scan("Q.coocsv",n=2,sep=",")
Q<-matrix(0,d[1],d[2])
dat<-fread("Q.coocsv",skip=1)
Q[cbind(d$V1,d$V2)]<-d$V3
</syntaxhighlight>

===Files from running AI-REML jobs===
====AI matrix, gradient vector and parameter vector====
Upon provision of the respective [[parameter_file_elements#airemlc|switch]] in the instruction file {{lmt}} writes the AI matrix, gradient vector and parameter vector to files {{cc|ai_ai.csv}}, {{cc|ai_ja.csv}} and {{cc|ai_pa.csv}}, respectively. Files {{cc|ai_ai.csv}} and {{cc|ai_ja.csv}} contain as many records as AI-REML iterations. File {{cc|ai_pa.csv}} contains contains as many records as AI-REML iterations + 1, where the first record is the parameter vector at the start.

Each row of file {{cc|ai_ai.csv}} contains the upper-triangular of the AI in column-major order. The AI matrix of say iteration 2 can be reconstructed by

<syntaxhighlight lang="R" line>
d<-fread("ai_ai.csv"))
n<-floor(sqrt(ncol(d)*2))
ai<-matrix(0,n,n);ai[upper.tri(ai,diag=TRUE)]<-d[2,];
</syntaxhighlight>

Output files

2022-06-07T04:15:15Z

127.0.0.1: /* Variance component estimation using AI-REML-C */

==Default output files==
===General output files===
====lmt.log====
General log file always generated. Provides information of the current state of operation.
===Operation dependent output files===
====Solving the mixed model equation system====
=====results.csv=====
The file contains the solutions for the mixed model equation system. The file has four columns:
*factor name,
*sub-factor name,
*factor level id, and
*solution.

Note that {{cc|factor name}}s are derived according to the lmt factor naming convention, and {{cc|sub-factor name}}s are user-defined and are extracted from the equation system. Further, the {{cc|factor level id}} is the original as provided by the data, pedigree, etc. For variables undergoing polynomial expansions, e.g. sub-factor {{cc|c}} in

y=x*b+age(t(co(p(1,2))))*c+id*u(v(my_var(1)))

the sub-factor name will be expanded as well to {{cc|sub-factor name_id}}, where "id" is the polynomial id. For the above example {{cc|c}} would be expanded to {{cc|c_1}} and {{cc|c_2}}.

The file has as many records the system has equations. Fixed factor levels which have been omitted due to rank deficiencies are not printed.
=====PCG solver output files=====
======so_conv.csv======
Contains the iteration statistics with columns
*iteration number
*alpha
*beta
*$$||r_i M r_i||$$, where $$M$$ is the preconditioner matrix and $$r_i=Cx_i-b$$ for a system $$Cx=b$$
*convergence criterion CD
*convergence criterion CR
*second per iteration

====Variance component estimation using MC-EM-REML====

=====mcemreml_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*seconds for the last MC-Em iteration
*seconds for solving the equation system
*seconds for sampling the traces
*convergence criterion '''cd'''

=====<u.d. variance name>_sigma_SA.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as MC-EM-REML iterations. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_UPDATE.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d)-1,];
</syntaxhighlight>

====Variance component estimation using AI-REML-C====

=====aic_conv.csv=====

Contains the iteration statistic with one parameter vector per iteration. The parameter vector contains the following elements:
*iteration number
*convergence criterion '''ng'''
*convergence criterion '''cd'''
*convergence criterion '''ll'''
*log-likelihood
*Newton over-relaxation parameter
*number of Newton over-relaxation iterations
*seconds for the last AI-REML iteration

=====<u.d. variance name>_sigma_UPDATE.csv=====
The file contains the column-wise upper-triangular elements of the respective $$\Sigma$$ matrix estimated in each round. The file contains as many rows as AI-REML-C iterations plus one. The row before the last contains the co-variance estimates at convergence. The last row contains the approximate standard errors of the parameter estimates. Estimates at convergence for a $$\Sigma$$ matrix being part of variance structure named {{cc|g}} maybe read into R by

<syntaxhighlight lang="R" line>
d<-fread("g_sigma_UPDATE.csv"))
n<-floor(sqrt(ncol(d)*2))
g<-matrix(0,n,n);g[upper.tri(g,diag=TRUE)]<-d[nrow(d)-1,];
</syntaxhighlight>

===Intermediate output files===
====Files from processing pedigrees====
====="u.d. pedigree name"_sorted.csv=====
File contains a 3(ordinary pedigree) or 4(probabilistic pedigree) column matrix containing the sorted and renumbered pedigree generated from the original pedigree.
====="u.d. pedigree name"_crossref.csv=====
File contains a vector of original ids of individuals in '''"u.d. pedigree name"_sorted.csv'''. That is, the original id of individual #1 in '''"u.d. pedigree name"_sorted.csv''' is located in record 1 of this file, etc.

====="u.d. pedigree name".bin=====
Block file in binary format containing for blocks:
*a: real vector of diagonal elements of $$A$$
*ai: real vector of diagonal elements of $$A^{-1}$$
*m: real vector of mendelian sampling terms
*pe: 3 column integer matrix of the sorted and renumbered pedigree underlying $$A$$
==Requested output files==
===Files from processing pedigrees===
====Genetic group regression matrix====
lmt can write the genetic group regression matrix(aka $$Q$$) of a pedigree containing phantom parents to a user-defined file. For the necessary key string see [[Parameter_file_elements#<pedigree_name>|here]].

A $$Q$$ matrix written to {{cc|Q.coocsv}} format maybe read into R

<syntaxhighlight lang="R" line>
dim<-scan("Q.coocsv",n=2,sep=",")
Q<-matrix(0,d[1],d[2])
dat<-fread("Q.coocsv",skip=1)
Q[cbind(d$V1,d$V2)]<-d$V3
</syntaxhighlight>

===Files from running AI-REML jobs===
====AI matrix, gradient vector and parameter vector====
Upon provision of the respective [[parameter_file_elements#airemlc|switch]] in the instruction file {{lmt}} writes the AI matrix, gradient vector and parameter vector to files {{cc|ai_ai.csv}}, {{cc|ai_ja.csv}} and {{cc|ai_pa.csv}}, respectively. Files {{cc|ai_ai.csv}} and {{cc|ai_ja.csv}} contain as many records as AI-REML iterations. File {{cc|ai_pa.csv}} contains contains as many records as AI-REML iterations + 1, where the first record is the parameter vector at the start.

Each row of file {{cc|ai_ai.csv}} contains the upper-triangular of the AI in column-major order. The AI matrix of say iteration 2 can be reconstructed by

<syntaxhighlight lang="R" line>
d<-fread("ai_ai.csv"))
n<-floor(sqrt(ncol(d)*2))
ai<-matrix(0,n,n);ai[upper.tri(ai,diag=TRUE)]<-d[2,];
</syntaxhighlight>

Parameter file elements

2022-05-25T10:29:02Z

127.0.0.1: /* airemlc> */

Below is a list of all possible parameter file xml elements. For each element an example is provided as well as information about the element's host element, the element's type and the element's content. '''Note that all words(element names, key string words, key string variables) in bold are hard-coded, all in italic are user-defined (this does not apply to the example box)'''. The spelling of hard-coded words must be abide by, the spelling of user-defined words is user-defined.

=<'''model'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<model>
<eqn attribute="strings">
..
</eqn>
<poly attribute="strings">
..
</poly>
</model>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}compulsory
{{!}}hosts information about the equations and the polynomials.
}}

content:

*compulsory element '''<eqn attributes="strings">'''
*optional element '''<poly attributes="strings">'''
==<'''eqn'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<model>
<eqn attribute="strings">
y1=x*b1+z*u1(v(g(1))
y2=x*b2+z*u2(v(g(2))
y3=x*b3+a(t(co(p(1,2);n(k))))*c1+z*u3(v(g(3)))
</eqn>
..
</model>
</root>
</syntaxhighlight>
{{!}}'''model'''
{{!}}compulsory
{{!}}hosts information about the equations.
}}

content:

*[[linear mixed models in lmt#Model_syntax|model strings]] which are escaped from the formatting rules by adding '''attributes="strings"''' to the start tag.

==<'''poly'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<model>
<poly attribute="strings">
x^0
x^2
3*x^2+sqrt(sin(x))
</poly>
..
</model>
</root>
</syntaxhighlight>
{{!}}'''model'''
{{!}}optional
{{!}}hosts user defined polynomials and references to hard-coded polynomials. Note that there can only be one polynomial per line. Model strings will reference polynomials by their line number.
}}

content

*[[linear mixed models in lmt#Polynomials|polynomial strings]] which are escaped from the formatting rules by adding '''attributes="strings"''' to the start tag.

=<'''pedigrees'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<pedigrees>
pedigrees: a,b
...
</pedigrees>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}automatic-optional
{{!}}hosts one to several elements each containing information about a specific pedigree}}

content:
*key strings
{{tablekeys2|
{{!}}'''pedigrees'''
{{!}}'''pedigrees''': ''a,b''
{{!}}compulsory
{{!}}csv word-list
{{!}}''pedigree names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements}}
*nominated-compulsory elements
==<''pedigree name''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<pedigrees>
pedigrees: myped
..
<myped>
file: myped.csv
switch: selfing
phantomparents: 2
qfile: myq.coocsv
</myped>
..
</pedigrees>
</root>
</syntaxhighlight>
{{!}}'''pedigrees'''
{{!}}nominated-compulsory
{{!}}hosts information about a specific pedigree identified by ''pedigree name''
}}
content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''myped.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}list content determines the name of the file containing the pedigree
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''selfing'''
{{!}}optional
{{!}}csv-word-list
{{!}}'''selfing,probabilistic'''
{{!}}none
{{!}}list content determines pedigree properties.
*'''selfing''': both parents can have the same id
*'''probabilistic''': each individual can have more than 1 pair of parents
{{!}}-
{{!}}'''phantomparents'''
{{!}}'''phantomparents''': 2
{{!}}optional
{{!}}single numeric value
{{!}}positive integer
{{!}}none
{{!}}integer number determines the number of individuals at the top of the pedigree which are phantom parents
{{!}}-
{{!}}'''qfile'''
{{!}}'''qfile''': myq.coocsv
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}provides name of file to which the genetic regression matrix should be written. Supported file name suffixes are ".bin" for binary block file, ".blkcsv" for csv blockfile and ".coocsv" for csv coordinate format.
{{!}}-
{{!}}'''metafile'''
{{!}}'''metafile''': meta.csv
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}provides name of the file containing the metafounder co-variance matrix.
}}

=<'''genotypes'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<genotypes>
genotypes: a,b
...
</genotypes>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}automatic-optional
{{!}}hosts one to several elements each containing information about different sets of genotypes
}}

content:
*key strings
{{tablekeys2|
{{!}}'''genotypes'''
{{!}}'''genotypes''': ''a,b''
{{!}}compulsory
{{!}}csv word-list
{{!}}''genotype names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements
}}
*nominated-compulsory elements
==<''genotype name''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<genotypes>
genotypes: mygn
..
<mygn>
file: genotypes.txt
pedigree: myped
cross: crossref.csv
</mygn>
..
</genotypes>
</root>
</syntaxhighlight>
{{!}}'''genotypes'''
{{!}}nominated-compulsory
{{!}}hosts information about a specific set of genotypes identified by ''genotype name''
}}
content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''genotype.txt''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the genotypes
{{!}}-
{{!}}'''cross'''
{{!}}'''cross''': ''mycross.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the pedigree ids related to the genotypes
{{!}}-
{{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}optional
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree previously invoked pedigree related to the content of the cross-reference file
{{!}}-
{{!}}'''pqfile'''
{{!}}'''pqfile''': ''mypq.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the allele frequencies. Note that the file content is used as a substitute for the column means of the marker matrix. It must therefore contain 2p.
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''ignorefixed'''
{{!}}optional
{{!}}csv word-list
{{!}}'''ignorefixed,ignoremissing'''
{{!}}none
{{!}}
*ignorefixed: fixed markers are ignored '''but may lead to program crash or spurious results latter on'''
*ignoremissing: marker coded as missing(3) are set to 0.
}}

=<'''grms'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<grms>
grms: a,b
...
</grms>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}automatic-optional
{{!}}hosts one to several elements each containing information about a specific grm
}}

content:
*key strings
{{tablekeys2|
{{!}}'''grms'''
{{!}}'''grms''': ''x,y''
{{!}}compulsory
{{!}}csv word-list
{{!}}''grm names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements
}}
*nominated-compulsory elements
==<''grm name''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<grms>
grms: mygrm
..
<mygrm>
genotype: mygn
method: YA
</mygrm>
..
</genotypes>
</root>
</syntaxhighlight>
{{!}}'''grms'''
{{!}}nominated-compulsory
{{!}}hosts information about a specific grm identified by ''grm name''
}}
content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''mygrm.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the grm. mutually exclusive with keyword '''genotype'''.
{{!}}-
{{!}}'''genotype'''
{{!}}'''genotype''': ''mygn''
{{!}}compulsory
{{!}}word
{{!}}''genotype name''
{{!}}none
{{!}}content determines the genotype element to be used for building the grm. mutually exclusive with keyword '''file'''.
{{!}}-
{{!}}'''cross'''
{{!}}'''cross''': ''mycross.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the pedigree ids related to the genotypes. if this information has already been supplied to the genotypes it cannot be supplied here.
{{!}}-
{{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}optional
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree previously invoked pedigree related to the content of the cross-reference file. if this information has already been supplied to the genotypes it cannot be supplied here.
{{!}}-
{{!}}'''method'''
{{!}}'''method''':'''YA'''
{{!}}optional
{{!}}alternative words
{{!}}'''VR<nowiki>|</nowiki>YA'''
{{!}}'''VR'''
{{!}}content determines the method to be used for building a grm from genotypes
*'''VR''': VanRaden Method 1 is used
*'''YA''': VanRaden Method 2(method Yang) is used
{{!}}-
{{!}}'''outfile'''
{{!}}'''outfile''': ''mygrm.bin''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file where the grm should be written to. will only take effect if the grm was build from genotypes. if the genotypes had a pedigree assigned a cross-reference file will be written out as well which contains the original pedigree ids of the genotyped individuals in the order of the rows/columns of the grm. the file name of the cross-reference file is that of the grm with the prefix '''cross_'''.
}}

=<'''vars'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
vars: g,p
...
</vars>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}compulsory
{{!}}hosts one to several elements each containing information about a specific variance.
}}

content:
*key strings
{{tablekeys2|
{{!}}'''vars'''
{{!}}'''vars''': ''g,p''
{{!}}compulsory
{{!}}csv word-list
{{!}}''variance names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements
}}
*nominated-compulsory elements
*compulsory element '''<res>'''
=='''Kronecker products'''==
Variance structures below are Kronecker products $$\Gamma \otimes \Sigma$$. If no '''type''' keystring is provided this is the default.
==='''<res>'''===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
<res>
<sigma>
..
</sigma>
</res>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''vars'''
{{!}}compulsory
{{!}}hosts information about the residual variance structure.
}}

content:
*compulsory element [[#<sigma>|'''<sigma>''']]
*optional element [[#<gamma>|'''<gamma>''']]

===''<variance name>''===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
..
</sigma>
<gamma>
..
</gamma>
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''vars'''
{{!}}nominated-compulsory
{{!}}hosts information about variance structure identified by ''variance name''.
}}

content:
*compulsory element [[#<sigma>|'''<sigma>''']]
*optional element [[#<gamma>|'''<gamma>''']]

*key strings
{{tablekeys2|
1={{!}}'''type'''
{{!}}'''type''': ''kronecker''
{{!}}optional
{{!}}word
{{!}}''kronecker,snpblup_1''
{{!}}kronecker
{{!}}determines whether the variance structure deviates from a Kronecker product.
}}

===='''<sigma>'''====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
..
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''variance name''
{{!}}compulsory
{{!}}hosts information about $$\Sigma$$ as part of [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]].
}}

content:

*key strings
{{tablekeys2|
1={{!}}'''file'''
{{!}}'''file''': ''mymatrix.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the $$\Sigma$$ matrix. is mutually exclusive with '''<nowiki><matrix attributes="array"></nowiki>'''.
{{!}}-
{{!}}'''type'''
{{!}}'''type''': '''block'''
{{!}}optional
{{!}}word
{{!}}'''block'''
{{!}}none
{{!}}determines that $$\Sigma$$ is equal to [[Supported_features#Supported_variance_structures|$$\Theta$$]]
{{!}}-
{{!}}'''scale'''
{{!}}'''scale''': ''0.05''
{{!}}optional
{{!}}single numeric value
{{!}}real number>0.0
{{!}}none
{{!}}multiplies $$\Sigma$$ once by the provided value after reading.
{{!}}-
{{!}}'''priordf'''
{{!}}'''priordf''': ''10''
{{!}}optional
{{!}}single numeric value
{{!}}real number>=0.0
{{!}}0.0
{{!}}prior degree of freedom when doing Gibbs sampling
{{!}}-
{{!}}'''maskfile'''
{{!}}'''maskfile''': ''mymatrixmask.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing a T/F matrix of the same dimension as the respective $$\Sigma$$ matrix. Is mutually exclusive with '''<nowiki><maskmatrix attributes="array"></nowiki>'''.
}}

*optional element '''<matrix attributes="array">'''
=====<'''matrix attributes="array"'''>=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
<matrix attributes="array">
5.0,0.5
0.5,1.8
</matrix>
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''sigma'''
{{!}}optional
{{!}}hosts the content of a single $$\Sigma$$ matrix. Is mutually exclusive with key string '''file: '''.
}}
=====<'''maskmatrix attributes="array"'''>=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
<maskmatrix attributes="array">
T,F
F,T
</matrix>
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''sigma'''
{{!}}optional
{{!}}hosts the content of a single indicator matrix of the same dimensions as the respective $$\Sigma$$ matrix. Is mutually exclusive with key string '''maskfile: '''.
}}

===='''<gamma>'''====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
..
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''variance name''
{{!}}optional
{{!}}hosts information about $$\Gamma$$ as part of [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]]. If absent $$\Gamma$$ defaults to $$I$$.
}}

content:

*mutually exclusive elements '''<A>, <H>, <G> and <E>'''

====='''<A>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<A>
pedigree: myped
</A>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma$$ being constructed as the numerator relationship matrix A using pedigree ''pedigree name''.
}}

content:
*key strings
{{tablekeys2|
{{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}optional
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree previously invoked to be used to construct A.
{{!}}-
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''gg'''
{{!}}optional
{{!}}csv word-list
{{!}}'''gg'''
{{!}}none
{{!}}
*gg: the pedigree contains genetic groups which will be fitted as random
}}

====='''<H>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<H>
type: tblup
pedigree: myped
genotype: mygn
aweight: 0.05
switch: adjustg2a
</H>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma$$ being constructed as combined single step relationship matrix H using pedigree ''pedigree name'' and genomic information. the genomic information can be supplied
*via a grm element for single step H-BLUP models
*via a genotype element for single step T-BLUP models
Note that for '''type:tblup''' it is not necessary to have an automatic-optional [[#<grms>|<grms>]] element in the parameter file. Doing so will cause the construction and RAM-storage of $$G$$ although it is not need for building H, thus maybe leading to substantial increase in processing time and RAM demand.
}}

content:
*key strings
{{tablekeys2|
1={{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}compulsory
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree element to be used to construct H.
{{!}}-
{{!}}'''type'''
{{!}}'''type''': '''tblup'''
{{!}}optional
{{!}}word
{{!}}'''tblup<nowiki>|</nowiki>gblup'''
{{!}}'''gblup'''
{{!}}content determines the way the inverse of H is constructed.
{{!}}-
{{!}}'''grm'''
{{!}}'''grm''': ''mygrm''
{{!}}conditional-compulsory
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the grm element to be used to construct H. compulsory for '''type: hblup'''.
{{!}}-
{{!}}'''genotype'''
{{!}}'''genotype''': ''mygn''
{{!}}conditional-compulsory
{{!}}word
{{!}}''genotype name''
{{!}}none
{{!}}content determines the genotype element to be used to construct H. compulsory for '''type: tblup'''.
{{!}}-
{{!}}'''aweight'''
{{!}}'''aweight: 0.05'''
{{!}}optional
{{!}}single numeric value
{{!}}0.0<=aweight<=1.0
{{!}}0.0
{{!}}blending of $$G$$ with $$A_{gg}$$ by $$G_w=aweight\times A_{gg}+(1-aweight)\times G$$
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''adjustg2a'''
{{!}}optional
{{!}}csv word-list
{{!}}'''adjustg2a,gg,diag'''
{{!}}none
{{!}}
*adjustg2a: adjustment of $$G$$ towards $$A_{gg}$$ using method
*gg: the pedigree contains genetic groups which will be fitted as random
*diag: calculate H diagonal elements and write to file (only supported for gblup).
{{!}}-
{{!}}'''grmdadd'''
{{!}}'''grmdadd''': ''0.05''
{{!}}optional
{{!}}single numeric value
{{!}}real number >=0.0
{{!}}none
{{!}} value added to the diagonal of $$G$$ to ensure invertibility. The policy is
*if '''aweight'''>0.0, nothing will be added to the diagonals
*if '''aweight''' is not supplied or is zero:
** if '''grmdadd''' is not supplied 0.001 will be added to the diagonals
** otherwise '''grmdadd''' will be used
}}

====='''<G>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<G>
grm: mygrm
</G>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma$$ being constructed from a genomic relationsship matrix.
}}

content:
*key strings
{{tablekeys2|
1={{!}}'''grmdadd'''
{{!}}'''grmdadd''': ''0.05''
{{!}}optional
{{!}}single numeric value
{{!}}real number >=0.0
{{!}}none
{{!}} value added to the diagonal of $$G$$ to ensure invertibility.
}}

====='''<E>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<E>
file: mygamma.csv
</E>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma^{-1}$$ being uploaded from a file.
}}

content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''mygamma.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the file which contains $$\Gamma^{-1}$$.
{{!}}-
{{!}}'''type'''
{{!}}'''type''': '''dense'''
{{!}}optional
{{!}}word
{{!}}'''dense<nowiki>|</nowiki>sparse_csr_ut'''
{{!}}'''sparse_csr_ut'''
{{!}}content determines the file storage of $$\Gamma^{-1}$$
*dense: full squared symmetric matrix
*sparse_csr_ut: squared symmetric sparse upper triangular matrix in [https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_row_(CSR,_CRS_or_Yale_format) csr] format
}}

=='''snpblup1'''==

===''<variance name>''===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
genotype: mygn
aweight: 0.05
switch: adjustg2a
<sigma>
..
</sigma>
<gamma>
..
</gamma>
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''vars'''
{{!}}nominated-compulsory
{{!}}hosts information about variance structure identified by ''variance name''.
}}

content:
*compulsory element '''<sigma>'''
*compulsory element [[#<marker_sb1>|'''<marker_sb1>''']]

*key strings
{{tablekeys2|
1={{!}}'''type'''
{{!}}'''type''': ''kronecker''
{{!}}optional
{{!}}word
{{!}}''kronecker,snpblup_1''
{{!}}kronecker
{{!}}determines whether the variance structure deviates from a Kronecker product.
{{!}}-
{{!}}'''genotype'''
{{!}}'''genotype''': ''mygn''
{{!}}conditional-compulsory
{{!}}word
{{!}}''genotype name''
{{!}}none
{{!}}content determines the genotype element to be used to construct H. compulsory for '''type: tblup'''.
{{!}}-
{{!}}'''aweight'''
{{!}}'''aweight: 0.05'''
{{!}}optional
{{!}}single numeric value
{{!}}0.0<=aweight<=1.0
{{!}}0.0
{{!}}blending of $$G$$ with $$A_{gg}$$ by $$G_w=aweight\times A_{gg}+(1-aweight)\times G$$
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''adjustg2a'''
{{!}}optional
{{!}}csv word-list
{{!}}'''adjustg2a,gg,diag'''
{{!}}none
{{!}}
*adjustg2a: adjustment of $$G$$ towards $$A_{gg}$$ using method
*gg: the pedigree contains genetic groups which will be fitted as random
*diag: calculate H diagonal elements and write to file (only supported for gblup).
}}

===='''<sigma>'''====

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
<sigma>
..
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''variance name''
{{!}}compulsory
{{!}}hosts information about $$\Sigma$$ for the poly-genetic part of the variance structure.
}}

content:

see [[#<sigma>|'''<sigma''']]

===='''<marker_sb1>'''====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
..
<marker_sb1>
..
</marker_sb1>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''marker''
{{!}}compulsory
{{!}}hosts information about the co-variance between and within markers following [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]].
}}

content:

*compulsory element '''<sigma>'''
*optional element '''<gamma>'''

====='''<sigma>'''=====

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
..
<marker_sb1>
<sigma>
..
</sigma>
..
</marker_sb1>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''marker''
{{!}}compulsory
{{!}}hosts information about $$\Sigma$$ as part of [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]] for the marker part of the variance structure. Note that $$\Sigma$$ will be scaled by (1-aweight).
}}

see [[#<sigma>|'''<sigma>''']]

=<'''jobs'''>=

{{tableele2|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: solve,yh
...
</jobs>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}optional
{{!}}hosts one to several elements each containing information about a specific job
{{!}}run default job(solve) in default parameterization(default pcgiod parameterization)
}}

content:
*key strings
{{tablekeys2|
{{!}}'''jobs'''
{{!}}'''jobs''': '''solve,yhat'''
{{!}}compulsory
{{!}}csv word-list
{{!}}'''solve,sample,pevsample,mcemreml,yhat'''
{{!}}none
{{!}}job sequence is determined by the list sequence. list content determines nominated-compulsory elements
}}

*nominated-compulsory elements
**'''<default>'''
**'''<solve>'''
**'''<sample>'''
**'''<pevsample>'''
**'''<pevsolve>'''
**'''<mcemreml>'''
**'''<airemlc>'''
**'''<yhat>'''

==<'''default'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
..
<default>
conv: -18.42
</default>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''default'''
}}

content: see [[#<pcgiod>|<pcgiod>]] for a list of all possible key strings

==<'''solve'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
..
<solve>
solver: mysolver
</solve>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''solve'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''solver'''
{{!}}'''solver''': ''mysolver''
{{!}}compulsory
{{!}}word
{{!}}''solver name''
{{!}}none
{{!}}''solver name'' must be the name of a previously defined solver
}}

==<'''sample'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: sample,..
<sample>
sampler: mysampler
</sample>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''sample'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''sampler'''
{{!}}'''sampler''': ''mysampler''
{{!}}compulsory
{{!}}word
{{!}}''sampler name''
{{!}}none
{{!}}''sampler name'' must be the name of a previously defined sampler
}}

==<'''pevsample'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: pevsample,..
<pevsample>
sampler: mysampler
</pevsample>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''pevsample'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''sampler'''
{{!}}'''sampler''': ''mysampler''
{{!}}compulsory
{{!}}word
{{!}}''sampler name''
{{!}}none
{{!}}''sampler name'' must be the name of a previously defined sampler of type pev
}}

==<'''pevsolve'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: pevsolve,..
<pevsolve>
solver: mysolver
</pevsolver>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''pevsolve'''
}}

content:

*key strings
{{tablekeys2|
1={{!}}'''solver'''
{{!}}'''solver''': ''mysolver''
{{!}}compulsory
{{!}}word
{{!}}''solver name''
{{!}}none
{{!}}''solver name'' must be the name of a previously defined solver
{{!}}-
{{!}}'''factor'''
{{!}}'''factor''': ''gen''
{{!}}compulsory
{{!}}word
{{!}}''factor name''
{{!}}none
{{!}}''factor name'' must be the name of a random factor
{{!}}-
{{!}}'''levels'''
{{!}}'''levels''': ''5,10,20''
{{!}}optional
{{!}}csv integer list
{{!}}''factor level ids''
{{!}}none
{{!}}original factor level ids(.e.g. pedigree ids etc). If not supplied the prediction error co-variance blocks of all factor levels associated to the nominated factor will be calculated. Mutually exclusive with '''levelfile'''.
{{!}}-
{{!}}'''levelfile'''
{{!}}'''levelfile''': ''myfile.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}file containing original factor level ids(.e.g. pedigree ids etc). If not supplied the prediction error co-variance blocks of all factor levels associated to the nominated factor will be calculated. Mutually exclusive with '''levels'''.
{{!}}-
{{!}}'''nrhs'''
{{!}}'''nrhs''': ''50''
{{!}}optional
{{!}}integer
{{!}}''number of right-hand sides''
{{!}}1000
{{!}}number of right-hand-sides to be solved for simultaneously. Has only effect if the direct solver is used. The default may exceed the available RAM.
}}

==<'''airemlc'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: airemlc,..
<airemlc>
rounds: 50
..
</airemlc>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''airemlc'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''rounds'''
{{!}}'''rounds''': ''10''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}20
{{!}}provides the number of aireml-rounds to run
{{!}}-
{{!}}'''convtype'''
{{!}}'''convtype''': '''ng'''
{{!}}optional
{{!}}word
{{!}}'''cd<nowiki>|</nowiki>ng<nowiki>|</nowiki>ll<nowiki>|</nowiki>any<nowiki>|</nowiki>all'''
{{!}}'''cd'''
{{!}}provides the convergence criterion to use
* ll: log of relative change in log-likelihood
* ng: log of the norm of the gradient vector
* cd: log of the relative change of the parameter vector
* all: all of the above
* any: any of the above
{{!}}-
{{!}}'''convll'''
{{!}}'''convll''': ''-10.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''-6.907755''
{{!}}provides the convergence threshold for convergence criterion '''ll'''
{{!}}-
{{!}}'''convng'''
{{!}}'''convng''': ''-10.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''-16.1181''
{{!}}provides the convergence threshold for convergence criterion '''ng'''
{{!}}-
{{!}}'''convcd'''
{{!}}'''convcd''': ''-10.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''-16.1181''
{{!}}provides the convergence threshold for convergence criterion '''cd'''
{{!}}-
{{!}}'''nscale'''
{{!}}'''nscale''': ''0.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''1.0''
{{!}}scales the length of the Newton step.
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''residuals'''
{{!}}optional
{{!}}csv word-list
{{!}}any real number
{{!}}'''writeai,residuals,solutions'''
{{!}}
*'''writeai''': write ai matrix and gradient vector to files ai_ai.csv and ai_ja.csv.
*'''residuals''': after convergence write the residuals to file aic_residuals.csv
*'''solutions''': after convergence write the MME solutions to file results.csv
}}

==<'''mcemreml'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: mcemreml,..
<mcemreml>
emrounds: 500
sampler: mysampler
</mcemreml>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''mcemreml'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''emrounds'''
{{!}}'''emrounds''': ''500''
{{!}}compulsory
{{!}}numeric value
{{!}}positive integer
{{!}}none
{{!}}provides the number of mcemreml-rounds to run
{{!}}-
{{!}}'''sampler'''
{{!}}'''sampler''': ''mysampler''
{{!}}compulsory
{{!}}word
{{!}}''sampler name''
{{!}}none
{{!}}''sampler name'' must be the name of a previously defined sampler
}}

==<'''yhat'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: yhat,..
<yhat>
</yhat>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''yhat'''
}}
Currently '''yhat''' has no key strings or nested elements defined.

=<'''samplers'''>=

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,b,..
...
</samplers>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}optional
{{!}}hosts one to several elements each containing information about a specific sampler
}}

content:
*key strings
{{tablekeys2|
{{!}}'''samplers'''
{{!}}'''samplers''': ''a''
{{!}}compulsory
{{!}}csv word-list
{{!}}''sampler names''
{{!}}none
{{!}}list content determines nominated-compulsory elements
}}
*conditional-compulsory elements

==<''sampler name''>==

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
..
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}'''samplers'''
{{!}}conditional-compulsory
{{!}}hosts one of several mutually exclusive elements defining the type of sampler ''sampler name''
}}

content:
*compulsory mutually exclusive elements
**'''<singlepass>'''
**'''<blocked>'''
**'''<pev>'''

===<'''singlepass'''>===

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
<singlepass>
samples: 10000
burnin: 1000
</singlepass>
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}''sampler name''
{{!}}compulsory
{{!}}defines parameters of a sampler of type '''singlepass'''
}}

*key strings
{{tablekeys2|
{{!}}'''samples'''
{{!}}'''samples''': ''100000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the total number of samples to draw
{{!}}-
{{!}}'''burnin'''
{{!}}'''burnin''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}0
{{!}}provides the number of samples to be discarded as burnin
}}

===<'''blocked'''>===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
<blocked>
samples: 10000
burnin: 1000
</blocked>
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}''sampler name''
{{!}}compulsory
{{!}}defines parameters of a sampler of type '''blocked'''
}}

*key strings
{{tablekeys2|
{{!}}'''samples'''
{{!}}'''samples''': ''100000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the total number of samples to draw
{{!}}-
{{!}}'''burnin'''
{{!}}'''burnin''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}0
{{!}}provides the number of samples to be discarded as burnin
}}

===<'''pev'''>===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
<pev>
samples: 10000
burnin: 1000
chains: 10
</pev>
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}''sampler name''
{{!}}compulsory
{{!}}defines parameters of a sampler of type '''pev'''
}}

*key strings
{{tablekeys2|
{{!}}'''samples'''
{{!}}'''samples''': ''100000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the total number of samples to draw
{{!}}-
{{!}}'''burnin'''
{{!}}'''burnin''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}0
{{!}}provides the number of samples to be discarded as burnin
{{!}}-
{{!}}'''chains'''
{{!}}'''chains''': ''10''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}1
{{!}}provides the number of parallel chains to run
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''trace'''
{{!}}optional
{{!}}word
{{!}}'''trace'''
{{!}}none
{{!}}changes sampler from sampling prediction error variances to sampling traces required for emreml
}}

=<'''solvers'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,b,..
...
</solvers>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}optional
{{!}}hosts one to several elements each containing information about a specific solver
}}

content:
*key strings
{{tablekeys2|
{{!}}'''solvers'''
{{!}}'''solvers''': ''a''
{{!}}compulsory
{{!}}csv word-list
{{!}}''solver names''
{{!}}none
{{!}}list content determines nominated-compulsory elements
}}
*conditional-compulsory elements

==<''solver name''>==

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,..
<a>
..
</a>
</solvers>
</root>
</syntaxhighlight>
{{!}}'''solvers'''
{{!}}conditional-compulsory
{{!}}hosts one of several mutually exclusive elements defining the type of solver ''solver name''
}}

content:
*compulsory mutually exclusive elements with default element
**'''<pcgiod>''', default
**'''<direct>'''

===<'''pcgiod'''>===

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,..
<a>
<pcgiod>
rounds: 1000
conv: -20.0
</pcgiod>
</a>
</solvers>
</root>
</syntaxhighlight>
{{!}}''solver name''
{{!}}compulsory
{{!}}defines parameters of a solver of type '''pcgiod'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''rounds'''
{{!}}'''rounds''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the maximum number of rounds to run
{{!}}-
{{!}}'''conv'''
{{!}}'''conv''': ''-15.0''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}} -18.42
{{!}}provides the convergence threshold
{{!}}-
{{!}}'''convtype'''
{{!}}'''convtype''': '''cd'''
{{!}}optional
{{!}}word
{{!}}'''cr<nowiki>|</nowiki>cd'''
{{!}} '''cr'''
{{!}}provides the convergence parameter type
}}

===<'''direct'''>===

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,..
<a>
<direct>
</direct>
</a>
</solvers>
</root>
</syntaxhighlight>
{{!}}''solver name''
{{!}}compulsory
{{!}}defines parameters of a solver of type '''direct'''
}}

content: no content defined

Examples

2022-05-16T07:08:21Z

127.0.0.1: /* Use job "solve" instead of "default" */

The examples provided in this section are meant to provide a practical examples about the {{lmt}} facilities and the parameter file syntax. It is assumed that the reader is familiar with [[Parameterfile1|section]]

== Solving linear mixed model equations ==

=== Estimating a mean in a uni-variate model ===

Estimating a mean is equivalent to obtaining the generalized least square solution $$b=(X'R^{-1}X)^{-1}X'R^{-1}y$$ for model $$y=Xb+e$$, where $$y$$ is a vector of $$n$$ observations, $$X$$ is as single column matrix of $$1$$, $$b$$ is a fixed factor (mean), $$e$$ is the residual and $$y\sim N(Xb,R)$$ where $$R$$ is a $$n \times n$$ co-variance matrix.

From the above it follows that for task of solving for $$b$$ {{lmt}} needs following information:

the data
the residual variance $$R$$
the model
the solver

Assume we have a data file "data.csv" with content:
#y,mu
25.0,1
33.1,1
36.0,1
28.3,1
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records.
A valid {{lmt}} xml parameter file would look like:
<syntaxhighlight lang="xml" line highlight="5,27">
<root>
<models>
<eqn attributes="strings">
y=mu*b
</eqn>
</models>
<data>
datafile: data.csv
missingthreshold: -50.0
</data>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
</vars>
</root>
</syntaxhighlight>

Following the introduced [[Parameterfile1|parameterfile terminology]] tags {{cc|<data>}}, {{cc|<vars>}} and {{cc|<model>}} are automatic-compulsory. Since {{cc|solve}} is the default job and we are using the default solver in default parameterization no further information about the job or solver is required.

The most important aspect is the model definition in tag {{cc|<eqn>}}, nested inside tag {{cc|<model>}} $$y=mu*b$$. The variable names used here are either defined by the data file header, or by the user. That is, $$y$$ and $$mu$$ are defined in the data file header, whereas $$b$$ is a user-defined factor name. Translated this means that the content of the data column named $$y$$ should be regressed on the content of the data column named $$mu$$ with the regression coefficient named $$b$$.

Since there are no further specifications supplied about $$y$$, $$mu$$ and $$b$$, it is assumed that $$y$$ is a continuous variable, $$mu$$ is a classification variable, and $$b$$ is fixed factor.
The necessary variances are defined by the content of the automatic-compulsory tag {{cc|<vars>}}. {{lmt}} requires one compulsory variance, the residual variance, which must be specified via tag {{cc|<res>}}. Therefore tag {{cc|res}} is automatic-compulsory.

The default {{lmt}} variance structure is [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Gamma$$ and $$\Sigma$$ are specified inside tags {{cc|<gamma>}} and {{cc|<sigma>}}, respectively.
However, only tag {{cc|<sigma>}} is [[Parameterfile1#Parsing logic|automatic-compulsory]], whereas tag {{cc|<gamma>}} is [[Parameterfile1#Parsing logic|automatic-optional]]. A missing {{cc|<gamma>}} tag implies that [https://en.wikipedia.org/wiki/Identity_matrix $$\Gamma = I$$]. Note that for {{lmt}} $$\Sigma$$ is always a matrix, that is a scalar $$\sigma^2$$ is treated as a matrix $$1 \times 1$$ matrix.

For the above example, the variance specification inside {{cc|<res>}} implies that $$\Gamma\otimes \Sigma \equiv I\otimes \Sigma$$. Since $$\Sigma$$ is a $$1\times 1$$ matrix with $$\Sigma[1,1]=\sigma_e^2$$, $$R$$ reduces to $$I\sigma_e^2$$.

Note tag {{cc|<matrix>}} nested in tag {{cc|<sigma>}}. The content of tag {{cc|<matrix>}} does not comply with the formatting rules as pointed o ut [[Parameterfile1#Key strings|above]]. That is {{cc|5.0}} is not a valid key string. To let {{lmt}} know that the content of tag {{cc|<matrix>}} should not be evaluated as a key string, with a subsequent error message, [[Parameterfile1#Escaping tag content formatting rules|the tag must have attributes]]. In this example {{cc|1=matrix attributes="matrix"}} escapes the content of tag {{cc|<matrix>}} from the formatting rules.

Further, tag {{cc|<matrix>}} is automatic-optional. This might be confusing because, as pointed out above, $$\Sigma$$ forms an indispensable part of $$\Gamma\otimes \Sigma$$. However, tag {{cc|<matrix>}} belongs to a [[Parameterfile1#Group of mutually exclusive information sources|group of mutually exclusive information sources]] of which members are tag {{cc|<matrix>}} and key string {{cc|file: yourfilename}}. That is, $$\Sigma$$ maybe either embedded in the parameter file or supplied via an external file.

Note that the spelling of most tags used in the above parameter file is determined by {{lmt}} and must be abide by.

=== Estimating a fixed mean and a random genetic effect in a uni-variate model ===

Consider the linear model $$y=Xb+Zu+e$$ where all variables are those declared in [[#Estimating a mean]], $$u$$ is vector of length $$m$$ of random direct genetic effects and $$Z$$ is a design matrix of dimension $$n \times m$$ linking genetic effects to their respective observations. Note that $$u\sim N(0,A\sigma_a^2)$$ where $$A$$ is the pedigree-derived relationship matrix and forms the $$\Gamma$$ part in $$\Gamma\otimes\Sigma$$. A possible data file for such mode may look like:

#y,mu,id
25.0,1,5
33.1,1,6
36.0,1,7
28.3,1,8
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records. Further assume a pedigree in a file called "ped.csv" with content:
1,0,0
2,0,0
3,1,0
4,0,2
5,3,4
6,0,4
7,5,4
8,5,7

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y = mu*b + id*u(v(my_var(1)))
</eqn>
</model>
</root>
</syntaxhighlight>

Compared with the parameter file in example [[#Estimating a mean]] the one above contains only a few extra elements. One this the automatic-optional {{cc|<pedigrees>}} nested inside tag {{cc|<root>}}. This tag contains a keystring {{cc|pedigrees: myped}}, where the user-defined variable behind {{cc|pedigrees:}} is the name of a nominated-compulsory tag nested inside tag {cc|<pedigrees>}}. This concept allows to supply several pedigrees to lmt (e.g. a normal pedigree and a genetic group pedigree). In our example we have only one pedigree named my_ped, with tag {{cc|<my_ped>}} containing the information about this pedigree. Another additional element is the key string {{cc|vars: my_var}} nested in tag {{cc|<vars>}} where the variable of key string {{cc|vars: my_var}} provides the tag names of nominated-compulsory tags, in this example tag {{cc|<my_var>}}.

Tag {{cc|<myvar>}} consist of two structural components: the automatic-compulsory tag {{cc|<sigma>}} and the automatic-optional {{cc|<gamma>}}. Since the the variance of $$u=A\sigma_a^2$$, where $$A=\Gamma$$ and $$\sigma_a^2=\Sigma$$, a {{cc|<gamma>}} tag must be supplied to fully specify the variance. '''Note that if the {{cc|<gamma>}} tag is missing or miss-spelled {{lmt}} will assume that the variance of $$u=I\sigma_a^2$$'''. Tag {{cc|<gamma>}} contains a automatic-compulsory tag {{cc|<A>}} which specifies the $$\Gamma=A$$. Since $$A$$ is build from a pedigree, tag {{cc|<A>}} contains a compulsory key string {{cc|pedigree: my_ped}} which nominates pedigree in tag {{cc|<my_ped>}} to be used for building $$A$$.

Note the difference between the tags {{cc|<sigma>}} nested in tag {{cc|<res>}} and {{cc|<my_var>}}. The former specifies {{cc|<sigma>}} to be provided by tag {{cc|1=<matrix attributes="matrix">}}, whereas the latter specifies {{cc|<sigma>}} to be provided by a file.

The model section in the above parameter file need to communicate to to {{lmt}} that $$u$$ is a random factor with a variance $$A\sigma_a^2$$. This is done by extending the u.d. factor name {{cc|u}} in {{cc|1=y = mu*b + id*u(v(my_var(1)))}} by a specifier {{cc|(v(my_var(1)))}}. Note that without a specifier {{cc|u}} would be regarded as a fixed factor. The specifier {{cc|u(v)}} communicates that {{cc|u}} has a variance assigned. Further, {{cc|v}} has a specifier assigned via {{cc|v(my_var)}} which communicates that the name of the variance is {{cc|my_var}}. The variance in tag {{cc|<my_var>}} contains a {{cc|<gamma>}} and a {{cc|<sigma>}} component. The integer number inside bracket {{cc|my_var(1)}} communicates that $$\sigma_a^2$$ of {{cc|u}} is located in the first diagonal element of $$\Sigma$$.

In summary construct {{cc|u(v(my_var(1)))}} communicates that
*{{cc|u}} has a variance assigned
*the variance is named {{cc|my_var}}
*the variance is located in the first diagonal element of the $$\Sigma$$ matrix specified in tag {{cc|<sigma>}} nested in tag {{cc|<my_var>>}}

=== Estimating fixed means and a random genetic effects in a multi-variate model ===

Consider the linear model

$$
\left(
\begin{array}{c}
y_1 \\
y_2
\end{array}
\right)=
\left(
\begin{array}{cc}
X_1 & 0 \\
0 & X_2 \\
\end{array}
\right)
\left(
\begin{array}{c}
b_1 \\
b_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
Z & 0 \\
0 & Z
\end{array}
\right)
\left(
\begin{array}{c}
u_1 \\
u_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
I & 0 \\
0 & I
\end{array}
\right)
\left(
\begin{array}{c}
e_1 \\
e_2
\end{array}
\right)
$$

where all variables are those declared in [[#Estimating a mean and a random genetic effect in a uni-variate model|above]], and subscripts $$1$$ and $$2$$ index trait $$1$$ and $$2$$, respectively.

Note that $$[u_1,u_2]\sim N([0,0],A\otimes \Sigma_a)$$ where $$A$$ is the pedigree-derived relationship matrix and
$$
\Sigma_a=
\left(\begin{array}{cc}
\sigma_{a_1}^2 & \sigma_{a_1,a_2}\\
\sigma_{a_2,a_1} & \sigma_{a_2}^2
\end{array}\right)
$$
Further, $$[e_1,e_2]\sim N([0,0],I\otimes \Sigma_e)$$ with
$$
\Sigma_e=
\left(\begin{array}{cc}
\sigma_{e_1}^2 & \sigma_{e_1,e_2}\\
\sigma_{e_2,e_1} & \sigma_{e_2}^2
\end{array}\right)
$$.

A possible data file for such mode may look like:
#y1,y2,mu,id
25.0,0.8,1,5
33.1,0.5,1,6
36.0,1.5,1,7
28.3,3.6,1,8
and the pedigree files is that provided in example [[#Estimating a mean and a random genetic effect in a uni-variate model]].

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0,0.8
0.8,1.2
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y1 = mu*b1 + id*u1(v(my_var(1)))
y2 = mu*b2 + id*u2(v(my_var(2)))
</eqn>
</model>
</root>
</syntaxhighlight>

== Example code chunks ==

'''The following code chunks are only subset of a full parameter file. It is assumed that all other parts of the instruction file are functional and all necessary input data are available and the that the data file columns have the respective names.'''

=== Providing pedigrees ===

==== Providing a pedigree containing genetic groups ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
phantomparents: 2
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a pedigree containing metafounders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
metafile: mymeta.csv
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a probabilistic pedigree ====

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<pedigrees>
pedigrees: a
<a>
switch: probabilistic
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing several pedigrees ====

<syntaxhighlight lang="xml">
<root>
...
<pedigrees>
pedigrees: a,b
<a>
...
</a>

...

</pedigrees>
...
</root>
</syntaxhighlight>

=== Providing Genotypes ===

==== Providing external allele frequencies ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
pqfile: mypq.csv 
</a>
</genotypes>
...
</root>
</syntaxhighlight>

==== Providing several genotype files ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
...
</root>
</syntaxhighlight>

=== Providing GRMs ===

==== Constructing GRM from genotypes ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Overriding the default GRM construction method ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
method: YA 
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing a GRM from file ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<grms>
grms: x
<x>
file: mygrm.csv
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing several GRMs ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
...
</root>
</syntaxhighlight>

=== Single step models ===

==== ssGBLUP model with GRM build from genotypes====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGBLUP model with GRM supplied externally ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<grms>
grms: x
<x>
file: mygrm.bin
pedigree: a
cross: id.csv
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGTBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
file: pedigree.csv
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
file: mygeno.txt
pedigree: a
cross: ids.csv
...
</a>
</genotypes>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
type: tblup
genotype: a
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssSNPBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
switch: adjustg2a
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with meta-founders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
metafile: mymeta.csv 
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
pqfile: myp.csv 
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with a separate polygenic factor ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: a,g
<a>
<sigma>
file: cov_polygenic.csv 
</sigma>
<gamma>
<A>
pedigree: a
</A>
</gamma>
</a>
<g>
type: snpblup1
genotype: a
aweight: 0.001 
switch: adjustg2a
<sigma>
file: cov_genomic.csv 
</sigma>
<marker_sb1>
<sigma>
file: cov_genomic.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*ug1(v(g(1))+dam*mg1(v(g(2))+individual*ua1(v(a(1))+dam*ma1(v(a(2))
y2=mu*b2+individual*ug2(v(g(3))+dam*mg2(v(g(4))+individual*ua2(v(a(3))+dam*ma2(v(a(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssGBLUP with two genomic factors ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a,b
<a>
...
pedigree: a
</a>

...
pedigree: a

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
<vars>
...
vars: g1,g2
<g1>
...
<gamma>
<H>
...
grm: x
</H>
</gamma>
</g1>
<g2>
...
<gamma>
<H>
...
grm: y
</H>
</gamma>
</g2>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u11(v(g1(1))+id*u21(v(g2(1))
y2=mu*b2+id*u12(v(g1(2))+id*u22(v(g2(2))
</eqn>
</models>
</root>
</syntaxhighlight>

=== Regression on continuous co-variables ===

==== Linear regression ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co))*age1
y2=mu*b2+age(t(co))*age2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== User-defined polynomial expansion ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
x^1
log(sqrt(x))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Using hard-coded Legendre polynomials ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2,3))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
l0
l1
l2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested co-variables ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
weaningweight=mu*b1+age(t(co(p(1,2);n(sex))))*age
intramuscularfatcontent=mu*b2+weight(t(co(p(1,2);n(sex))))*weight
</eqn>
<eqn attributes="strings">
x^1
x^2
</eqn>
</models>
...
</root>
</syntaxhighlight>

=== Random-regression models ===
==== Nested continuous random co-variables ====

{{cc|days}} is a co-variable which is nested within {{cc|individual}} or {{cc|dam}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(n(individual))))*u1(v(g(1))+days(t(co(n(dam))))*m1(v(g(2))
y2=mu*b2+days(t(co(n(individual))))*u2(v(g(3))+days(t(co(n(dam))))*m2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous random co-variables with polynomial expansion ====

Similar to [[#Nested continuous co-variables|Nested continuous co-variables]] but {{cc|days}} is expanded

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(p(1,2,3);n(dam))))*m1(v(g(4,5,6))
y2=mu*b2+days(t(co(p(1,2,3);n(individual))))*u2(v(g(7,8,9))+days(t(co(p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous co-variables with polynomial expansion and an integer co-variable ====

Similar to [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]], but an additional information {{cc|t(i)}} is provided telling {{lmt}} that {{cc|days}} is actually an integer. While the results do not differ from [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]] {{lmt}} can exploit this information for memory efficiency.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(t(i);p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(t(i);p(1,2,3);n(dam))))*m1(v(g(7,8,9))
y2=mu*b2+days(t(co(t(i);p(1,2,3);n(individual))))*u2(v(g(4,5,6))+days(t(co(t(i);p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials of order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
</root>
</syntaxhighlight>

=== Defining equivalent models with genetic groups ===

Note that in the parameterization provided below [[#Defining a model with absorbed genetic groups|absorbed genetic groups]] and [[#Defining a model with genetic groups as extra factor|genetic groups as extra factor]] must yield the same results. However, only when using {{cc|absorbed genetic groups}} the factor level solutions are the actual breeding values. When modelling genetic groups as an extra factor genetic factor solutions and genetic group factor solutions must be added by the user.

==== Defining a model with absorbed genetic groups ====

Note that the only information necessary is the number of phantom parents '''at the top of the pedigree'''({{cc|phantomparents: 10}}) and the information to the variance that the it should be constructed allowing for genetic groups({{cc|switch gg}}).

<syntaxhighlight lang="xml" line highlight="6,19">
<root>
<pedigrees>
pedigrees: a
<a>
file: myped.csv
phantomparents: 10
</a>
<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: a
switch: gg
</A>
</gamma>
</g>
</vars>
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Defining a model with genetic groups as extra random factor ====

Genetic groups are defined as an extra factor, which requires an extra variance({{cc|gg}}) and two pedigrees, the genetic group pedigree({{cc|a}}) and the normal pedigree({{cc|b}}). For a model equivalent to [[#Defining a model with absorbed genetic groups|absorption]] pedigree {{cc|b}} must be a subset of pedigree {{cc|a}}. Further, if breeding values are required {{lmt}} can provide the genetic group regression matrix {{cc|qfile: Q.coocsv}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g,gg
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
<gg>
<sigma>
file: myG.csv <! must contain a 4x4 matrix. should be the same as for "g">
</sigma>
</gg>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1(v(gg(1))+dam(t(gg(a)))*damgg1(v(gg(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2(v(gg(2))+dam(t(gg(a)))*damgg2(v(gg(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== Defining a model with fixed genetic groups ====

Fixed genetic groups are only supported if modeled as an extra factor. Therefore, the model is similar to [[#Defining a model with genetic groups as extra random factor|above]], but the extra variance is omitted. Note that when modeling genetic groups as fixed it is the users responsibility to omit one group from the respective pedigree to ensure that $$X$$ is of full column rank. [[#Linear models in lmt:Column rank of $$X$$|bla]]

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1+dam(t(gg(a)))*damgg1
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2+dam(t(gg(a)))*damgg2
</eqn>
</models>
</root>
</syntaxhighlight>

=== Override the default job parameters ===

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<jobs>
jobs: default
<default>
conv: -9.21 <! log(10e-5)>
</default>
</jobs>
...
</root>
</syntaxhighlight>

=== Use job "solve" instead of "default" ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>

</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Use a direct solver in stead of the default solver ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>
<direct>
</direct>
</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using Gibbs sampling ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: sample
<sample>
sampler: x
</sample>
</jobs>
<samplers>
samplers: x
<x>
<blocked>
samples: 100000
</blocked>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using AI-REML-C ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: airemlc
<airemlc>
</airemlc>
</jobs>
...
</root>
</syntaxhighlight>

=== Calculating exact prediction error co-variances using a direct solver===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>
<direct>
</direct>
</a>
</solvers>
...
</root>
</syntaxhighlight>

=== Calculating prediction error co-variances for a target individual===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
levels: 1156679414 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>

</a>
</solvers>
...
</root>
</syntaxhighlight>

Examples

2022-05-16T07:06:45Z

127.0.0.1: /* Estimating variance components using AI-REML-C */

The examples provided in this section are meant to provide a practical examples about the {{lmt}} facilities and the parameter file syntax. It is assumed that the reader is familiar with [[Parameterfile1|section]]

== Solving linear mixed model equations ==

=== Estimating a mean in a uni-variate model ===

Estimating a mean is equivalent to obtaining the generalized least square solution $$b=(X'R^{-1}X)^{-1}X'R^{-1}y$$ for model $$y=Xb+e$$, where $$y$$ is a vector of $$n$$ observations, $$X$$ is as single column matrix of $$1$$, $$b$$ is a fixed factor (mean), $$e$$ is the residual and $$y\sim N(Xb,R)$$ where $$R$$ is a $$n \times n$$ co-variance matrix.

From the above it follows that for task of solving for $$b$$ {{lmt}} needs following information:

the data
the residual variance $$R$$
the model
the solver

Assume we have a data file "data.csv" with content:
#y,mu
25.0,1
33.1,1
36.0,1
28.3,1
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records.
A valid {{lmt}} xml parameter file would look like:
<syntaxhighlight lang="xml" line highlight="5,27">
<root>
<models>
<eqn attributes="strings">
y=mu*b
</eqn>
</models>
<data>
datafile: data.csv
missingthreshold: -50.0
</data>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
</vars>
</root>
</syntaxhighlight>

Following the introduced [[Parameterfile1|parameterfile terminology]] tags {{cc|<data>}}, {{cc|<vars>}} and {{cc|<model>}} are automatic-compulsory. Since {{cc|solve}} is the default job and we are using the default solver in default parameterization no further information about the job or solver is required.

The most important aspect is the model definition in tag {{cc|<eqn>}}, nested inside tag {{cc|<model>}} $$y=mu*b$$. The variable names used here are either defined by the data file header, or by the user. That is, $$y$$ and $$mu$$ are defined in the data file header, whereas $$b$$ is a user-defined factor name. Translated this means that the content of the data column named $$y$$ should be regressed on the content of the data column named $$mu$$ with the regression coefficient named $$b$$.

Since there are no further specifications supplied about $$y$$, $$mu$$ and $$b$$, it is assumed that $$y$$ is a continuous variable, $$mu$$ is a classification variable, and $$b$$ is fixed factor.
The necessary variances are defined by the content of the automatic-compulsory tag {{cc|<vars>}}. {{lmt}} requires one compulsory variance, the residual variance, which must be specified via tag {{cc|<res>}}. Therefore tag {{cc|res}} is automatic-compulsory.

The default {{lmt}} variance structure is [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Gamma$$ and $$\Sigma$$ are specified inside tags {{cc|<gamma>}} and {{cc|<sigma>}}, respectively.
However, only tag {{cc|<sigma>}} is [[Parameterfile1#Parsing logic|automatic-compulsory]], whereas tag {{cc|<gamma>}} is [[Parameterfile1#Parsing logic|automatic-optional]]. A missing {{cc|<gamma>}} tag implies that [https://en.wikipedia.org/wiki/Identity_matrix $$\Gamma = I$$]. Note that for {{lmt}} $$\Sigma$$ is always a matrix, that is a scalar $$\sigma^2$$ is treated as a matrix $$1 \times 1$$ matrix.

For the above example, the variance specification inside {{cc|<res>}} implies that $$\Gamma\otimes \Sigma \equiv I\otimes \Sigma$$. Since $$\Sigma$$ is a $$1\times 1$$ matrix with $$\Sigma[1,1]=\sigma_e^2$$, $$R$$ reduces to $$I\sigma_e^2$$.

Note tag {{cc|<matrix>}} nested in tag {{cc|<sigma>}}. The content of tag {{cc|<matrix>}} does not comply with the formatting rules as pointed o ut [[Parameterfile1#Key strings|above]]. That is {{cc|5.0}} is not a valid key string. To let {{lmt}} know that the content of tag {{cc|<matrix>}} should not be evaluated as a key string, with a subsequent error message, [[Parameterfile1#Escaping tag content formatting rules|the tag must have attributes]]. In this example {{cc|1=matrix attributes="matrix"}} escapes the content of tag {{cc|<matrix>}} from the formatting rules.

Further, tag {{cc|<matrix>}} is automatic-optional. This might be confusing because, as pointed out above, $$\Sigma$$ forms an indispensable part of $$\Gamma\otimes \Sigma$$. However, tag {{cc|<matrix>}} belongs to a [[Parameterfile1#Group of mutually exclusive information sources|group of mutually exclusive information sources]] of which members are tag {{cc|<matrix>}} and key string {{cc|file: yourfilename}}. That is, $$\Sigma$$ maybe either embedded in the parameter file or supplied via an external file.

Note that the spelling of most tags used in the above parameter file is determined by {{lmt}} and must be abide by.

=== Estimating a fixed mean and a random genetic effect in a uni-variate model ===

Consider the linear model $$y=Xb+Zu+e$$ where all variables are those declared in [[#Estimating a mean]], $$u$$ is vector of length $$m$$ of random direct genetic effects and $$Z$$ is a design matrix of dimension $$n \times m$$ linking genetic effects to their respective observations. Note that $$u\sim N(0,A\sigma_a^2)$$ where $$A$$ is the pedigree-derived relationship matrix and forms the $$\Gamma$$ part in $$\Gamma\otimes\Sigma$$. A possible data file for such mode may look like:

#y,mu,id
25.0,1,5
33.1,1,6
36.0,1,7
28.3,1,8
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records. Further assume a pedigree in a file called "ped.csv" with content:
1,0,0
2,0,0
3,1,0
4,0,2
5,3,4
6,0,4
7,5,4
8,5,7

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y = mu*b + id*u(v(my_var(1)))
</eqn>
</model>
</root>
</syntaxhighlight>

Compared with the parameter file in example [[#Estimating a mean]] the one above contains only a few extra elements. One this the automatic-optional {{cc|<pedigrees>}} nested inside tag {{cc|<root>}}. This tag contains a keystring {{cc|pedigrees: myped}}, where the user-defined variable behind {{cc|pedigrees:}} is the name of a nominated-compulsory tag nested inside tag {cc|<pedigrees>}}. This concept allows to supply several pedigrees to lmt (e.g. a normal pedigree and a genetic group pedigree). In our example we have only one pedigree named my_ped, with tag {{cc|<my_ped>}} containing the information about this pedigree. Another additional element is the key string {{cc|vars: my_var}} nested in tag {{cc|<vars>}} where the variable of key string {{cc|vars: my_var}} provides the tag names of nominated-compulsory tags, in this example tag {{cc|<my_var>}}.

Tag {{cc|<myvar>}} consist of two structural components: the automatic-compulsory tag {{cc|<sigma>}} and the automatic-optional {{cc|<gamma>}}. Since the the variance of $$u=A\sigma_a^2$$, where $$A=\Gamma$$ and $$\sigma_a^2=\Sigma$$, a {{cc|<gamma>}} tag must be supplied to fully specify the variance. '''Note that if the {{cc|<gamma>}} tag is missing or miss-spelled {{lmt}} will assume that the variance of $$u=I\sigma_a^2$$'''. Tag {{cc|<gamma>}} contains a automatic-compulsory tag {{cc|<A>}} which specifies the $$\Gamma=A$$. Since $$A$$ is build from a pedigree, tag {{cc|<A>}} contains a compulsory key string {{cc|pedigree: my_ped}} which nominates pedigree in tag {{cc|<my_ped>}} to be used for building $$A$$.

Note the difference between the tags {{cc|<sigma>}} nested in tag {{cc|<res>}} and {{cc|<my_var>}}. The former specifies {{cc|<sigma>}} to be provided by tag {{cc|1=<matrix attributes="matrix">}}, whereas the latter specifies {{cc|<sigma>}} to be provided by a file.

The model section in the above parameter file need to communicate to to {{lmt}} that $$u$$ is a random factor with a variance $$A\sigma_a^2$$. This is done by extending the u.d. factor name {{cc|u}} in {{cc|1=y = mu*b + id*u(v(my_var(1)))}} by a specifier {{cc|(v(my_var(1)))}}. Note that without a specifier {{cc|u}} would be regarded as a fixed factor. The specifier {{cc|u(v)}} communicates that {{cc|u}} has a variance assigned. Further, {{cc|v}} has a specifier assigned via {{cc|v(my_var)}} which communicates that the name of the variance is {{cc|my_var}}. The variance in tag {{cc|<my_var>}} contains a {{cc|<gamma>}} and a {{cc|<sigma>}} component. The integer number inside bracket {{cc|my_var(1)}} communicates that $$\sigma_a^2$$ of {{cc|u}} is located in the first diagonal element of $$\Sigma$$.

In summary construct {{cc|u(v(my_var(1)))}} communicates that
*{{cc|u}} has a variance assigned
*the variance is named {{cc|my_var}}
*the variance is located in the first diagonal element of the $$\Sigma$$ matrix specified in tag {{cc|<sigma>}} nested in tag {{cc|<my_var>>}}

=== Estimating fixed means and a random genetic effects in a multi-variate model ===

Consider the linear model

$$
\left(
\begin{array}{c}
y_1 \\
y_2
\end{array}
\right)=
\left(
\begin{array}{cc}
X_1 & 0 \\
0 & X_2 \\
\end{array}
\right)
\left(
\begin{array}{c}
b_1 \\
b_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
Z & 0 \\
0 & Z
\end{array}
\right)
\left(
\begin{array}{c}
u_1 \\
u_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
I & 0 \\
0 & I
\end{array}
\right)
\left(
\begin{array}{c}
e_1 \\
e_2
\end{array}
\right)
$$

where all variables are those declared in [[#Estimating a mean and a random genetic effect in a uni-variate model|above]], and subscripts $$1$$ and $$2$$ index trait $$1$$ and $$2$$, respectively.

Note that $$[u_1,u_2]\sim N([0,0],A\otimes \Sigma_a)$$ where $$A$$ is the pedigree-derived relationship matrix and
$$
\Sigma_a=
\left(\begin{array}{cc}
\sigma_{a_1}^2 & \sigma_{a_1,a_2}\\
\sigma_{a_2,a_1} & \sigma_{a_2}^2
\end{array}\right)
$$
Further, $$[e_1,e_2]\sim N([0,0],I\otimes \Sigma_e)$$ with
$$
\Sigma_e=
\left(\begin{array}{cc}
\sigma_{e_1}^2 & \sigma_{e_1,e_2}\\
\sigma_{e_2,e_1} & \sigma_{e_2}^2
\end{array}\right)
$$.

A possible data file for such mode may look like:
#y1,y2,mu,id
25.0,0.8,1,5
33.1,0.5,1,6
36.0,1.5,1,7
28.3,3.6,1,8
and the pedigree files is that provided in example [[#Estimating a mean and a random genetic effect in a uni-variate model]].

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0,0.8
0.8,1.2
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y1 = mu*b1 + id*u1(v(my_var(1)))
y2 = mu*b2 + id*u2(v(my_var(2)))
</eqn>
</model>
</root>
</syntaxhighlight>

== Example code chunks ==

'''The following code chunks are only subset of a full parameter file. It is assumed that all other parts of the instruction file are functional and all necessary input data are available and the that the data file columns have the respective names.'''

=== Providing pedigrees ===

==== Providing a pedigree containing genetic groups ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
phantomparents: 2
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a pedigree containing metafounders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
metafile: mymeta.csv
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a probabilistic pedigree ====

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<pedigrees>
pedigrees: a
<a>
switch: probabilistic
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing several pedigrees ====

<syntaxhighlight lang="xml">
<root>
...
<pedigrees>
pedigrees: a,b
<a>
...
</a>

...

</pedigrees>
...
</root>
</syntaxhighlight>

=== Providing Genotypes ===

==== Providing external allele frequencies ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
pqfile: mypq.csv 
</a>
</genotypes>
...
</root>
</syntaxhighlight>

==== Providing several genotype files ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
...
</root>
</syntaxhighlight>

=== Providing GRMs ===

==== Constructing GRM from genotypes ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Overriding the default GRM construction method ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
method: YA 
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing a GRM from file ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<grms>
grms: x
<x>
file: mygrm.csv
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing several GRMs ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
...
</root>
</syntaxhighlight>

=== Single step models ===

==== ssGBLUP model with GRM build from genotypes====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGBLUP model with GRM supplied externally ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<grms>
grms: x
<x>
file: mygrm.bin
pedigree: a
cross: id.csv
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGTBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
file: pedigree.csv
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
file: mygeno.txt
pedigree: a
cross: ids.csv
...
</a>
</genotypes>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
type: tblup
genotype: a
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssSNPBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
switch: adjustg2a
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with meta-founders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
metafile: mymeta.csv 
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
pqfile: myp.csv 
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with a separate polygenic factor ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: a,g
<a>
<sigma>
file: cov_polygenic.csv 
</sigma>
<gamma>
<A>
pedigree: a
</A>
</gamma>
</a>
<g>
type: snpblup1
genotype: a
aweight: 0.001 
switch: adjustg2a
<sigma>
file: cov_genomic.csv 
</sigma>
<marker_sb1>
<sigma>
file: cov_genomic.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*ug1(v(g(1))+dam*mg1(v(g(2))+individual*ua1(v(a(1))+dam*ma1(v(a(2))
y2=mu*b2+individual*ug2(v(g(3))+dam*mg2(v(g(4))+individual*ua2(v(a(3))+dam*ma2(v(a(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssGBLUP with two genomic factors ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a,b
<a>
...
pedigree: a
</a>

...
pedigree: a

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
<vars>
...
vars: g1,g2
<g1>
...
<gamma>
<H>
...
grm: x
</H>
</gamma>
</g1>
<g2>
...
<gamma>
<H>
...
grm: y
</H>
</gamma>
</g2>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u11(v(g1(1))+id*u21(v(g2(1))
y2=mu*b2+id*u12(v(g1(2))+id*u22(v(g2(2))
</eqn>
</models>
</root>
</syntaxhighlight>

=== Regression on continuous co-variables ===

==== Linear regression ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co))*age1
y2=mu*b2+age(t(co))*age2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== User-defined polynomial expansion ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
x^1
log(sqrt(x))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Using hard-coded Legendre polynomials ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2,3))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
l0
l1
l2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested co-variables ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
weaningweight=mu*b1+age(t(co(p(1,2);n(sex))))*age
intramuscularfatcontent=mu*b2+weight(t(co(p(1,2);n(sex))))*weight
</eqn>
<eqn attributes="strings">
x^1
x^2
</eqn>
</models>
...
</root>
</syntaxhighlight>

=== Random-regression models ===
==== Nested continuous random co-variables ====

{{cc|days}} is a co-variable which is nested within {{cc|individual}} or {{cc|dam}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(n(individual))))*u1(v(g(1))+days(t(co(n(dam))))*m1(v(g(2))
y2=mu*b2+days(t(co(n(individual))))*u2(v(g(3))+days(t(co(n(dam))))*m2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous random co-variables with polynomial expansion ====

Similar to [[#Nested continuous co-variables|Nested continuous co-variables]] but {{cc|days}} is expanded

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(p(1,2,3);n(dam))))*m1(v(g(4,5,6))
y2=mu*b2+days(t(co(p(1,2,3);n(individual))))*u2(v(g(7,8,9))+days(t(co(p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous co-variables with polynomial expansion and an integer co-variable ====

Similar to [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]], but an additional information {{cc|t(i)}} is provided telling {{lmt}} that {{cc|days}} is actually an integer. While the results do not differ from [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]] {{lmt}} can exploit this information for memory efficiency.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(t(i);p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(t(i);p(1,2,3);n(dam))))*m1(v(g(7,8,9))
y2=mu*b2+days(t(co(t(i);p(1,2,3);n(individual))))*u2(v(g(4,5,6))+days(t(co(t(i);p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials of order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
</root>
</syntaxhighlight>

=== Defining equivalent models with genetic groups ===

Note that in the parameterization provided below [[#Defining a model with absorbed genetic groups|absorbed genetic groups]] and [[#Defining a model with genetic groups as extra factor|genetic groups as extra factor]] must yield the same results. However, only when using {{cc|absorbed genetic groups}} the factor level solutions are the actual breeding values. When modelling genetic groups as an extra factor genetic factor solutions and genetic group factor solutions must be added by the user.

==== Defining a model with absorbed genetic groups ====

Note that the only information necessary is the number of phantom parents '''at the top of the pedigree'''({{cc|phantomparents: 10}}) and the information to the variance that the it should be constructed allowing for genetic groups({{cc|switch gg}}).

<syntaxhighlight lang="xml" line highlight="6,19">
<root>
<pedigrees>
pedigrees: a
<a>
file: myped.csv
phantomparents: 10
</a>
<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: a
switch: gg
</A>
</gamma>
</g>
</vars>
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Defining a model with genetic groups as extra random factor ====

Genetic groups are defined as an extra factor, which requires an extra variance({{cc|gg}}) and two pedigrees, the genetic group pedigree({{cc|a}}) and the normal pedigree({{cc|b}}). For a model equivalent to [[#Defining a model with absorbed genetic groups|absorption]] pedigree {{cc|b}} must be a subset of pedigree {{cc|a}}. Further, if breeding values are required {{lmt}} can provide the genetic group regression matrix {{cc|qfile: Q.coocsv}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g,gg
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
<gg>
<sigma>
file: myG.csv <! must contain a 4x4 matrix. should be the same as for "g">
</sigma>
</gg>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1(v(gg(1))+dam(t(gg(a)))*damgg1(v(gg(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2(v(gg(2))+dam(t(gg(a)))*damgg2(v(gg(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== Defining a model with fixed genetic groups ====

Fixed genetic groups are only supported if modeled as an extra factor. Therefore, the model is similar to [[#Defining a model with genetic groups as extra random factor|above]], but the extra variance is omitted. Note that when modeling genetic groups as fixed it is the users responsibility to omit one group from the respective pedigree to ensure that $$X$$ is of full column rank. [[#Linear models in lmt:Column rank of $$X$$|bla]]

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1+dam(t(gg(a)))*damgg1
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2+dam(t(gg(a)))*damgg2
</eqn>
</models>
</root>
</syntaxhighlight>

=== Override the default job parameters ===

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<jobs>
jobs: default
<default>
conv: -9.21 <! log(10e-5)>
</default>
</jobs>
...
</root>
</syntaxhighlight>

=== Use job "solve" instead of "default" ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>
</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Use a direct solver in stead of the default solver ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>
<direct>
</direct>
</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using Gibbs sampling ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: sample
<sample>
sampler: x
</sample>
</jobs>
<samplers>
samplers: x
<x>
<blocked>
samples: 100000
</blocked>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using AI-REML-C ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: airemlc
<airemlc>
</airemlc>
</jobs>
...
</root>
</syntaxhighlight>

=== Calculating exact prediction error co-variances using a direct solver===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>
<direct>
</direct>
</a>
</solvers>
...
</root>
</syntaxhighlight>

=== Calculating prediction error co-variances for a target individual===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: pevsolve
<pevsolve>
solver: a
factor: g 
levels: 1156679414 
</pevsolve>
</jobs>
<solvers>
solvers: a
<a>

</a>
</solvers>
...
</root>
</syntaxhighlight>

Parameter file elements

2022-05-16T05:46:21Z

127.0.0.1: /* airemlc> */

Below is a list of all possible parameter file xml elements. For each element an example is provided as well as information about the element's host element, the element's type and the element's content. '''Note that all words(element names, key string words, key string variables) in bold are hard-coded, all in italic are user-defined (this does not apply to the example box)'''. The spelling of hard-coded words must be abide by, the spelling of user-defined words is user-defined.

=<'''model'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<model>
<eqn attribute="strings">
..
</eqn>
<poly attribute="strings">
..
</poly>
</model>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}compulsory
{{!}}hosts information about the equations and the polynomials.
}}

content:

*compulsory element '''<eqn attributes="strings">'''
*optional element '''<poly attributes="strings">'''
==<'''eqn'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<model>
<eqn attribute="strings">
y1=x*b1+z*u1(v(g(1))
y2=x*b2+z*u2(v(g(2))
y3=x*b3+a(t(co(p(1,2);n(k))))*c1+z*u3(v(g(3)))
</eqn>
..
</model>
</root>
</syntaxhighlight>
{{!}}'''model'''
{{!}}compulsory
{{!}}hosts information about the equations.
}}

content:

*[[linear mixed models in lmt#Model_syntax|model strings]] which are escaped from the formatting rules by adding '''attributes="strings"''' to the start tag.

==<'''poly'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<model>
<poly attribute="strings">
x^0
x^2
3*x^2+sqrt(sin(x))
</poly>
..
</model>
</root>
</syntaxhighlight>
{{!}}'''model'''
{{!}}optional
{{!}}hosts user defined polynomials and references to hard-coded polynomials. Note that there can only be one polynomial per line. Model strings will reference polynomials by their line number.
}}

content

*[[linear mixed models in lmt#Polynomials|polynomial strings]] which are escaped from the formatting rules by adding '''attributes="strings"''' to the start tag.

=<'''pedigrees'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<pedigrees>
pedigrees: a,b
...
</pedigrees>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}automatic-optional
{{!}}hosts one to several elements each containing information about a specific pedigree}}

content:
*key strings
{{tablekeys2|
{{!}}'''pedigrees'''
{{!}}'''pedigrees''': ''a,b''
{{!}}compulsory
{{!}}csv word-list
{{!}}''pedigree names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements}}
*nominated-compulsory elements
==<''pedigree name''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<pedigrees>
pedigrees: myped
..
<myped>
file: myped.csv
switch: selfing
phantomparents: 2
qfile: myq.coocsv
</myped>
..
</pedigrees>
</root>
</syntaxhighlight>
{{!}}'''pedigrees'''
{{!}}nominated-compulsory
{{!}}hosts information about a specific pedigree identified by ''pedigree name''
}}
content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''myped.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}list content determines the name of the file containing the pedigree
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''selfing'''
{{!}}optional
{{!}}csv-word-list
{{!}}'''selfing,probabilistic'''
{{!}}none
{{!}}list content determines pedigree properties.
*'''selfing''': both parents can have the same id
*'''probabilistic''': each individual can have more than 1 pair of parents
{{!}}-
{{!}}'''phantomparents'''
{{!}}'''phantomparents''': 2
{{!}}optional
{{!}}single numeric value
{{!}}positive integer
{{!}}none
{{!}}integer number determines the number of individuals at the top of the pedigree which are phantom parents
{{!}}-
{{!}}'''qfile'''
{{!}}'''qfile''': myq.coocsv
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}provides name of file to which the genetic regression matrix should be written. Supported file name suffixes are ".bin" for binary block file, ".blkcsv" for csv blockfile and ".coocsv" for csv coordinate format.
{{!}}-
{{!}}'''metafile'''
{{!}}'''metafile''': meta.csv
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}provides name of the file containing the metafounder co-variance matrix.
}}

=<'''genotypes'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<genotypes>
genotypes: a,b
...
</genotypes>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}automatic-optional
{{!}}hosts one to several elements each containing information about different sets of genotypes
}}

content:
*key strings
{{tablekeys2|
{{!}}'''genotypes'''
{{!}}'''genotypes''': ''a,b''
{{!}}compulsory
{{!}}csv word-list
{{!}}''genotype names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements
}}
*nominated-compulsory elements
==<''genotype name''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<genotypes>
genotypes: mygn
..
<mygn>
file: genotypes.txt
pedigree: myped
cross: crossref.csv
</mygn>
..
</genotypes>
</root>
</syntaxhighlight>
{{!}}'''genotypes'''
{{!}}nominated-compulsory
{{!}}hosts information about a specific set of genotypes identified by ''genotype name''
}}
content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''genotype.txt''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the genotypes
{{!}}-
{{!}}'''cross'''
{{!}}'''cross''': ''mycross.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the pedigree ids related to the genotypes
{{!}}-
{{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}optional
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree previously invoked pedigree related to the content of the cross-reference file
{{!}}-
{{!}}'''pqfile'''
{{!}}'''pqfile''': ''mypq.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the allele frequencies. Note that the file content is used as a substitute for the column means of the marker matrix. It must therefore contain 2p.
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''ignorefixed'''
{{!}}optional
{{!}}csv word-list
{{!}}'''ignorefixed,ignoremissing'''
{{!}}none
{{!}}
*ignorefixed: fixed markers are ignored '''but may lead to program crash or spurious results latter on'''
*ignoremissing: marker coded as missing(3) are set to 0.
}}

=<'''grms'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<grms>
grms: a,b
...
</grms>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}automatic-optional
{{!}}hosts one to several elements each containing information about a specific grm
}}

content:
*key strings
{{tablekeys2|
{{!}}'''grms'''
{{!}}'''grms''': ''x,y''
{{!}}compulsory
{{!}}csv word-list
{{!}}''grm names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements
}}
*nominated-compulsory elements
==<''grm name''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<grms>
grms: mygrm
..
<mygrm>
genotype: mygn
method: YA
</mygrm>
..
</genotypes>
</root>
</syntaxhighlight>
{{!}}'''grms'''
{{!}}nominated-compulsory
{{!}}hosts information about a specific grm identified by ''grm name''
}}
content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''mygrm.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the grm. mutually exclusive with keyword '''genotype'''.
{{!}}-
{{!}}'''genotype'''
{{!}}'''genotype''': ''mygn''
{{!}}compulsory
{{!}}word
{{!}}''genotype name''
{{!}}none
{{!}}content determines the genotype element to be used for building the grm. mutually exclusive with keyword '''file'''.
{{!}}-
{{!}}'''cross'''
{{!}}'''cross''': ''mycross.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the pedigree ids related to the genotypes. if this information has already been supplied to the genotypes it cannot be supplied here.
{{!}}-
{{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}optional
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree previously invoked pedigree related to the content of the cross-reference file. if this information has already been supplied to the genotypes it cannot be supplied here.
{{!}}-
{{!}}'''method'''
{{!}}'''method''':'''YA'''
{{!}}optional
{{!}}alternative words
{{!}}'''VR<nowiki>|</nowiki>YA'''
{{!}}'''VR'''
{{!}}content determines the method to be used for building a grm from genotypes
*'''VR''': VanRaden Method 1 is used
*'''YA''': VanRaden Method 2(method Yang) is used
{{!}}-
{{!}}'''outfile'''
{{!}}'''outfile''': ''mygrm.bin''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file where the grm should be written to. will only take effect if the grm was build from genotypes. if the genotypes had a pedigree assigned a cross-reference file will be written out as well which contains the original pedigree ids of the genotyped individuals in the order of the rows/columns of the grm. the file name of the cross-reference file is that of the grm with the prefix '''cross_'''.
}}

=<'''vars'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
vars: g,p
...
</vars>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}compulsory
{{!}}hosts one to several elements each containing information about a specific variance.
}}

content:
*key strings
{{tablekeys2|
{{!}}'''vars'''
{{!}}'''vars''': ''g,p''
{{!}}compulsory
{{!}}csv word-list
{{!}}''variance names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements
}}
*nominated-compulsory elements
*compulsory element '''<res>'''
=='''Kronecker products'''==
Variance structures below are Kronecker products $$\Gamma \otimes \Sigma$$. If no '''type''' keystring is provided this is the default.
==='''<res>'''===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
<res>
<sigma>
..
</sigma>
</res>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''vars'''
{{!}}compulsory
{{!}}hosts information about the residual variance structure.
}}

content:
*compulsory element [[#<sigma>|'''<sigma>''']]
*optional element [[#<gamma>|'''<gamma>''']]

===''<variance name>''===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
..
</sigma>
<gamma>
..
</gamma>
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''vars'''
{{!}}nominated-compulsory
{{!}}hosts information about variance structure identified by ''variance name''.
}}

content:
*compulsory element [[#<sigma>|'''<sigma>''']]
*optional element [[#<gamma>|'''<gamma>''']]

*key strings
{{tablekeys2|
1={{!}}'''type'''
{{!}}'''type''': ''kronecker''
{{!}}optional
{{!}}word
{{!}}''kronecker,snpblup_1''
{{!}}kronecker
{{!}}determines whether the variance structure deviates from a Kronecker product.
}}

===='''<sigma>'''====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
..
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''variance name''
{{!}}compulsory
{{!}}hosts information about $$\Sigma$$ as part of [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]].
}}

content:

*key strings
{{tablekeys2|
1={{!}}'''file'''
{{!}}'''file''': ''mymatrix.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the $$\Sigma$$ matrix. is mutually exclusive with '''<nowiki><matrix attributes="array"></nowiki>'''.
{{!}}-
{{!}}'''type'''
{{!}}'''type''': '''block'''
{{!}}optional
{{!}}word
{{!}}'''block'''
{{!}}none
{{!}}determines that $$\Sigma$$ is equal to [[Supported_features#Supported_variance_structures|$$\Theta$$]]
{{!}}-
{{!}}'''scale'''
{{!}}'''scale''': ''0.05''
{{!}}optional
{{!}}single numeric value
{{!}}real number>0.0
{{!}}none
{{!}}multiplies $$\Sigma$$ once by the provided value after reading.
{{!}}-
{{!}}'''priordf'''
{{!}}'''priordf''': ''10''
{{!}}optional
{{!}}single numeric value
{{!}}real number>=0.0
{{!}}0.0
{{!}}prior degree of freedom when doing Gibbs sampling
{{!}}-
{{!}}'''maskfile'''
{{!}}'''maskfile''': ''mymatrixmask.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing a T/F matrix of the same dimension as the respective $$\Sigma$$ matrix. Is mutually exclusive with '''<nowiki><maskmatrix attributes="array"></nowiki>'''.
}}

*optional element '''<matrix attributes="array">'''
=====<'''matrix attributes="array"'''>=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
<matrix attributes="array">
5.0,0.5
0.5,1.8
</matrix>
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''sigma'''
{{!}}optional
{{!}}hosts the content of a single $$\Sigma$$ matrix. Is mutually exclusive with key string '''file: '''.
}}
=====<'''maskmatrix attributes="array"'''>=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
<maskmatrix attributes="array">
T,F
F,T
</matrix>
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''sigma'''
{{!}}optional
{{!}}hosts the content of a single indicator matrix of the same dimensions as the respective $$\Sigma$$ matrix. Is mutually exclusive with key string '''maskfile: '''.
}}

===='''<gamma>'''====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
..
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''variance name''
{{!}}optional
{{!}}hosts information about $$\Gamma$$ as part of [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]]. If absent $$\Gamma$$ defaults to $$I$$.
}}

content:

*mutually exclusive elements '''<A>, <H>, <G> and <E>'''

====='''<A>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<A>
pedigree: myped
</A>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma$$ being constructed as the numerator relationship matrix A using pedigree ''pedigree name''.
}}

content:
*key strings
{{tablekeys2|
{{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}optional
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree previously invoked to be used to construct A.
{{!}}-
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''gg'''
{{!}}optional
{{!}}csv word-list
{{!}}'''gg'''
{{!}}none
{{!}}
*gg: the pedigree contains genetic groups which will be fitted as random
}}

====='''<H>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<H>
type: tblup
pedigree: myped
genotype: mygn
aweight: 0.05
switch: adjustg2a
</H>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma$$ being constructed as combined single step relationship matrix H using pedigree ''pedigree name'' and genomic information. the genomic information can be supplied
*via a grm element for single step H-BLUP models
*via a genotype element for single step T-BLUP models
Note that for '''type:tblup''' it is not necessary to have an automatic-optional [[#<grms>|<grms>]] element in the parameter file. Doing so will cause the construction and RAM-storage of $$G$$ although it is not need for building H, thus maybe leading to substantial increase in processing time and RAM demand.
}}

content:
*key strings
{{tablekeys2|
1={{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}compulsory
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree element to be used to construct H.
{{!}}-
{{!}}'''type'''
{{!}}'''type''': '''tblup'''
{{!}}optional
{{!}}word
{{!}}'''tblup<nowiki>|</nowiki>gblup'''
{{!}}'''gblup'''
{{!}}content determines the way the inverse of H is constructed.
{{!}}-
{{!}}'''grm'''
{{!}}'''grm''': ''mygrm''
{{!}}conditional-compulsory
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the grm element to be used to construct H. compulsory for '''type: hblup'''.
{{!}}-
{{!}}'''genotype'''
{{!}}'''genotype''': ''mygn''
{{!}}conditional-compulsory
{{!}}word
{{!}}''genotype name''
{{!}}none
{{!}}content determines the genotype element to be used to construct H. compulsory for '''type: tblup'''.
{{!}}-
{{!}}'''aweight'''
{{!}}'''aweight: 0.05'''
{{!}}optional
{{!}}single numeric value
{{!}}0.0<=aweight<=1.0
{{!}}0.0
{{!}}blending of $$G$$ with $$A_{gg}$$ by $$G_w=aweight\times A_{gg}+(1-aweight)\times G$$
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''adjustg2a'''
{{!}}optional
{{!}}csv word-list
{{!}}'''adjustg2a,gg,diag'''
{{!}}none
{{!}}
*adjustg2a: adjustment of $$G$$ towards $$A_{gg}$$ using method
*gg: the pedigree contains genetic groups which will be fitted as random
*diag: calculate H diagonal elements and write to file (only supported for gblup).
{{!}}-
{{!}}'''grmdadd'''
{{!}}'''grmdadd''': ''0.05''
{{!}}optional
{{!}}single numeric value
{{!}}real number >=0.0
{{!}}none
{{!}} value added to the diagonal of $$G$$ to ensure invertibility. The policy is
*if '''aweight'''>0.0, nothing will be added to the diagonals
*if '''aweight''' is not supplied or is zero:
** if '''grmdadd''' is not supplied 0.001 will be added to the diagonals
** otherwise '''grmdadd''' will be used
}}

====='''<G>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<G>
grm: mygrm
</G>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma$$ being constructed from a genomic relationsship matrix.
}}

content:
*key strings
{{tablekeys2|
1={{!}}'''grmdadd'''
{{!}}'''grmdadd''': ''0.05''
{{!}}optional
{{!}}single numeric value
{{!}}real number >=0.0
{{!}}none
{{!}} value added to the diagonal of $$G$$ to ensure invertibility.
}}

====='''<E>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<E>
file: mygamma.csv
</E>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma^{-1}$$ being uploaded from a file.
}}

content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''mygamma.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the file which contains $$\Gamma^{-1}$$.
{{!}}-
{{!}}'''type'''
{{!}}'''type''': '''dense'''
{{!}}optional
{{!}}word
{{!}}'''dense<nowiki>|</nowiki>sparse_csr_ut'''
{{!}}'''sparse_csr_ut'''
{{!}}content determines the file storage of $$\Gamma^{-1}$$
*dense: full squared symmetric matrix
*sparse_csr_ut: squared symmetric sparse upper triangular matrix in [https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_row_(CSR,_CRS_or_Yale_format) csr] format
}}

=='''snpblup1'''==

===''<variance name>''===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
genotype: mygn
aweight: 0.05
switch: adjustg2a
<sigma>
..
</sigma>
<gamma>
..
</gamma>
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''vars'''
{{!}}nominated-compulsory
{{!}}hosts information about variance structure identified by ''variance name''.
}}

content:
*compulsory element '''<sigma>'''
*compulsory element [[#<marker_sb1>|'''<marker_sb1>''']]

*key strings
{{tablekeys2|
1={{!}}'''type'''
{{!}}'''type''': ''kronecker''
{{!}}optional
{{!}}word
{{!}}''kronecker,snpblup_1''
{{!}}kronecker
{{!}}determines whether the variance structure deviates from a Kronecker product.
{{!}}-
{{!}}'''genotype'''
{{!}}'''genotype''': ''mygn''
{{!}}conditional-compulsory
{{!}}word
{{!}}''genotype name''
{{!}}none
{{!}}content determines the genotype element to be used to construct H. compulsory for '''type: tblup'''.
{{!}}-
{{!}}'''aweight'''
{{!}}'''aweight: 0.05'''
{{!}}optional
{{!}}single numeric value
{{!}}0.0<=aweight<=1.0
{{!}}0.0
{{!}}blending of $$G$$ with $$A_{gg}$$ by $$G_w=aweight\times A_{gg}+(1-aweight)\times G$$
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''adjustg2a'''
{{!}}optional
{{!}}csv word-list
{{!}}'''adjustg2a,gg,diag'''
{{!}}none
{{!}}
*adjustg2a: adjustment of $$G$$ towards $$A_{gg}$$ using method
*gg: the pedigree contains genetic groups which will be fitted as random
*diag: calculate H diagonal elements and write to file (only supported for gblup).
}}

===='''<sigma>'''====

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
<sigma>
..
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''variance name''
{{!}}compulsory
{{!}}hosts information about $$\Sigma$$ for the poly-genetic part of the variance structure.
}}

content:

see [[#<sigma>|'''<sigma''']]

===='''<marker_sb1>'''====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
..
<marker_sb1>
..
</marker_sb1>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''marker''
{{!}}compulsory
{{!}}hosts information about the co-variance between and within markers following [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]].
}}

content:

*compulsory element '''<sigma>'''
*optional element '''<gamma>'''

====='''<sigma>'''=====

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
..
<marker_sb1>
<sigma>
..
</sigma>
..
</marker_sb1>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''marker''
{{!}}compulsory
{{!}}hosts information about $$\Sigma$$ as part of [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]] for the marker part of the variance structure. Note that $$\Sigma$$ will be scaled by (1-aweight).
}}

see [[#<sigma>|'''<sigma>''']]

=<'''jobs'''>=

{{tableele2|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: solve,yh
...
</jobs>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}optional
{{!}}hosts one to several elements each containing information about a specific job
{{!}}run default job(solve) in default parameterization(default pcgiod parameterization)
}}

content:
*key strings
{{tablekeys2|
{{!}}'''jobs'''
{{!}}'''jobs''': '''solve,yhat'''
{{!}}compulsory
{{!}}csv word-list
{{!}}'''solve,sample,pevsample,mcemreml,yhat'''
{{!}}none
{{!}}job sequence is determined by the list sequence. list content determines nominated-compulsory elements
}}

*nominated-compulsory elements
**'''<default>'''
**'''<solve>'''
**'''<sample>'''
**'''<pevsample>'''
**'''<pevsolve>'''
**'''<mcemreml>'''
**'''<airemlc>'''
**'''<yhat>'''

==<'''default'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
..
<default>
conv: -18.42
</default>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''default'''
}}

content: see [[#<pcgiod>|<pcgiod>]] for a list of all possible key strings

==<'''solve'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
..
<solve>
solver: mysolver
</solve>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''solve'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''solver'''
{{!}}'''solver''': ''mysolver''
{{!}}compulsory
{{!}}word
{{!}}''solver name''
{{!}}none
{{!}}''solver name'' must be the name of a previously defined solver
}}

==<'''sample'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: sample,..
<sample>
sampler: mysampler
</sample>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''sample'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''sampler'''
{{!}}'''sampler''': ''mysampler''
{{!}}compulsory
{{!}}word
{{!}}''sampler name''
{{!}}none
{{!}}''sampler name'' must be the name of a previously defined sampler
}}

==<'''pevsample'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: pevsample,..
<pevsample>
sampler: mysampler
</pevsample>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''pevsample'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''sampler'''
{{!}}'''sampler''': ''mysampler''
{{!}}compulsory
{{!}}word
{{!}}''sampler name''
{{!}}none
{{!}}''sampler name'' must be the name of a previously defined sampler of type pev
}}

==<'''pevsolve'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: pevsolve,..
<pevsolve>
solver: mysolver
</pevsolver>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''pevsolve'''
}}

content:

*key strings
{{tablekeys2|
1={{!}}'''solver'''
{{!}}'''solver''': ''mysolver''
{{!}}compulsory
{{!}}word
{{!}}''solver name''
{{!}}none
{{!}}''solver name'' must be the name of a previously defined solver
{{!}}-
{{!}}'''factor'''
{{!}}'''factor''': ''gen''
{{!}}compulsory
{{!}}word
{{!}}''factor name''
{{!}}none
{{!}}''factor name'' must be the name of a random factor
{{!}}-
{{!}}'''levels'''
{{!}}'''levels''': ''5,10,20''
{{!}}optional
{{!}}csv integer list
{{!}}''factor level ids''
{{!}}none
{{!}}original factor level ids(.e.g. pedigree ids etc). If not supplied the prediction error co-variance blocks of all factor levels associated to the nominated factor will be calculated. Mutually exclusive with '''levelfile'''.
{{!}}-
{{!}}'''levelfile'''
{{!}}'''levelfile''': ''myfile.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}file containing original factor level ids(.e.g. pedigree ids etc). If not supplied the prediction error co-variance blocks of all factor levels associated to the nominated factor will be calculated. Mutually exclusive with '''levels'''.
{{!}}-
{{!}}'''nrhs'''
{{!}}'''nrhs''': ''50''
{{!}}optional
{{!}}integer
{{!}}''number of right-hand sides''
{{!}}1000
{{!}}number of right-hand-sides to be solved for simultaneously. Has only effect if the direct solver is used. The default may exceed the available RAM.
}}

==<'''airemlc'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: airemlc,..
<airemlc>
rounds: 50
..
</airemlc>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''airemlc'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''rounds'''
{{!}}'''rounds''': ''10''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}20
{{!}}provides the number of aireml-rounds to run
{{!}}-
{{!}}'''convtype'''
{{!}}'''convtype''': '''ng'''
{{!}}optional
{{!}}word
{{!}}'''cd<nowiki>|</nowiki>ng<nowiki>|</nowiki>ll<nowiki>|</nowiki>any<nowiki>|</nowiki>all'''
{{!}}'''cd'''
{{!}}provides the convergence criterion to use
* ll: log of relative change in log-likelihood
* ng: log of the norm of the gradient vector
* cd: log of the relative change of the parameter vector
* all: all of the above
* any: any of the above
{{!}}-
{{!}}'''convll'''
{{!}}'''convll''': ''-10.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''-6.907755''
{{!}}provides the convergence threshold for convergence criterion '''ll'''
{{!}}-
{{!}}'''convng'''
{{!}}'''convng''': ''-10.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''-16.1181''
{{!}}provides the convergence threshold for convergence criterion '''ng'''
{{!}}-
{{!}}'''convcd'''
{{!}}'''convcd''': ''-10.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''-16.1181''
{{!}}provides the convergence threshold for convergence criterion '''cd'''
{{!}}-
{{!}}'''nscale'''
{{!}}'''nscale''': ''0.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''1.0''
{{!}}scales the length of the Newton step.
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''residuals'''
{{!}}optional
{{!}}csv word-list
{{!}}any real number
{{!}}'''writeai,residuals'''
{{!}}
*'''writeai''': write ai matrix and gradient vector to files ai_ai.csv and ai_ja.csv.
*'''residuals''': after convergence write the residuals to file aic_residuals.csv
}}

==<'''mcemreml'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: mcemreml,..
<mcemreml>
emrounds: 500
sampler: mysampler
</mcemreml>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''mcemreml'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''emrounds'''
{{!}}'''emrounds''': ''500''
{{!}}compulsory
{{!}}numeric value
{{!}}positive integer
{{!}}none
{{!}}provides the number of mcemreml-rounds to run
{{!}}-
{{!}}'''sampler'''
{{!}}'''sampler''': ''mysampler''
{{!}}compulsory
{{!}}word
{{!}}''sampler name''
{{!}}none
{{!}}''sampler name'' must be the name of a previously defined sampler
}}

==<'''yhat'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: yhat,..
<yhat>
</yhat>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''yhat'''
}}
Currently '''yhat''' has no key strings or nested elements defined.

=<'''samplers'''>=

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,b,..
...
</samplers>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}optional
{{!}}hosts one to several elements each containing information about a specific sampler
}}

content:
*key strings
{{tablekeys2|
{{!}}'''samplers'''
{{!}}'''samplers''': ''a''
{{!}}compulsory
{{!}}csv word-list
{{!}}''sampler names''
{{!}}none
{{!}}list content determines nominated-compulsory elements
}}
*conditional-compulsory elements

==<''sampler name''>==

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
..
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}'''samplers'''
{{!}}conditional-compulsory
{{!}}hosts one of several mutually exclusive elements defining the type of sampler ''sampler name''
}}

content:
*compulsory mutually exclusive elements
**'''<singlepass>'''
**'''<blocked>'''
**'''<pev>'''

===<'''singlepass'''>===

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
<singlepass>
samples: 10000
burnin: 1000
</singlepass>
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}''sampler name''
{{!}}compulsory
{{!}}defines parameters of a sampler of type '''singlepass'''
}}

*key strings
{{tablekeys2|
{{!}}'''samples'''
{{!}}'''samples''': ''100000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the total number of samples to draw
{{!}}-
{{!}}'''burnin'''
{{!}}'''burnin''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}0
{{!}}provides the number of samples to be discarded as burnin
}}

===<'''blocked'''>===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
<blocked>
samples: 10000
burnin: 1000
</blocked>
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}''sampler name''
{{!}}compulsory
{{!}}defines parameters of a sampler of type '''blocked'''
}}

*key strings
{{tablekeys2|
{{!}}'''samples'''
{{!}}'''samples''': ''100000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the total number of samples to draw
{{!}}-
{{!}}'''burnin'''
{{!}}'''burnin''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}0
{{!}}provides the number of samples to be discarded as burnin
}}

===<'''pev'''>===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
<pev>
samples: 10000
burnin: 1000
chains: 10
</pev>
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}''sampler name''
{{!}}compulsory
{{!}}defines parameters of a sampler of type '''pev'''
}}

*key strings
{{tablekeys2|
{{!}}'''samples'''
{{!}}'''samples''': ''100000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the total number of samples to draw
{{!}}-
{{!}}'''burnin'''
{{!}}'''burnin''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}0
{{!}}provides the number of samples to be discarded as burnin
{{!}}-
{{!}}'''chains'''
{{!}}'''chains''': ''10''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}1
{{!}}provides the number of parallel chains to run
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''trace'''
{{!}}optional
{{!}}word
{{!}}'''trace'''
{{!}}none
{{!}}changes sampler from sampling prediction error variances to sampling traces required for emreml
}}

=<'''solvers'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,b,..
...
</solvers>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}optional
{{!}}hosts one to several elements each containing information about a specific solver
}}

content:
*key strings
{{tablekeys2|
{{!}}'''solvers'''
{{!}}'''solvers''': ''a''
{{!}}compulsory
{{!}}csv word-list
{{!}}''solver names''
{{!}}none
{{!}}list content determines nominated-compulsory elements
}}
*conditional-compulsory elements

==<''solver name''>==

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,..
<a>
..
</a>
</solvers>
</root>
</syntaxhighlight>
{{!}}'''solvers'''
{{!}}conditional-compulsory
{{!}}hosts one of several mutually exclusive elements defining the type of solver ''solver name''
}}

content:
*compulsory mutually exclusive elements with default element
**'''<pcgiod>''', default
**'''<direct>'''

===<'''pcgiod'''>===

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,..
<a>
<pcgiod>
rounds: 1000
conv: -20.0
</pcgiod>
</a>
</solvers>
</root>
</syntaxhighlight>
{{!}}''solver name''
{{!}}compulsory
{{!}}defines parameters of a solver of type '''pcgiod'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''rounds'''
{{!}}'''rounds''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the maximum number of rounds to run
{{!}}-
{{!}}'''conv'''
{{!}}'''conv''': ''-15.0''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}} -18.42
{{!}}provides the convergence threshold
{{!}}-
{{!}}'''convtype'''
{{!}}'''convtype''': '''cd'''
{{!}}optional
{{!}}word
{{!}}'''cr<nowiki>|</nowiki>cd'''
{{!}} '''cr'''
{{!}}provides the convergence parameter type
}}

===<'''direct'''>===

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,..
<a>
<direct>
</direct>
</a>
</solvers>
</root>
</syntaxhighlight>
{{!}}''solver name''
{{!}}compulsory
{{!}}defines parameters of a solver of type '''direct'''
}}

content: no content defined

Parameter file elements

2022-05-15T23:32:38Z

127.0.0.1: /* airemlc> */

Below is a list of all possible parameter file xml elements. For each element an example is provided as well as information about the element's host element, the element's type and the element's content. '''Note that all words(element names, key string words, key string variables) in bold are hard-coded, all in italic are user-defined (this does not apply to the example box)'''. The spelling of hard-coded words must be abide by, the spelling of user-defined words is user-defined.

=<'''model'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<model>
<eqn attribute="strings">
..
</eqn>
<poly attribute="strings">
..
</poly>
</model>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}compulsory
{{!}}hosts information about the equations and the polynomials.
}}

content:

*compulsory element '''<eqn attributes="strings">'''
*optional element '''<poly attributes="strings">'''
==<'''eqn'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<model>
<eqn attribute="strings">
y1=x*b1+z*u1(v(g(1))
y2=x*b2+z*u2(v(g(2))
y3=x*b3+a(t(co(p(1,2);n(k))))*c1+z*u3(v(g(3)))
</eqn>
..
</model>
</root>
</syntaxhighlight>
{{!}}'''model'''
{{!}}compulsory
{{!}}hosts information about the equations.
}}

content:

*[[linear mixed models in lmt#Model_syntax|model strings]] which are escaped from the formatting rules by adding '''attributes="strings"''' to the start tag.

==<'''poly'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<model>
<poly attribute="strings">
x^0
x^2
3*x^2+sqrt(sin(x))
</poly>
..
</model>
</root>
</syntaxhighlight>
{{!}}'''model'''
{{!}}optional
{{!}}hosts user defined polynomials and references to hard-coded polynomials. Note that there can only be one polynomial per line. Model strings will reference polynomials by their line number.
}}

content

*[[linear mixed models in lmt#Polynomials|polynomial strings]] which are escaped from the formatting rules by adding '''attributes="strings"''' to the start tag.

=<'''pedigrees'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<pedigrees>
pedigrees: a,b
...
</pedigrees>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}automatic-optional
{{!}}hosts one to several elements each containing information about a specific pedigree}}

content:
*key strings
{{tablekeys2|
{{!}}'''pedigrees'''
{{!}}'''pedigrees''': ''a,b''
{{!}}compulsory
{{!}}csv word-list
{{!}}''pedigree names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements}}
*nominated-compulsory elements
==<''pedigree name''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<pedigrees>
pedigrees: myped
..
<myped>
file: myped.csv
switch: selfing
phantomparents: 2
qfile: myq.coocsv
</myped>
..
</pedigrees>
</root>
</syntaxhighlight>
{{!}}'''pedigrees'''
{{!}}nominated-compulsory
{{!}}hosts information about a specific pedigree identified by ''pedigree name''
}}
content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''myped.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}list content determines the name of the file containing the pedigree
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''selfing'''
{{!}}optional
{{!}}csv-word-list
{{!}}'''selfing,probabilistic'''
{{!}}none
{{!}}list content determines pedigree properties.
*'''selfing''': both parents can have the same id
*'''probabilistic''': each individual can have more than 1 pair of parents
{{!}}-
{{!}}'''phantomparents'''
{{!}}'''phantomparents''': 2
{{!}}optional
{{!}}single numeric value
{{!}}positive integer
{{!}}none
{{!}}integer number determines the number of individuals at the top of the pedigree which are phantom parents
{{!}}-
{{!}}'''qfile'''
{{!}}'''qfile''': myq.coocsv
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}provides name of file to which the genetic regression matrix should be written. Supported file name suffixes are ".bin" for binary block file, ".blkcsv" for csv blockfile and ".coocsv" for csv coordinate format.
{{!}}-
{{!}}'''metafile'''
{{!}}'''metafile''': meta.csv
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}provides name of the file containing the metafounder co-variance matrix.
}}

=<'''genotypes'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<genotypes>
genotypes: a,b
...
</genotypes>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}automatic-optional
{{!}}hosts one to several elements each containing information about different sets of genotypes
}}

content:
*key strings
{{tablekeys2|
{{!}}'''genotypes'''
{{!}}'''genotypes''': ''a,b''
{{!}}compulsory
{{!}}csv word-list
{{!}}''genotype names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements
}}
*nominated-compulsory elements
==<''genotype name''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<genotypes>
genotypes: mygn
..
<mygn>
file: genotypes.txt
pedigree: myped
cross: crossref.csv
</mygn>
..
</genotypes>
</root>
</syntaxhighlight>
{{!}}'''genotypes'''
{{!}}nominated-compulsory
{{!}}hosts information about a specific set of genotypes identified by ''genotype name''
}}
content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''genotype.txt''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the genotypes
{{!}}-
{{!}}'''cross'''
{{!}}'''cross''': ''mycross.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the pedigree ids related to the genotypes
{{!}}-
{{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}optional
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree previously invoked pedigree related to the content of the cross-reference file
{{!}}-
{{!}}'''pqfile'''
{{!}}'''pqfile''': ''mypq.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the allele frequencies. Note that the file content is used as a substitute for the column means of the marker matrix. It must therefore contain 2p.
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''ignorefixed'''
{{!}}optional
{{!}}csv word-list
{{!}}'''ignorefixed,ignoremissing'''
{{!}}none
{{!}}
*ignorefixed: fixed markers are ignored '''but may lead to program crash or spurious results latter on'''
*ignoremissing: marker coded as missing(3) are set to 0.
}}

=<'''grms'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<grms>
grms: a,b
...
</grms>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}automatic-optional
{{!}}hosts one to several elements each containing information about a specific grm
}}

content:
*key strings
{{tablekeys2|
{{!}}'''grms'''
{{!}}'''grms''': ''x,y''
{{!}}compulsory
{{!}}csv word-list
{{!}}''grm names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements
}}
*nominated-compulsory elements
==<''grm name''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<grms>
grms: mygrm
..
<mygrm>
genotype: mygn
method: YA
</mygrm>
..
</genotypes>
</root>
</syntaxhighlight>
{{!}}'''grms'''
{{!}}nominated-compulsory
{{!}}hosts information about a specific grm identified by ''grm name''
}}
content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''mygrm.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the grm. mutually exclusive with keyword '''genotype'''.
{{!}}-
{{!}}'''genotype'''
{{!}}'''genotype''': ''mygn''
{{!}}compulsory
{{!}}word
{{!}}''genotype name''
{{!}}none
{{!}}content determines the genotype element to be used for building the grm. mutually exclusive with keyword '''file'''.
{{!}}-
{{!}}'''cross'''
{{!}}'''cross''': ''mycross.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the pedigree ids related to the genotypes. if this information has already been supplied to the genotypes it cannot be supplied here.
{{!}}-
{{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}optional
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree previously invoked pedigree related to the content of the cross-reference file. if this information has already been supplied to the genotypes it cannot be supplied here.
{{!}}-
{{!}}'''method'''
{{!}}'''method''':'''YA'''
{{!}}optional
{{!}}alternative words
{{!}}'''VR<nowiki>|</nowiki>YA'''
{{!}}'''VR'''
{{!}}content determines the method to be used for building a grm from genotypes
*'''VR''': VanRaden Method 1 is used
*'''YA''': VanRaden Method 2(method Yang) is used
{{!}}-
{{!}}'''outfile'''
{{!}}'''outfile''': ''mygrm.bin''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file where the grm should be written to. will only take effect if the grm was build from genotypes. if the genotypes had a pedigree assigned a cross-reference file will be written out as well which contains the original pedigree ids of the genotyped individuals in the order of the rows/columns of the grm. the file name of the cross-reference file is that of the grm with the prefix '''cross_'''.
}}

=<'''vars'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
vars: g,p
...
</vars>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}compulsory
{{!}}hosts one to several elements each containing information about a specific variance.
}}

content:
*key strings
{{tablekeys2|
{{!}}'''vars'''
{{!}}'''vars''': ''g,p''
{{!}}compulsory
{{!}}csv word-list
{{!}}''variance names''
{{!}}none
{{!}}list content determines names of nominated-compulsory elements
}}
*nominated-compulsory elements
*compulsory element '''<res>'''
=='''Kronecker products'''==
Variance structures below are Kronecker products $$\Gamma \otimes \Sigma$$. If no '''type''' keystring is provided this is the default.
==='''<res>'''===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
<res>
<sigma>
..
</sigma>
</res>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''vars'''
{{!}}compulsory
{{!}}hosts information about the residual variance structure.
}}

content:
*compulsory element [[#<sigma>|'''<sigma>''']]
*optional element [[#<gamma>|'''<gamma>''']]

===''<variance name>''===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
..
</sigma>
<gamma>
..
</gamma>
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''vars'''
{{!}}nominated-compulsory
{{!}}hosts information about variance structure identified by ''variance name''.
}}

content:
*compulsory element [[#<sigma>|'''<sigma>''']]
*optional element [[#<gamma>|'''<gamma>''']]

*key strings
{{tablekeys2|
1={{!}}'''type'''
{{!}}'''type''': ''kronecker''
{{!}}optional
{{!}}word
{{!}}''kronecker,snpblup_1''
{{!}}kronecker
{{!}}determines whether the variance structure deviates from a Kronecker product.
}}

===='''<sigma>'''====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
..
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''variance name''
{{!}}compulsory
{{!}}hosts information about $$\Sigma$$ as part of [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]].
}}

content:

*key strings
{{tablekeys2|
1={{!}}'''file'''
{{!}}'''file''': ''mymatrix.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing the $$\Sigma$$ matrix. is mutually exclusive with '''<nowiki><matrix attributes="array"></nowiki>'''.
{{!}}-
{{!}}'''type'''
{{!}}'''type''': '''block'''
{{!}}optional
{{!}}word
{{!}}'''block'''
{{!}}none
{{!}}determines that $$\Sigma$$ is equal to [[Supported_features#Supported_variance_structures|$$\Theta$$]]
{{!}}-
{{!}}'''scale'''
{{!}}'''scale''': ''0.05''
{{!}}optional
{{!}}single numeric value
{{!}}real number>0.0
{{!}}none
{{!}}multiplies $$\Sigma$$ once by the provided value after reading.
{{!}}-
{{!}}'''priordf'''
{{!}}'''priordf''': ''10''
{{!}}optional
{{!}}single numeric value
{{!}}real number>=0.0
{{!}}0.0
{{!}}prior degree of freedom when doing Gibbs sampling
{{!}}-
{{!}}'''maskfile'''
{{!}}'''maskfile''': ''mymatrixmask.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the name of the file containing a T/F matrix of the same dimension as the respective $$\Sigma$$ matrix. Is mutually exclusive with '''<nowiki><maskmatrix attributes="array"></nowiki>'''.
}}

*optional element '''<matrix attributes="array">'''
=====<'''matrix attributes="array"'''>=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
<matrix attributes="array">
5.0,0.5
0.5,1.8
</matrix>
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''sigma'''
{{!}}optional
{{!}}hosts the content of a single $$\Sigma$$ matrix. Is mutually exclusive with key string '''file: '''.
}}
=====<'''maskmatrix attributes="array"'''>=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<sigma>
<maskmatrix attributes="array">
T,F
F,T
</matrix>
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''sigma'''
{{!}}optional
{{!}}hosts the content of a single indicator matrix of the same dimensions as the respective $$\Sigma$$ matrix. Is mutually exclusive with key string '''maskfile: '''.
}}

===='''<gamma>'''====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
..
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''variance name''
{{!}}optional
{{!}}hosts information about $$\Gamma$$ as part of [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]]. If absent $$\Gamma$$ defaults to $$I$$.
}}

content:

*mutually exclusive elements '''<A>, <H>, <G> and <E>'''

====='''<A>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<A>
pedigree: myped
</A>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma$$ being constructed as the numerator relationship matrix A using pedigree ''pedigree name''.
}}

content:
*key strings
{{tablekeys2|
{{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}optional
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree previously invoked to be used to construct A.
{{!}}-
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''gg'''
{{!}}optional
{{!}}csv word-list
{{!}}'''gg'''
{{!}}none
{{!}}
*gg: the pedigree contains genetic groups which will be fitted as random
}}

====='''<H>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<H>
type: tblup
pedigree: myped
genotype: mygn
aweight: 0.05
switch: adjustg2a
</H>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma$$ being constructed as combined single step relationship matrix H using pedigree ''pedigree name'' and genomic information. the genomic information can be supplied
*via a grm element for single step H-BLUP models
*via a genotype element for single step T-BLUP models
Note that for '''type:tblup''' it is not necessary to have an automatic-optional [[#<grms>|<grms>]] element in the parameter file. Doing so will cause the construction and RAM-storage of $$G$$ although it is not need for building H, thus maybe leading to substantial increase in processing time and RAM demand.
}}

content:
*key strings
{{tablekeys2|
1={{!}}'''pedigree'''
{{!}}'''pedigree''': ''myped''
{{!}}compulsory
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the name of a pedigree element to be used to construct H.
{{!}}-
{{!}}'''type'''
{{!}}'''type''': '''tblup'''
{{!}}optional
{{!}}word
{{!}}'''tblup<nowiki>|</nowiki>gblup'''
{{!}}'''gblup'''
{{!}}content determines the way the inverse of H is constructed.
{{!}}-
{{!}}'''grm'''
{{!}}'''grm''': ''mygrm''
{{!}}conditional-compulsory
{{!}}word
{{!}}''pedigree name''
{{!}}none
{{!}}content determines the grm element to be used to construct H. compulsory for '''type: hblup'''.
{{!}}-
{{!}}'''genotype'''
{{!}}'''genotype''': ''mygn''
{{!}}conditional-compulsory
{{!}}word
{{!}}''genotype name''
{{!}}none
{{!}}content determines the genotype element to be used to construct H. compulsory for '''type: tblup'''.
{{!}}-
{{!}}'''aweight'''
{{!}}'''aweight: 0.05'''
{{!}}optional
{{!}}single numeric value
{{!}}0.0<=aweight<=1.0
{{!}}0.0
{{!}}blending of $$G$$ with $$A_{gg}$$ by $$G_w=aweight\times A_{gg}+(1-aweight)\times G$$
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''adjustg2a'''
{{!}}optional
{{!}}csv word-list
{{!}}'''adjustg2a,gg,diag'''
{{!}}none
{{!}}
*adjustg2a: adjustment of $$G$$ towards $$A_{gg}$$ using method
*gg: the pedigree contains genetic groups which will be fitted as random
*diag: calculate H diagonal elements and write to file (only supported for gblup).
{{!}}-
{{!}}'''grmdadd'''
{{!}}'''grmdadd''': ''0.05''
{{!}}optional
{{!}}single numeric value
{{!}}real number >=0.0
{{!}}none
{{!}} value added to the diagonal of $$G$$ to ensure invertibility. The policy is
*if '''aweight'''>0.0, nothing will be added to the diagonals
*if '''aweight''' is not supplied or is zero:
** if '''grmdadd''' is not supplied 0.001 will be added to the diagonals
** otherwise '''grmdadd''' will be used
}}

====='''<G>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<G>
grm: mygrm
</G>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma$$ being constructed from a genomic relationsship matrix.
}}

content:
*key strings
{{tablekeys2|
1={{!}}'''grmdadd'''
{{!}}'''grmdadd''': ''0.05''
{{!}}optional
{{!}}single numeric value
{{!}}real number >=0.0
{{!}}none
{{!}} value added to the diagonal of $$G$$ to ensure invertibility.
}}

====='''<E>'''=====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
<gamma>
<E>
file: mygamma.csv
</E>
</gamma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''gamma'''
{{!}}compulsory
{{!}}hosts information about $$\Gamma^{-1}$$ being uploaded from a file.
}}

content:
*key strings
{{tablekeys2|
{{!}}'''file'''
{{!}}'''file''': ''mygamma.csv''
{{!}}compulsory
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}content determines the file which contains $$\Gamma^{-1}$$.
{{!}}-
{{!}}'''type'''
{{!}}'''type''': '''dense'''
{{!}}optional
{{!}}word
{{!}}'''dense<nowiki>|</nowiki>sparse_csr_ut'''
{{!}}'''sparse_csr_ut'''
{{!}}content determines the file storage of $$\Gamma^{-1}$$
*dense: full squared symmetric matrix
*sparse_csr_ut: squared symmetric sparse upper triangular matrix in [https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_row_(CSR,_CRS_or_Yale_format) csr] format
}}

=='''snpblup1'''==

===''<variance name>''===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
genotype: mygn
aweight: 0.05
switch: adjustg2a
<sigma>
..
</sigma>
<gamma>
..
</gamma>
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}'''vars'''
{{!}}nominated-compulsory
{{!}}hosts information about variance structure identified by ''variance name''.
}}

content:
*compulsory element '''<sigma>'''
*compulsory element [[#<marker_sb1>|'''<marker_sb1>''']]

*key strings
{{tablekeys2|
1={{!}}'''type'''
{{!}}'''type''': ''kronecker''
{{!}}optional
{{!}}word
{{!}}''kronecker,snpblup_1''
{{!}}kronecker
{{!}}determines whether the variance structure deviates from a Kronecker product.
{{!}}-
{{!}}'''genotype'''
{{!}}'''genotype''': ''mygn''
{{!}}conditional-compulsory
{{!}}word
{{!}}''genotype name''
{{!}}none
{{!}}content determines the genotype element to be used to construct H. compulsory for '''type: tblup'''.
{{!}}-
{{!}}'''aweight'''
{{!}}'''aweight: 0.05'''
{{!}}optional
{{!}}single numeric value
{{!}}0.0<=aweight<=1.0
{{!}}0.0
{{!}}blending of $$G$$ with $$A_{gg}$$ by $$G_w=aweight\times A_{gg}+(1-aweight)\times G$$
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''adjustg2a'''
{{!}}optional
{{!}}csv word-list
{{!}}'''adjustg2a,gg,diag'''
{{!}}none
{{!}}
*adjustg2a: adjustment of $$G$$ towards $$A_{gg}$$ using method
*gg: the pedigree contains genetic groups which will be fitted as random
*diag: calculate H diagonal elements and write to file (only supported for gblup).
}}

===='''<sigma>'''====

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
<sigma>
..
</sigma>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''variance name''
{{!}}compulsory
{{!}}hosts information about $$\Sigma$$ for the poly-genetic part of the variance structure.
}}

content:

see [[#<sigma>|'''<sigma''']]

===='''<marker_sb1>'''====
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
..
<marker_sb1>
..
</marker_sb1>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''marker''
{{!}}compulsory
{{!}}hosts information about the co-variance between and within markers following [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]].
}}

content:

*compulsory element '''<sigma>'''
*optional element '''<gamma>'''

====='''<sigma>'''=====

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<vars>
..
vars: myvar
<myvar>
type: snpblup1
..
<marker_sb1>
<sigma>
..
</sigma>
..
</marker_sb1>
..
</myvar>
..
</vars>
</root>
</syntaxhighlight>
{{!}}''marker''
{{!}}compulsory
{{!}}hosts information about $$\Sigma$$ as part of [[Supported_features#Supported_variance_structures|$$\Gamma \otimes \Sigma$$]] for the marker part of the variance structure. Note that $$\Sigma$$ will be scaled by (1-aweight).
}}

see [[#<sigma>|'''<sigma>''']]

=<'''jobs'''>=

{{tableele2|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: solve,yh
...
</jobs>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}optional
{{!}}hosts one to several elements each containing information about a specific job
{{!}}run default job(solve) in default parameterization(default pcgiod parameterization)
}}

content:
*key strings
{{tablekeys2|
{{!}}'''jobs'''
{{!}}'''jobs''': '''solve,yhat'''
{{!}}compulsory
{{!}}csv word-list
{{!}}'''solve,sample,pevsample,mcemreml,yhat'''
{{!}}none
{{!}}job sequence is determined by the list sequence. list content determines nominated-compulsory elements
}}

*nominated-compulsory elements
**'''<default>'''
**'''<solve>'''
**'''<sample>'''
**'''<pevsample>'''
**'''<pevsolve>'''
**'''<mcemreml>'''
**'''<airemlc>'''
**'''<yhat>'''

==<'''default'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
..
<default>
conv: -18.42
</default>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''default'''
}}

content: see [[#<pcgiod>|<pcgiod>]] for a list of all possible key strings

==<'''solve'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
..
<solve>
solver: mysolver
</solve>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''solve'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''solver'''
{{!}}'''solver''': ''mysolver''
{{!}}compulsory
{{!}}word
{{!}}''solver name''
{{!}}none
{{!}}''solver name'' must be the name of a previously defined solver
}}

==<'''sample'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: sample,..
<sample>
sampler: mysampler
</sample>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''sample'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''sampler'''
{{!}}'''sampler''': ''mysampler''
{{!}}compulsory
{{!}}word
{{!}}''sampler name''
{{!}}none
{{!}}''sampler name'' must be the name of a previously defined sampler
}}

==<'''pevsample'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: pevsample,..
<pevsample>
sampler: mysampler
</pevsample>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''pevsample'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''sampler'''
{{!}}'''sampler''': ''mysampler''
{{!}}compulsory
{{!}}word
{{!}}''sampler name''
{{!}}none
{{!}}''sampler name'' must be the name of a previously defined sampler of type pev
}}

==<'''pevsolve'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: pevsolve,..
<pevsolve>
solver: mysolver
</pevsolver>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''pevsolve'''
}}

content:

*key strings
{{tablekeys2|
1={{!}}'''solver'''
{{!}}'''solver''': ''mysolver''
{{!}}compulsory
{{!}}word
{{!}}''solver name''
{{!}}none
{{!}}''solver name'' must be the name of a previously defined solver
{{!}}-
{{!}}'''factor'''
{{!}}'''factor''': ''gen''
{{!}}compulsory
{{!}}word
{{!}}''factor name''
{{!}}none
{{!}}''factor name'' must be the name of a random factor
{{!}}-
{{!}}'''levels'''
{{!}}'''levels''': ''5,10,20''
{{!}}optional
{{!}}csv integer list
{{!}}''factor level ids''
{{!}}none
{{!}}original factor level ids(.e.g. pedigree ids etc). If not supplied the prediction error co-variance blocks of all factor levels associated to the nominated factor will be calculated. Mutually exclusive with '''levelfile'''.
{{!}}-
{{!}}'''levelfile'''
{{!}}'''levelfile''': ''myfile.csv''
{{!}}optional
{{!}}word
{{!}}''file name''
{{!}}none
{{!}}file containing original factor level ids(.e.g. pedigree ids etc). If not supplied the prediction error co-variance blocks of all factor levels associated to the nominated factor will be calculated. Mutually exclusive with '''levels'''.
{{!}}-
{{!}}'''nrhs'''
{{!}}'''nrhs''': ''50''
{{!}}optional
{{!}}integer
{{!}}''number of right-hand sides''
{{!}}1000
{{!}}number of right-hand-sides to be solved for simultaneously. Has only effect if the direct solver is used. The default may exceed the available RAM.
}}

==<'''airemlc'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: airemlc,..
<airemlc>
rounds: 50
..
</airemlc>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''airemlc'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''rounds'''
{{!}}'''rounds''': ''10''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}20
{{!}}provides the number of aireml-rounds to run
{{!}}-
{{!}}'''convtype'''
{{!}}'''convtype''': '''ng'''
{{!}}optional
{{!}}word
{{!}}'''cd<nowiki>|</nowiki>ng<nowiki>|</nowiki>ll<nowiki>|</nowiki>any<nowiki>|</nowiki>all'''
{{!}}'''cd'''
{{!}}provides the convergence criterion to use
* ll: log of relative change in log-likelihood
* ng: log of the norm of the gradient vector
* cd: log of the relative change of the parameter vector
* all: all of the above
* any: any of the above
{{!}}-
{{!}}'''convll'''
{{!}}'''convll''': ''-10.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''-6.907755''
{{!}}provides the convergence threshold for convergence criterion '''ll'''
{{!}}-
{{!}}'''convng'''
{{!}}'''convng''': ''-10.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''-16.1181''
{{!}}provides the convergence threshold for convergence criterion '''ng'''
{{!}}-
{{!}}'''convcd'''
{{!}}'''convcd''': ''-10.5''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}}''-16.1181''
{{!}}provides the convergence threshold for convergence criterion '''cd'''
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''residuals'''
{{!}}optional
{{!}}csv word-list
{{!}}any real number
{{!}}'''writeai,residuals'''
{{!}}
*'''writeai''': write ai matrix and gradient vector to files ai_ai.csv and ai_ja.csv.
*'''residuals''': after convergence write the residuals to file aic_residuals.csv
}}

==<'''mcemreml'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: mcemreml,..
<mcemreml>
emrounds: 500
sampler: mysampler
</mcemreml>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''mcemreml'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''emrounds'''
{{!}}'''emrounds''': ''500''
{{!}}compulsory
{{!}}numeric value
{{!}}positive integer
{{!}}none
{{!}}provides the number of mcemreml-rounds to run
{{!}}-
{{!}}'''sampler'''
{{!}}'''sampler''': ''mysampler''
{{!}}compulsory
{{!}}word
{{!}}''sampler name''
{{!}}none
{{!}}''sampler name'' must be the name of a previously defined sampler
}}

==<'''yhat'''>==
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<jobs>
jobs: yhat,..
<yhat>
</yhat>
..
</jobs>
..
</root>
</syntaxhighlight>
{{!}}'''jobs'''
{{!}}conditional-compulsory
{{!}}hosts information about job '''yhat'''
}}
Currently '''yhat''' has no key strings or nested elements defined.

=<'''samplers'''>=

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,b,..
...
</samplers>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}optional
{{!}}hosts one to several elements each containing information about a specific sampler
}}

content:
*key strings
{{tablekeys2|
{{!}}'''samplers'''
{{!}}'''samplers''': ''a''
{{!}}compulsory
{{!}}csv word-list
{{!}}''sampler names''
{{!}}none
{{!}}list content determines nominated-compulsory elements
}}
*conditional-compulsory elements

==<''sampler name''>==

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
..
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}'''samplers'''
{{!}}conditional-compulsory
{{!}}hosts one of several mutually exclusive elements defining the type of sampler ''sampler name''
}}

content:
*compulsory mutually exclusive elements
**'''<singlepass>'''
**'''<blocked>'''
**'''<pev>'''

===<'''singlepass'''>===

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
<singlepass>
samples: 10000
burnin: 1000
</singlepass>
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}''sampler name''
{{!}}compulsory
{{!}}defines parameters of a sampler of type '''singlepass'''
}}

*key strings
{{tablekeys2|
{{!}}'''samples'''
{{!}}'''samples''': ''100000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the total number of samples to draw
{{!}}-
{{!}}'''burnin'''
{{!}}'''burnin''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}0
{{!}}provides the number of samples to be discarded as burnin
}}

===<'''blocked'''>===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
<blocked>
samples: 10000
burnin: 1000
</blocked>
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}''sampler name''
{{!}}compulsory
{{!}}defines parameters of a sampler of type '''blocked'''
}}

*key strings
{{tablekeys2|
{{!}}'''samples'''
{{!}}'''samples''': ''100000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the total number of samples to draw
{{!}}-
{{!}}'''burnin'''
{{!}}'''burnin''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}0
{{!}}provides the number of samples to be discarded as burnin
}}

===<'''pev'''>===
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<samplers>
samplers: a,..
<a>
<pev>
samples: 10000
burnin: 1000
chains: 10
</pev>
</a>
</samplers>
</root>
</syntaxhighlight>
{{!}}''sampler name''
{{!}}compulsory
{{!}}defines parameters of a sampler of type '''pev'''
}}

*key strings
{{tablekeys2|
{{!}}'''samples'''
{{!}}'''samples''': ''100000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the total number of samples to draw
{{!}}-
{{!}}'''burnin'''
{{!}}'''burnin''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}0
{{!}}provides the number of samples to be discarded as burnin
{{!}}-
{{!}}'''chains'''
{{!}}'''chains''': ''10''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}1
{{!}}provides the number of parallel chains to run
{{!}}-
{{!}}'''switch'''
{{!}}'''switch''': '''trace'''
{{!}}optional
{{!}}word
{{!}}'''trace'''
{{!}}none
{{!}}changes sampler from sampling prediction error variances to sampling traces required for emreml
}}

=<'''solvers'''>=
{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,b,..
...
</solvers>
</root>
</syntaxhighlight>
{{!}}'''root'''
{{!}}optional
{{!}}hosts one to several elements each containing information about a specific solver
}}

content:
*key strings
{{tablekeys2|
{{!}}'''solvers'''
{{!}}'''solvers''': ''a''
{{!}}compulsory
{{!}}csv word-list
{{!}}''solver names''
{{!}}none
{{!}}list content determines nominated-compulsory elements
}}
*conditional-compulsory elements

==<''solver name''>==

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,..
<a>
..
</a>
</solvers>
</root>
</syntaxhighlight>
{{!}}'''solvers'''
{{!}}conditional-compulsory
{{!}}hosts one of several mutually exclusive elements defining the type of solver ''solver name''
}}

content:
*compulsory mutually exclusive elements with default element
**'''<pcgiod>''', default
**'''<direct>'''

===<'''pcgiod'''>===

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,..
<a>
<pcgiod>
rounds: 1000
conv: -20.0
</pcgiod>
</a>
</solvers>
</root>
</syntaxhighlight>
{{!}}''solver name''
{{!}}compulsory
{{!}}defines parameters of a solver of type '''pcgiod'''
}}

content:

*key strings
{{tablekeys2|
{{!}}'''rounds'''
{{!}}'''rounds''': ''1000''
{{!}}optional
{{!}}numeric value
{{!}}positive integer
{{!}}10000
{{!}}provides the maximum number of rounds to run
{{!}}-
{{!}}'''conv'''
{{!}}'''conv''': ''-15.0''
{{!}}optional
{{!}}numeric value
{{!}}any real number
{{!}} -18.42
{{!}}provides the convergence threshold
{{!}}-
{{!}}'''convtype'''
{{!}}'''convtype''': '''cd'''
{{!}}optional
{{!}}word
{{!}}'''cr<nowiki>|</nowiki>cd'''
{{!}} '''cr'''
{{!}}provides the convergence parameter type
}}

===<'''direct'''>===

{{tableele1|
{{!}}<syntaxhighlight lang="xml" line>
<root>
..
<solvers>
solvers: a,..
<a>
<direct>
</direct>
</a>
</solvers>
</root>
</syntaxhighlight>
{{!}}''solver name''
{{!}}compulsory
{{!}}defines parameters of a solver of type '''direct'''
}}

content: no content defined

Output files

2022-05-12T05:12:07Z

127.0.0.1: /* AI matrix and Gradient vector */

Output files

2022-05-12T01:29:21Z

127.0.0.1: /* Genetic group regression matrix */

Output files

2022-05-12T01:28:49Z

127.0.0.1: /* Genetic group regression matrix */

Output files

2022-05-12T01:25:04Z

127.0.0.1: /* Genetic group regression matrix */

Output files

2022-05-12T01:21:09Z

127.0.0.1: /* aic_conv.csv */

Output files

2022-05-12T01:20:42Z

127.0.0.1: /* aic_conv.csv */

Examples

2022-05-12T01:12:53Z

127.0.0.1: /* Providing GRMs */

The examples provided in this section are meant to provide a practical examples about the {{lmt}} facilities and the parameter file syntax. It is assumed that the reader is familiar with [[Parameterfile1|section]]

== Solving linear mixed model equations ==

=== Estimating a mean in a uni-variate model ===

Estimating a mean is equivalent to obtaining the generalized least square solution $$b=(X'R^{-1}X)^{-1}X'R^{-1}y$$ for model $$y=Xb+e$$, where $$y$$ is a vector of $$n$$ observations, $$X$$ is as single column matrix of $$1$$, $$b$$ is a fixed factor (mean), $$e$$ is the residual and $$y\sim N(Xb,R)$$ where $$R$$ is a $$n \times n$$ co-variance matrix.

From the above it follows that for task of solving for $$b$$ {{lmt}} needs following information:

the data
the residual variance $$R$$
the model
the solver

Assume we have a data file "data.csv" with content:
#y,mu
25.0,1
33.1,1
36.0,1
28.3,1
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records.
A valid {{lmt}} xml parameter file would look like:
<syntaxhighlight lang="xml" line highlight="5,27">
<root>
<models>
<eqn attributes="strings">
y=mu*b
</eqn>
</models>
<data>
datafile: data.csv
missingthreshold: -50.0
</data>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
</vars>
</root>
</syntaxhighlight>

Following the introduced [[Parameterfile1|parameterfile terminology]] tags {{cc|<data>}}, {{cc|<vars>}} and {{cc|<model>}} are automatic-compulsory. Since {{cc|solve}} is the default job and we are using the default solver in default parameterization no further information about the job or solver is required.

The most important aspect is the model definition in tag {{cc|<eqn>}}, nested inside tag {{cc|<model>}} $$y=mu*b$$. The variable names used here are either defined by the data file header, or by the user. That is, $$y$$ and $$mu$$ are defined in the data file header, whereas $$b$$ is a user-defined factor name. Translated this means that the content of the data column named $$y$$ should be regressed on the content of the data column named $$mu$$ with the regression coefficient named $$b$$.

Since there are no further specifications supplied about $$y$$, $$mu$$ and $$b$$, it is assumed that $$y$$ is a continuous variable, $$mu$$ is a classification variable, and $$b$$ is fixed factor.
The necessary variances are defined by the content of the automatic-compulsory tag {{cc|<vars>}}. {{lmt}} requires one compulsory variance, the residual variance, which must be specified via tag {{cc|<res>}}. Therefore tag {{cc|res}} is automatic-compulsory.

The default {{lmt}} variance structure is [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Gamma$$ and $$\Sigma$$ are specified inside tags {{cc|<gamma>}} and {{cc|<sigma>}}, respectively.
However, only tag {{cc|<sigma>}} is [[Parameterfile1#Parsing logic|automatic-compulsory]], whereas tag {{cc|<gamma>}} is [[Parameterfile1#Parsing logic|automatic-optional]]. A missing {{cc|<gamma>}} tag implies that [https://en.wikipedia.org/wiki/Identity_matrix $$\Gamma = I$$]. Note that for {{lmt}} $$\Sigma$$ is always a matrix, that is a scalar $$\sigma^2$$ is treated as a matrix $$1 \times 1$$ matrix.

For the above example, the variance specification inside {{cc|<res>}} implies that $$\Gamma\otimes \Sigma \equiv I\otimes \Sigma$$. Since $$\Sigma$$ is a $$1\times 1$$ matrix with $$\Sigma[1,1]=\sigma_e^2$$, $$R$$ reduces to $$I\sigma_e^2$$.

Note tag {{cc|<matrix>}} nested in tag {{cc|<sigma>}}. The content of tag {{cc|<matrix>}} does not comply with the formatting rules as pointed o ut [[Parameterfile1#Key strings|above]]. That is {{cc|5.0}} is not a valid key string. To let {{lmt}} know that the content of tag {{cc|<matrix>}} should not be evaluated as a key string, with a subsequent error message, [[Parameterfile1#Escaping tag content formatting rules|the tag must have attributes]]. In this example {{cc|1=matrix attributes="matrix"}} escapes the content of tag {{cc|<matrix>}} from the formatting rules.

Further, tag {{cc|<matrix>}} is automatic-optional. This might be confusing because, as pointed out above, $$\Sigma$$ forms an indispensable part of $$\Gamma\otimes \Sigma$$. However, tag {{cc|<matrix>}} belongs to a [[Parameterfile1#Group of mutually exclusive information sources|group of mutually exclusive information sources]] of which members are tag {{cc|<matrix>}} and key string {{cc|file: yourfilename}}. That is, $$\Sigma$$ maybe either embedded in the parameter file or supplied via an external file.

Note that the spelling of most tags used in the above parameter file is determined by {{lmt}} and must be abide by.

=== Estimating a fixed mean and a random genetic effect in a uni-variate model ===

Consider the linear model $$y=Xb+Zu+e$$ where all variables are those declared in [[#Estimating a mean]], $$u$$ is vector of length $$m$$ of random direct genetic effects and $$Z$$ is a design matrix of dimension $$n \times m$$ linking genetic effects to their respective observations. Note that $$u\sim N(0,A\sigma_a^2)$$ where $$A$$ is the pedigree-derived relationship matrix and forms the $$\Gamma$$ part in $$\Gamma\otimes\Sigma$$. A possible data file for such mode may look like:

#y,mu,id
25.0,1,5
33.1,1,6
36.0,1,7
28.3,1,8
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records. Further assume a pedigree in a file called "ped.csv" with content:
1,0,0
2,0,0
3,1,0
4,0,2
5,3,4
6,0,4
7,5,4
8,5,7

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y = mu*b + id*u(v(my_var(1)))
</eqn>
</model>
</root>
</syntaxhighlight>

Compared with the parameter file in example [[#Estimating a mean]] the one above contains only a few extra elements. One this the automatic-optional {{cc|<pedigrees>}} nested inside tag {{cc|<root>}}. This tag contains a keystring {{cc|pedigrees: myped}}, where the user-defined variable behind {{cc|pedigrees:}} is the name of a nominated-compulsory tag nested inside tag {cc|<pedigrees>}}. This concept allows to supply several pedigrees to lmt (e.g. a normal pedigree and a genetic group pedigree). In our example we have only one pedigree named my_ped, with tag {{cc|<my_ped>}} containing the information about this pedigree. Another additional element is the key string {{cc|vars: my_var}} nested in tag {{cc|<vars>}} where the variable of key string {{cc|vars: my_var}} provides the tag names of nominated-compulsory tags, in this example tag {{cc|<my_var>}}.

Tag {{cc|<myvar>}} consist of two structural components: the automatic-compulsory tag {{cc|<sigma>}} and the automatic-optional {{cc|<gamma>}}. Since the the variance of $$u=A\sigma_a^2$$, where $$A=\Gamma$$ and $$\sigma_a^2=\Sigma$$, a {{cc|<gamma>}} tag must be supplied to fully specify the variance. '''Note that if the {{cc|<gamma>}} tag is missing or miss-spelled {{lmt}} will assume that the variance of $$u=I\sigma_a^2$$'''. Tag {{cc|<gamma>}} contains a automatic-compulsory tag {{cc|<A>}} which specifies the $$\Gamma=A$$. Since $$A$$ is build from a pedigree, tag {{cc|<A>}} contains a compulsory key string {{cc|pedigree: my_ped}} which nominates pedigree in tag {{cc|<my_ped>}} to be used for building $$A$$.

Note the difference between the tags {{cc|<sigma>}} nested in tag {{cc|<res>}} and {{cc|<my_var>}}. The former specifies {{cc|<sigma>}} to be provided by tag {{cc|1=<matrix attributes="matrix">}}, whereas the latter specifies {{cc|<sigma>}} to be provided by a file.

The model section in the above parameter file need to communicate to to {{lmt}} that $$u$$ is a random factor with a variance $$A\sigma_a^2$$. This is done by extending the u.d. factor name {{cc|u}} in {{cc|1=y = mu*b + id*u(v(my_var(1)))}} by a specifier {{cc|(v(my_var(1)))}}. Note that without a specifier {{cc|u}} would be regarded as a fixed factor. The specifier {{cc|u(v)}} communicates that {{cc|u}} has a variance assigned. Further, {{cc|v}} has a specifier assigned via {{cc|v(my_var)}} which communicates that the name of the variance is {{cc|my_var}}. The variance in tag {{cc|<my_var>}} contains a {{cc|<gamma>}} and a {{cc|<sigma>}} component. The integer number inside bracket {{cc|my_var(1)}} communicates that $$\sigma_a^2$$ of {{cc|u}} is located in the first diagonal element of $$\Sigma$$.

In summary construct {{cc|u(v(my_var(1)))}} communicates that
*{{cc|u}} has a variance assigned
*the variance is named {{cc|my_var}}
*the variance is located in the first diagonal element of the $$\Sigma$$ matrix specified in tag {{cc|<sigma>}} nested in tag {{cc|<my_var>>}}

=== Estimating fixed means and a random genetic effects in a multi-variate model ===

Consider the linear model

$$
\left(
\begin{array}{c}
y_1 \\
y_2
\end{array}
\right)=
\left(
\begin{array}{cc}
X_1 & 0 \\
0 & X_2 \\
\end{array}
\right)
\left(
\begin{array}{c}
b_1 \\
b_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
Z & 0 \\
0 & Z
\end{array}
\right)
\left(
\begin{array}{c}
u_1 \\
u_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
I & 0 \\
0 & I
\end{array}
\right)
\left(
\begin{array}{c}
e_1 \\
e_2
\end{array}
\right)
$$

where all variables are those declared in [[#Estimating a mean and a random genetic effect in a uni-variate model|above]], and subscripts $$1$$ and $$2$$ index trait $$1$$ and $$2$$, respectively.

Note that $$[u_1,u_2]\sim N([0,0],A\otimes \Sigma_a)$$ where $$A$$ is the pedigree-derived relationship matrix and
$$
\Sigma_a=
\left(\begin{array}{cc}
\sigma_{a_1}^2 & \sigma_{a_1,a_2}\\
\sigma_{a_2,a_1} & \sigma_{a_2}^2
\end{array}\right)
$$
Further, $$[e_1,e_2]\sim N([0,0],I\otimes \Sigma_e)$$ with
$$
\Sigma_e=
\left(\begin{array}{cc}
\sigma_{e_1}^2 & \sigma_{e_1,e_2}\\
\sigma_{e_2,e_1} & \sigma_{e_2}^2
\end{array}\right)
$$.

A possible data file for such mode may look like:
#y1,y2,mu,id
25.0,0.8,1,5
33.1,0.5,1,6
36.0,1.5,1,7
28.3,3.6,1,8
and the pedigree files is that provided in example [[#Estimating a mean and a random genetic effect in a uni-variate model]].

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0,0.8
0.8,1.2
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y1 = mu*b1 + id*u1(v(my_var(1)))
y2 = mu*b2 + id*u2(v(my_var(2)))
</eqn>
</model>
</root>
</syntaxhighlight>

== Example code chunks ==

'''The following code chunks are only subset of a full parameter file. It is assumed that all other parts of the instruction file are functional and all necessary input data are available and the that the data file columns have the respective names.'''

=== Providing pedigrees ===

==== Providing a pedigree containing genetic groups ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
phantomparents: 2
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a pedigree containing metafounders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
metafile: mymeta.csv
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a probabilistic pedigree ====

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<pedigrees>
pedigrees: a
<a>
switch: probabilistic
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing several pedigrees ====

<syntaxhighlight lang="xml">
<root>
...
<pedigrees>
pedigrees: a,b
<a>
...
</a>

...

</pedigrees>
...
</root>
</syntaxhighlight>

=== Providing Genotypes ===

==== Providing external allele frequencies ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
pqfile: mypq.csv 
</a>
</genotypes>
...
</root>
</syntaxhighlight>

==== Providing several genotype files ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
...
</root>
</syntaxhighlight>

=== Providing GRMs ===

==== Constructing GRM from genotypes ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Overriding the default GRM construction method ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
method: YA 
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing a GRM from file ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<grms>
grms: x
<x>
file: mygrm.csv
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing several GRMs ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
...
</root>
</syntaxhighlight>

=== Single step models ===

==== ssGBLUP model with GRM build from genotypes====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGBLUP model with GRM supplied externally ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<grms>
grms: x
<x>
file: mygrm.bin
pedigree: a
cross: id.csv
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGTBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
file: pedigree.csv
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
file: mygeno.txt
pedigree: a
cross: ids.csv
...
</a>
</genotypes>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
type: tblup
genotype: a
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssSNPBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
switch: adjustg2a
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with meta-founders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
metafile: mymeta.csv 
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
pqfile: myp.csv 
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with a separate polygenic factor ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: a,g
<a>
<sigma>
file: cov_polygenic.csv 
</sigma>
<gamma>
<A>
pedigree: a
</A>
</gamma>
</a>
<g>
type: snpblup1
genotype: a
aweight: 0.001 
switch: adjustg2a
<sigma>
file: cov_genomic.csv 
</sigma>
<marker_sb1>
<sigma>
file: cov_genomic.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*ug1(v(g(1))+dam*mg1(v(g(2))+individual*ua1(v(a(1))+dam*ma1(v(a(2))
y2=mu*b2+individual*ug2(v(g(3))+dam*mg2(v(g(4))+individual*ua2(v(a(3))+dam*ma2(v(a(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssGBLUP with two genomic factors ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a,b
<a>
...
pedigree: a
</a>

...
pedigree: a

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
<vars>
...
vars: g1,g2
<g1>
...
<gamma>
<H>
...
grm: x
</H>
</gamma>
</g1>
<g2>
...
<gamma>
<H>
...
grm: y
</H>
</gamma>
</g2>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u11(v(g1(1))+id*u21(v(g2(1))
y2=mu*b2+id*u12(v(g1(2))+id*u22(v(g2(2))
</eqn>
</models>
</root>
</syntaxhighlight>

=== Regression on continuous co-variables ===

==== Linear regression ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co))*age1
y2=mu*b2+age(t(co))*age2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== User-defined polynomial expansion ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
x^1
log(sqrt(x))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Using hard-coded Legendre polynomials ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2,3))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
l0
l1
l2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested co-variables ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
weaningweight=mu*b1+age(t(co(p(1,2);n(sex))))*age
intramuscularfatcontent=mu*b2+weight(t(co(p(1,2);n(sex))))*weight
</eqn>
<eqn attributes="strings">
x^1
x^2
</eqn>
</models>
...
</root>
</syntaxhighlight>

=== Random-regression models ===
==== Nested continuous random co-variables ====

{{cc|days}} is a co-variable which is nested within {{cc|individual}} or {{cc|dam}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(n(individual))))*u1(v(g(1))+days(t(co(n(dam))))*m1(v(g(2))
y2=mu*b2+days(t(co(n(individual))))*u2(v(g(3))+days(t(co(n(dam))))*m2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous random co-variables with polynomial expansion ====

Similar to [[#Nested continuous co-variables|Nested continuous co-variables]] but {{cc|days}} is expanded

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(p(1,2,3);n(dam))))*m1(v(g(4,5,6))
y2=mu*b2+days(t(co(p(1,2,3);n(individual))))*u2(v(g(7,8,9))+days(t(co(p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous co-variables with polynomial expansion and an integer co-variable ====

Similar to [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]], but an additional information {{cc|t(i)}} is provided telling {{lmt}} that {{cc|days}} is actually an integer. While the results do not differ from [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]] {{lmt}} can exploit this information for memory efficiency.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(t(i);p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(t(i);p(1,2,3);n(dam))))*m1(v(g(7,8,9))
y2=mu*b2+days(t(co(t(i);p(1,2,3);n(individual))))*u2(v(g(4,5,6))+days(t(co(t(i);p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials of order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
</root>
</syntaxhighlight>

=== Defining equivalent models with genetic groups ===

Note that in the parameterization provided below [[#Defining a model with absorbed genetic groups|absorbed genetic groups]] and [[#Defining a model with genetic groups as extra factor|genetic groups as extra factor]] must yield the same results. However, only when using {{cc|absorbed genetic groups}} the factor level solutions are the actual breeding values. When modelling genetic groups as an extra factor genetic factor solutions and genetic group factor solutions must be added by the user.

==== Defining a model with absorbed genetic groups ====

Note that the only information necessary is the number of phantom parents '''at the top of the pedigree'''({{cc|phantomparents: 10}}) and the information to the variance that the it should be constructed allowing for genetic groups({{cc|switch gg}}).

<syntaxhighlight lang="xml" line highlight="6,19">
<root>
<pedigrees>
pedigrees: a
<a>
file: myped.csv
phantomparents: 10
</a>
<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: a
switch: gg
</A>
</gamma>
</g>
</vars>
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Defining a model with genetic groups as extra random factor ====

Genetic groups are defined as an extra factor, which requires an extra variance({{cc|gg}}) and two pedigrees, the genetic group pedigree({{cc|a}}) and the normal pedigree({{cc|b}}). For a model equivalent to [[#Defining a model with absorbed genetic groups|absorption]] pedigree {{cc|b}} must be a subset of pedigree {{cc|a}}. Further, if breeding values are required {{lmt}} can provide the genetic group regression matrix {{cc|qfile: Q.coocsv}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g,gg
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
<gg>
<sigma>
file: myG.csv <! must contain a 4x4 matrix. should be the same as for "g">
</sigma>
</gg>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1(v(gg(1))+dam(t(gg(a)))*damgg1(v(gg(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2(v(gg(2))+dam(t(gg(a)))*damgg2(v(gg(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== Defining a model with fixed genetic groups ====

Fixed genetic groups are only supported if modeled as an extra factor. Therefore, the model is similar to [[#Defining a model with genetic groups as extra random factor|above]], but the extra variance is omitted. Note that when modeling genetic groups as fixed it is the users responsibility to omit one group from the respective pedigree to ensure that $$X$$ is of full column rank. [[#Linear models in lmt:Column rank of $$X$$|bla]]

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1+dam(t(gg(a)))*damgg1
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2+dam(t(gg(a)))*damgg2
</eqn>
</models>
</root>
</syntaxhighlight>

=== Override the default job parameters ===

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<jobs>
jobs: default
<default>
conv: -9.21 <! log(10e-5)>
</default>
</jobs>
...
</root>
</syntaxhighlight>

=== Use job "solve" instead of "default" ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>
</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Use a direct solver in stead of the default solver ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>
<direct>
</direct>
</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using Gibbs sampling ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: sample
<sample>
sampler: x
</sample>
</jobs>
<samplers>
samplers: x
<x>
<blocked>
samples: 100000
</blocked>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using AI-REML-C ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: airemlc
<airemlc>
</airemlc>
</jobs>
...
</root>
</syntaxhighlight>

Examples

2022-05-12T01:11:38Z

127.0.0.1: /* Providing external allele frequencies */

The examples provided in this section are meant to provide a practical examples about the {{lmt}} facilities and the parameter file syntax. It is assumed that the reader is familiar with [[Parameterfile1|section]]

== Solving linear mixed model equations ==

=== Estimating a mean in a uni-variate model ===

Estimating a mean is equivalent to obtaining the generalized least square solution $$b=(X'R^{-1}X)^{-1}X'R^{-1}y$$ for model $$y=Xb+e$$, where $$y$$ is a vector of $$n$$ observations, $$X$$ is as single column matrix of $$1$$, $$b$$ is a fixed factor (mean), $$e$$ is the residual and $$y\sim N(Xb,R)$$ where $$R$$ is a $$n \times n$$ co-variance matrix.

From the above it follows that for task of solving for $$b$$ {{lmt}} needs following information:

the data
the residual variance $$R$$
the model
the solver

Assume we have a data file "data.csv" with content:
#y,mu
25.0,1
33.1,1
36.0,1
28.3,1
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records.
A valid {{lmt}} xml parameter file would look like:
<syntaxhighlight lang="xml" line highlight="5,27">
<root>
<models>
<eqn attributes="strings">
y=mu*b
</eqn>
</models>
<data>
datafile: data.csv
missingthreshold: -50.0
</data>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
</vars>
</root>
</syntaxhighlight>

Following the introduced [[Parameterfile1|parameterfile terminology]] tags {{cc|<data>}}, {{cc|<vars>}} and {{cc|<model>}} are automatic-compulsory. Since {{cc|solve}} is the default job and we are using the default solver in default parameterization no further information about the job or solver is required.

The most important aspect is the model definition in tag {{cc|<eqn>}}, nested inside tag {{cc|<model>}} $$y=mu*b$$. The variable names used here are either defined by the data file header, or by the user. That is, $$y$$ and $$mu$$ are defined in the data file header, whereas $$b$$ is a user-defined factor name. Translated this means that the content of the data column named $$y$$ should be regressed on the content of the data column named $$mu$$ with the regression coefficient named $$b$$.

Since there are no further specifications supplied about $$y$$, $$mu$$ and $$b$$, it is assumed that $$y$$ is a continuous variable, $$mu$$ is a classification variable, and $$b$$ is fixed factor.
The necessary variances are defined by the content of the automatic-compulsory tag {{cc|<vars>}}. {{lmt}} requires one compulsory variance, the residual variance, which must be specified via tag {{cc|<res>}}. Therefore tag {{cc|res}} is automatic-compulsory.

The default {{lmt}} variance structure is [https://en.wikipedia.org/wiki/Kronecker_product $$\Gamma\otimes\Sigma$$], where $$\Gamma$$ and $$\Sigma$$ are specified inside tags {{cc|<gamma>}} and {{cc|<sigma>}}, respectively.
However, only tag {{cc|<sigma>}} is [[Parameterfile1#Parsing logic|automatic-compulsory]], whereas tag {{cc|<gamma>}} is [[Parameterfile1#Parsing logic|automatic-optional]]. A missing {{cc|<gamma>}} tag implies that [https://en.wikipedia.org/wiki/Identity_matrix $$\Gamma = I$$]. Note that for {{lmt}} $$\Sigma$$ is always a matrix, that is a scalar $$\sigma^2$$ is treated as a matrix $$1 \times 1$$ matrix.

For the above example, the variance specification inside {{cc|<res>}} implies that $$\Gamma\otimes \Sigma \equiv I\otimes \Sigma$$. Since $$\Sigma$$ is a $$1\times 1$$ matrix with $$\Sigma[1,1]=\sigma_e^2$$, $$R$$ reduces to $$I\sigma_e^2$$.

Note tag {{cc|<matrix>}} nested in tag {{cc|<sigma>}}. The content of tag {{cc|<matrix>}} does not comply with the formatting rules as pointed o ut [[Parameterfile1#Key strings|above]]. That is {{cc|5.0}} is not a valid key string. To let {{lmt}} know that the content of tag {{cc|<matrix>}} should not be evaluated as a key string, with a subsequent error message, [[Parameterfile1#Escaping tag content formatting rules|the tag must have attributes]]. In this example {{cc|1=matrix attributes="matrix"}} escapes the content of tag {{cc|<matrix>}} from the formatting rules.

Further, tag {{cc|<matrix>}} is automatic-optional. This might be confusing because, as pointed out above, $$\Sigma$$ forms an indispensable part of $$\Gamma\otimes \Sigma$$. However, tag {{cc|<matrix>}} belongs to a [[Parameterfile1#Group of mutually exclusive information sources|group of mutually exclusive information sources]] of which members are tag {{cc|<matrix>}} and key string {{cc|file: yourfilename}}. That is, $$\Sigma$$ maybe either embedded in the parameter file or supplied via an external file.

Note that the spelling of most tags used in the above parameter file is determined by {{lmt}} and must be abide by.

=== Estimating a fixed mean and a random genetic effect in a uni-variate model ===

Consider the linear model $$y=Xb+Zu+e$$ where all variables are those declared in [[#Estimating a mean]], $$u$$ is vector of length $$m$$ of random direct genetic effects and $$Z$$ is a design matrix of dimension $$n \times m$$ linking genetic effects to their respective observations. Note that $$u\sim N(0,A\sigma_a^2)$$ where $$A$$ is the pedigree-derived relationship matrix and forms the $$\Gamma$$ part in $$\Gamma\otimes\Sigma$$. A possible data file for such mode may look like:

#y,mu,id
25.0,1,5
33.1,1,6
36.0,1,7
28.3,1,8
where the columns are comma-separated, the first row is commented out with “#” but contains the header, and all other rows contain data records. Further assume a pedigree in a file called "ped.csv" with content:
1,0,0
2,0,0
3,1,0
4,0,2
5,3,4
6,0,4
7,5,4
8,5,7

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y = mu*b + id*u(v(my_var(1)))
</eqn>
</model>
</root>
</syntaxhighlight>

Compared with the parameter file in example [[#Estimating a mean]] the one above contains only a few extra elements. One this the automatic-optional {{cc|<pedigrees>}} nested inside tag {{cc|<root>}}. This tag contains a keystring {{cc|pedigrees: myped}}, where the user-defined variable behind {{cc|pedigrees:}} is the name of a nominated-compulsory tag nested inside tag {cc|<pedigrees>}}. This concept allows to supply several pedigrees to lmt (e.g. a normal pedigree and a genetic group pedigree). In our example we have only one pedigree named my_ped, with tag {{cc|<my_ped>}} containing the information about this pedigree. Another additional element is the key string {{cc|vars: my_var}} nested in tag {{cc|<vars>}} where the variable of key string {{cc|vars: my_var}} provides the tag names of nominated-compulsory tags, in this example tag {{cc|<my_var>}}.

Tag {{cc|<myvar>}} consist of two structural components: the automatic-compulsory tag {{cc|<sigma>}} and the automatic-optional {{cc|<gamma>}}. Since the the variance of $$u=A\sigma_a^2$$, where $$A=\Gamma$$ and $$\sigma_a^2=\Sigma$$, a {{cc|<gamma>}} tag must be supplied to fully specify the variance. '''Note that if the {{cc|<gamma>}} tag is missing or miss-spelled {{lmt}} will assume that the variance of $$u=I\sigma_a^2$$'''. Tag {{cc|<gamma>}} contains a automatic-compulsory tag {{cc|<A>}} which specifies the $$\Gamma=A$$. Since $$A$$ is build from a pedigree, tag {{cc|<A>}} contains a compulsory key string {{cc|pedigree: my_ped}} which nominates pedigree in tag {{cc|<my_ped>}} to be used for building $$A$$.

Note the difference between the tags {{cc|<sigma>}} nested in tag {{cc|<res>}} and {{cc|<my_var>}}. The former specifies {{cc|<sigma>}} to be provided by tag {{cc|1=<matrix attributes="matrix">}}, whereas the latter specifies {{cc|<sigma>}} to be provided by a file.

The model section in the above parameter file need to communicate to to {{lmt}} that $$u$$ is a random factor with a variance $$A\sigma_a^2$$. This is done by extending the u.d. factor name {{cc|u}} in {{cc|1=y = mu*b + id*u(v(my_var(1)))}} by a specifier {{cc|(v(my_var(1)))}}. Note that without a specifier {{cc|u}} would be regarded as a fixed factor. The specifier {{cc|u(v)}} communicates that {{cc|u}} has a variance assigned. Further, {{cc|v}} has a specifier assigned via {{cc|v(my_var)}} which communicates that the name of the variance is {{cc|my_var}}. The variance in tag {{cc|<my_var>}} contains a {{cc|<gamma>}} and a {{cc|<sigma>}} component. The integer number inside bracket {{cc|my_var(1)}} communicates that $$\sigma_a^2$$ of {{cc|u}} is located in the first diagonal element of $$\Sigma$$.

In summary construct {{cc|u(v(my_var(1)))}} communicates that
*{{cc|u}} has a variance assigned
*the variance is named {{cc|my_var}}
*the variance is located in the first diagonal element of the $$\Sigma$$ matrix specified in tag {{cc|<sigma>}} nested in tag {{cc|<my_var>>}}

=== Estimating fixed means and a random genetic effects in a multi-variate model ===

Consider the linear model

$$
\left(
\begin{array}{c}
y_1 \\
y_2
\end{array}
\right)=
\left(
\begin{array}{cc}
X_1 & 0 \\
0 & X_2 \\
\end{array}
\right)
\left(
\begin{array}{c}
b_1 \\
b_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
Z & 0 \\
0 & Z
\end{array}
\right)
\left(
\begin{array}{c}
u_1 \\
u_2
\end{array}
\right)
+
\left(
\begin{array}{cc}
I & 0 \\
0 & I
\end{array}
\right)
\left(
\begin{array}{c}
e_1 \\
e_2
\end{array}
\right)
$$

where all variables are those declared in [[#Estimating a mean and a random genetic effect in a uni-variate model|above]], and subscripts $$1$$ and $$2$$ index trait $$1$$ and $$2$$, respectively.

Note that $$[u_1,u_2]\sim N([0,0],A\otimes \Sigma_a)$$ where $$A$$ is the pedigree-derived relationship matrix and
$$
\Sigma_a=
\left(\begin{array}{cc}
\sigma_{a_1}^2 & \sigma_{a_1,a_2}\\
\sigma_{a_2,a_1} & \sigma_{a_2}^2
\end{array}\right)
$$
Further, $$[e_1,e_2]\sim N([0,0],I\otimes \Sigma_e)$$ with
$$
\Sigma_e=
\left(\begin{array}{cc}
\sigma_{e_1}^2 & \sigma_{e_1,e_2}\\
\sigma_{e_2,e_1} & \sigma_{e_2}^2
\end{array}\right)
$$.

A possible data file for such mode may look like:
#y1,y2,mu,id
25.0,0.8,1,5
33.1,0.5,1,6
36.0,1.5,1,7
28.3,3.6,1,8
and the pedigree files is that provided in example [[#Estimating a mean and a random genetic effect in a uni-variate model]].

and a valid {{lmt}} parameter file:

<syntaxhighlight lang="xml" line highlight="6">
<root>
<data>
file: data.csv
</data>
<pedigrees>
pedigrees: my_ped
<my_ped>
file: ped.csv
</my_ped>
</pedigrees>
<vars>
<res>
<sigma>
<matrix attributes="matrix">
5.0,0.8
0.8,1.2
</matrix>
</sigma>
</res>
vars: my_var
<my_var>
<sigma>
file: sigma.csv
</sigma>
<gamma>
<A>
pedigree: my_ped
</A>
</gamma>
</my_var>
</vars>
<model>
<eqn attributes="strings">
y1 = mu*b1 + id*u1(v(my_var(1)))
y2 = mu*b2 + id*u2(v(my_var(2)))
</eqn>
</model>
</root>
</syntaxhighlight>

== Example code chunks ==

'''The following code chunks are only subset of a full parameter file. It is assumed that all other parts of the instruction file are functional and all necessary input data are available and the that the data file columns have the respective names.'''

=== Providing pedigrees ===

==== Providing a pedigree containing genetic groups ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
phantomparents: 2
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a pedigree containing metafounders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<pedigrees>
pedigrees: a
<a>
metafile: mymeta.csv
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing a probabilistic pedigree ====

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<pedigrees>
pedigrees: a
<a>
switch: probabilistic
...
</a>
</pedigrees>
...
</root>
</syntaxhighlight>

==== Providing several pedigrees ====

<syntaxhighlight lang="xml">
<root>
...
<pedigrees>
pedigrees: a,b
<a>
...
</a>

...

</pedigrees>
...
</root>
</syntaxhighlight>

=== Providing Genotypes ===

==== Providing external allele frequencies ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
pqfile: mypq.csv 
</a>
</genotypes>
...
</root>
</syntaxhighlight>

==== Providing several genotype files ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
...
</root>
</syntaxhighlight>

=== Providing GRMs ===

==== Constructing GRM from genotypes ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Overriding the default GRM construction method ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a
<a>
...
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
method: YA 
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing a GRM from file ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<grms>
grms: x
<x>
file: mygrm.csv
...
</x>
</grms>
...
</root>
</syntaxhighlight>

==== Constructing several GRMs ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<genotypes>
genotypes: a,b
<a>
...
</a>

...

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
...
</root>
</syntaxhighlight>

=== Single step models ===

==== ssGBLUP model with GRM build from genotypes====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
</genotypes>
<grms>
grms: x
<x>
genotype: a
...
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGBLUP model with GRM supplied externally ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<grms>
grms: x
<x>
file: mygrm.bin
pedigree: a
cross: id.csv
</x>
</grms>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
grm: x
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssGTBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
file: pedigree.csv
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
file: mygeno.txt
pedigree: a
cross: ids.csv
...
</a>
</genotypes>
<vars>
...
vars: g
<g>
...
<gamma>
<H>
...
type: tblup
genotype: a
pedigree: a
aweight: 0.05
</H>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u1(v(g(1))
y2=mu*b2+id*u1(v(g(2))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== ssSNPBLUP model ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
switch: adjustg2a
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with meta-founders ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
metafile: mymeta.csv 
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
pqfile: myp.csv 
</a>
<vars>
...
vars: g
<g>
type: snpblup1
genotype: a
aweight: 0.05
<sigma>
file: covG.csv
</sigma>
<marker_sb1>
<sigma>
file: covG.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*u1(v(g(1))+dam*m1(v(g(2))
y2=mu*b2+individual*u2(v(g(3))+dam*m2(v(g(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssSNPBLUP model with a separate polygenic factor ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a
<a>
...
pedigree: a
</a>
<vars>
...
vars: a,g
<a>
<sigma>
file: cov_polygenic.csv 
</sigma>
<gamma>
<A>
pedigree: a
</A>
</gamma>
</a>
<g>
type: snpblup1
genotype: a
aweight: 0.001 
switch: adjustg2a
<sigma>
file: cov_genomic.csv 
</sigma>
<marker_sb1>
<sigma>
file: cov_genomic.csv
</sigma>
</marker_sb1>
</g>
</vars>
...
<models>
<eqn>
y1=mu*b1+individual*ug1(v(g(1))+dam*mg1(v(g(2))+individual*ua1(v(a(1))+dam*ma1(v(a(2))
y2=mu*b2+individual*ug2(v(g(3))+dam*mg2(v(g(4))+individual*ua2(v(a(3))+dam*ma2(v(a(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== ssGBLUP with two genomic factors ====

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a
<a>
...
</a>
<pedigrees>
<genotypes>
genotypes: a,b
<a>
...
pedigree: a
</a>

...
pedigree: a

</genotypes>
<grms>
grms: x,y
<x>
genotype: a
...
</x>
<y>
genotype: b
...
</y>
</grms>
<vars>
...
vars: g1,g2
<g1>
...
<gamma>
<H>
...
grm: x
</H>
</gamma>
</g1>
<g2>
...
<gamma>
<H>
...
grm: y
</H>
</gamma>
</g2>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*u11(v(g1(1))+id*u21(v(g2(1))
y2=mu*b2+id*u12(v(g1(2))+id*u22(v(g2(2))
</eqn>
</models>
</root>
</syntaxhighlight>

=== Regression on continuous co-variables ===

==== Linear regression ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co))*age1
y2=mu*b2+age(t(co))*age2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== User-defined polynomial expansion ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
x^1
log(sqrt(x))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Using hard-coded Legendre polynomials ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+age(t(co(p(1,2,3))))*age1
y2=mu*b2+age(t(co(p(1,2))))*age2
</eqn>
<eqn attributes="strings">
l0
l1
l2
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested co-variables ====

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
weaningweight=mu*b1+age(t(co(p(1,2);n(sex))))*age
intramuscularfatcontent=mu*b2+weight(t(co(p(1,2);n(sex))))*weight
</eqn>
<eqn attributes="strings">
x^1
x^2
</eqn>
</models>
...
</root>
</syntaxhighlight>

=== Random-regression models ===
==== Nested continuous random co-variables ====

{{cc|days}} is a co-variable which is nested within {{cc|individual}} or {{cc|dam}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(n(individual))))*u1(v(g(1))+days(t(co(n(dam))))*m1(v(g(2))
y2=mu*b2+days(t(co(n(individual))))*u2(v(g(3))+days(t(co(n(dam))))*m2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous random co-variables with polynomial expansion ====

Similar to [[#Nested continuous co-variables|Nested continuous co-variables]] but {{cc|days}} is expanded

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(p(1,2,3);n(dam))))*m1(v(g(4,5,6))
y2=mu*b2+days(t(co(p(1,2,3);n(individual))))*u2(v(g(7,8,9))+days(t(co(p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
...
</root>
</syntaxhighlight>

==== Nested continuous co-variables with polynomial expansion and an integer co-variable ====

Similar to [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]], but an additional information {{cc|t(i)}} is provided telling {{lmt}} that {{cc|days}} is actually an integer. While the results do not differ from [[#Nested continuous co-variables with polynomial expansion|Nested continuous co-variables with polynomial expansion]] {{lmt}} can exploit this information for memory efficiency.

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<models>
<eqn attributes="strings">
y1=mu*b1+days(t(co(t(i);p(1,2,3);n(individual))))*u1(v(g(1,2,3))+days(t(co(t(i);p(1,2,3);n(dam))))*m1(v(g(7,8,9))
y2=mu*b2+days(t(co(t(i);p(1,2,3);n(individual))))*u2(v(g(4,5,6))+days(t(co(t(i);p(1,2,3);n(dam))))*m2(v(g(10,11,12))
</eqn>
<poly attributes="strings">
<! Legendre polynomials of order 0, 1 and 2>
l0
l1
l2
</poly>
</models>
</root>
</syntaxhighlight>

=== Defining equivalent models with genetic groups ===

Note that in the parameterization provided below [[#Defining a model with absorbed genetic groups|absorbed genetic groups]] and [[#Defining a model with genetic groups as extra factor|genetic groups as extra factor]] must yield the same results. However, only when using {{cc|absorbed genetic groups}} the factor level solutions are the actual breeding values. When modelling genetic groups as an extra factor genetic factor solutions and genetic group factor solutions must be added by the user.

==== Defining a model with absorbed genetic groups ====

Note that the only information necessary is the number of phantom parents '''at the top of the pedigree'''({{cc|phantomparents: 10}}) and the information to the variance that the it should be constructed allowing for genetic groups({{cc|switch gg}}).

<syntaxhighlight lang="xml" line highlight="6,19">
<root>
<pedigrees>
pedigrees: a
<a>
file: myped.csv
phantomparents: 10
</a>
<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: a
switch: gg
</A>
</gamma>
</g>
</vars>
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))
</eqn>
</models>
...
</root>
</syntaxhighlight>

==== Defining a model with genetic groups as extra random factor ====

Genetic groups are defined as an extra factor, which requires an extra variance({{cc|gg}}) and two pedigrees, the genetic group pedigree({{cc|a}}) and the normal pedigree({{cc|b}}). For a model equivalent to [[#Defining a model with absorbed genetic groups|absorption]] pedigree {{cc|b}} must be a subset of pedigree {{cc|a}}. Further, if breeding values are required {{lmt}} can provide the genetic group regression matrix {{cc|qfile: Q.coocsv}}.

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g,gg
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
<gg>
<sigma>
file: myG.csv <! must contain a 4x4 matrix. should be the same as for "g">
</sigma>
</gg>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1(v(gg(1))+dam(t(gg(a)))*damgg1(v(gg(3))
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2(v(gg(2))+dam(t(gg(a)))*damgg2(v(gg(4))
</eqn>
</models>
</root>
</syntaxhighlight>

==== Defining a model with fixed genetic groups ====

Fixed genetic groups are only supported if modeled as an extra factor. Therefore, the model is similar to [[#Defining a model with genetic groups as extra random factor|above]], but the extra variance is omitted. Note that when modeling genetic groups as fixed it is the users responsibility to omit one group from the respective pedigree to ensure that $$X$$ is of full column rank. [[#Linear models in lmt:Column rank of $$X$$|bla]]

<syntaxhighlight lang="xml" line highlight="">
<root>
<pedigrees>
pedigrees: a,b
<a>
file: ggped.csv
phantomparents: 10
qfile: Q.coocsv
</a>

file: ped.csv

<pedigrees>
<vars>
...
vars: g
<g>
<sigma>
file: myG.csv <! must contain a 4x4 matrix>
</sigma>
<gamma>
<A>
pedigree: b
</A>
</gamma>
</g>
</vars>
...
<models>
<eqn attributes="strings">
y1=mu*b1+id*id1(v(g(1))+dam*dam1(v(g(3))+id(t(gg(a)))*idgg1+dam(t(gg(a)))*damgg1
y2=mu*b2+id*id2(v(g(2))+dam*dam2(v(g(4))+id(t(gg(a)))*idgg2+dam(t(gg(a)))*damgg2
</eqn>
</models>
</root>
</syntaxhighlight>

=== Override the default job parameters ===

<syntaxhighlight lang="xml" line highlight="6">
<root>
...
<jobs>
jobs: default
<default>
conv: -9.21 <! log(10e-5)>
</default>
</jobs>
...
</root>
</syntaxhighlight>

=== Use job "solve" instead of "default" ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>
</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Use a direct solver in stead of the default solver ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: solve
<solve>
solver: x
</solve>
</jobs>
<solvers>
solvers: x
<x>
<direct>
</direct>
</x>
</solvers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using Gibbs sampling ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: sample
<sample>
sampler: x
</sample>
</jobs>
<samplers>
samplers: x
<x>
<blocked>
samples: 100000
</blocked>
</x>
</samplers>
...
</root>
</syntaxhighlight>

=== Estimating variance components using AI-REML-C ===

<syntaxhighlight lang="xml" line highlight="">
<root>
...
<jobs>
jobs: airemlc
<airemlc>
</airemlc>
</jobs>
...
</root>
</syntaxhighlight>