Differences

This shows you the differences between two versions of the page.

--- readme.aireml [2012/05/30 13:28] – shogo
+++ readme.aireml [2014/09/05 16:16] – shogo
@@ Line 1: / Line 1: @@
 ====== AIREMLF90 ======
-\\
-A modification of REMLF90 for estimating variances with the Average-Information algorithm. Initially written by Shogo Tsuruta in 03/99-07/99.
 ===== Summary =====
-AIREMLF90 uses a second derivative REML algrithm with extra heuristics, as is described in Jensen et al. (1996-7). For most problems, it converges in far fewer rounds than EM REML as implemented in REMLF90. While typically REMLF90 takes 50-300 rounds to converge, AIREMLF90 converges in 5-15 rounds and to a higher accuracy. For selected problems, AI-REML fails to converge when the covariance matrix is close to non-positive definite. Adjust sensitivity of the program by setting the appropriate tolerance or setting good starting values.
+A modification of REMLF90 for estimating variances with the Average-Information algorithm. Initially written by Shogo Tsuruta in 03/99-07/99.
+\\
+AIREMLF90 uses a second derivative REML algrithm with extra heuristics, as is described in Jensen et al. (1996-7). For most models, it converges in far fewer rounds than EM-REML as implemented in REMLF90. While typically REMLF90 takes 50-300 rounds to converge, AIREMLF90 converges in 5-15 rounds and to a higher accuracy. For selected models, AI-REML may fail to converge when the covariance matrix is close to non-positive definite. Adjust sensitivity of the program by setting the appropriate tolerance or setting good starting values. The final results will be saved in "AIREMLF90.log".
+\\
+See PREGSF90 with genotypes (SNP) for options.
 ===== Options =====
@@ Line 14: / Line 16: @@
 OPTION maxrounds 1000
 </file>
-Maximum rounds (default 5000). When the number < 2, the program calculates BLUP without iterating REML.
+Maximum rounds (default 5000). When the number = 0, the program calculates BLUP without iterating REML and some statistics (-2logL, AIC, SE for (co)variances, ...).
 <file>
 OPTION EM-REML 10
 </file>
 Run EM-REML (REMLF90) for first 10 rounds to get initial variances within the parameter space (default 0).
+<file>
+OPTION use_yams
+</file>
+Run the program with YAMS (modified FSPAK). The computing time can be dramatically improved.
 <file>
 OPTION tol 1d-12
 </file>
-Tolerance (or precision) (default 1d-14) for positive definite matrix and g-inverse subroutines. Convergence may be much faster by changing this value.
+Tolerance (or precision) (default 1d-14) for positive definite matrix and g-inverse subroutines.\\
+Convergence may be much faster by changing this value.
 <file>
 OPTION sol se
 </file>
-Store solutions and those s.e.
+Store solutions and those standard errors.
 <file>
-OPTION missing -1
+OPTION store_pev_pec 6
 </file>
-Set the missing value (default 0).
+Store triangular matrices of standard errors and its covariances for correlated random effects such as direct-maternal effects and random-regression effects in "pev_pec_bf90".
+<file>
+OPTION residual
+</file>
+y-hat and residuals will be included in "yhat_residual".
+<file>
+OPTION missing -999
+</file>
+Specify the missing value (default 0).
+<file>
+OPTION constant_var 5 1 2 ...
+</file>
+: effect number\\
+: first trait number\\
+: second trait number\\
+implying the covariance between traits 1 and 2 for effect 5.
 **Heterogeneous residual variances for a single trait**
@@ Line 40: / Line 62: @@
 OPTION hetres_pol 4.0 0.1 0.1
 </file>
-Initial values of coefficients for heterogeneous residual variances use //ln//(a0, a1, a2, ...) to make these values.
+Initial values of coefficients for heterogeneous residual variances using //ln//(a0, a1, a2, ...) to make these values.
-**Heterogeneous residual variances for multiple traits**
+**Heterogeneous residual variances for multiple traits**\\
 Convergence will be very slow with multiple trait heterogeneous residual variances
 <file>
@@ Line 51: / Line 73: @@
 OPTION hetres_pos 10 11 12 13
 </file>
-Specify the position of covariables (trait first). "10 10" or "10 11" could be linear for first and second traits, and "11 11" or "12 13" could be quadratic.
+Specify the position of covariables (trait first).
+"10 10" or "10 11" could be linear for first and second traits.\\
+"11 11" or "12 13" could be quadratic.
 <file>
 OPTION hetres_pol 4.0 4.0 0.1 0.1 0.01 0.01
 </file>
-Initial values of coefficients for heterogeneous residual variances use //ln//(a0, a1, a2, ...) to make these values (trait first). "4.0 4.0" are intercept for first and second traits. "0.1 0.1" could be linear and "0.01 0.01" could be quadratic.
+Initial values of coefficients for heterogeneous residual variances using //ln//(a0, a1, a2, ...) to make these values (trait first).\\
+"4.0 4.0" are intercept for first and second traits.\\
+"0.1 0.1" could be linear and "0.01 0.01" could be quadratic.\\
+To transform back to the original scale, use exp(a0+a1*X1+a2*X2).
+<file>
+OPTION SNP_file snp
+</file>
+Specify the SNP file name to use genotype data.
+<file>OPTION se_covar_function <label> <function></file>
+As an alternative of SE, calculate SD for function of (co)variances by repeated sampling of parameters estimates from their asymptotic multivariate normal distribution, following idea presented by Meyer and Houle 2013.\\
+\\
+''<label>''\\
+A name for a particular function (e.g., ''P1'' for phenotypic variance of trait 1, ''H2_1'' for heritability for trait 1, ''rg12'' for genetic correlation between traits 1 and 2, …).\\
+\\
+''<function>''\\
+A formula to calculate a function of (co)variances to estimate SD. All terms of the function should be written with no spaces.\\
+\\
+Each term of the function corresponds to (co)variance elements and could include any random effects (G, PE, ...) and residual (R) (co)variances.\\
+\\
+Notation is with reference to the effect number and the trait number (''G_eff1_eff2_trt1_trt2'') that indicate the element of the (co)variance matrix for random effect ''eff1'' and ''eff2'' and ''trt1'' and ''trt2'',\\
+where ''eff1'' and ''eff2'' are effect numbers 1 and 2, and ''trt1'' and ''trt2'' are trait numbers 1 and 2.\\
+''R_trt1_trt1'' indicates the element of the residual (co)variance matrix for traits 1 and 2.\\
+\\
+Several functions could be added, with one OPTION line per function.\\
+\\
+Examples:\\
+\\
+''OPTION se_covar_function  P  G_2_2_1_1+G_2_3_1_1+G_3_3_1_1+G_4_4_1_1+R_1_1''\\
+''OPTION se_covar_function  H2d  G_2_2_1_1/(G_2_2_1_1+G_2_3_1_1+G_3_3_1_1+G_4_4_1_1+R_1_1)''\\
+''OPTION se_covar_function  H2t  (G_2_2_1_1+1.5*G_2_3_1_1+0.5*G_3_3_1_1)/(G_2_2_1_1+G_2_3_1_1+G_3_3_1_1+G_4_4_1_1+R_1_1)''\\
+''OPTION se_covar_function  rg12  G_2_2_1_2/(G_2_2_1_1*G_2_2_2_2)**0.5''\\
+\\
+The first function calculates the SD for the total variance for a maternal model with permanent maternal effect, where 2 and 3 are the effect number for the direct and maternal additive genetic effects respectively, and 4 is the effect number for the maternal permanent random effect.
+The second function calculates the heritability for the direct component.
+The third function the total heritability.
+The fourth function calculates the SD of the genetic correlation between traits 1 and 2 for the direct genetic effect (effect number 2)
+<file>OPTION samples_se_covar_function <n></file>
+Set the number of samples to calculate SE for function of (co)variances.\\
+default value 5000
+<file>OPTION out_se_covar_function</file>
+Indicate to store in file samples of (co)variances function for postprocessing (histogram, etc.)