In some instances, REML estimation continuing from the ‘best’ estimates so far is
necessary. This is invoked with the -c option.
If specified, WOMBAT will attempt to read its ‘starting’ values from the file BestPoint in the current working directory. N.B. If this is not available or if a read error occurs, the run proceeds as a ‘new’ run, i.e. using the starting values given in the parameter file instead. The -c option selects estimation using the AI algorithm, unless another procedure is selected explicitly.
The amount of screen output can be regulated by the following options
-t selects terse output
-v selects verbose output, useful to check the parameter file
-d selects detailed output, useful for debugging
It is good practice, to start each analysis with a run which carries out the set-up steps only, checking that the summary information provided on the model of analysis and data structure in file SumModel.out (see 7.1.2) is as expected, i.e. that WOMBAT is fitting the correct model and has read the data file correctly. This is specified using --setup. This option also invokes verbose screen output.
For analyses comprising 18 or less covariance components to be estimated, WOMBAT defaults to the AI algorithm for maximisation. For other analyses, the default is for WOMBAT to begin with up to 3 iterates of the PX-EM algorithm, before switching to an AI algorithm. For reduced rank estimation, every tenth AI iterate is subsequently replaced by a PX-EM step. Two options are provided to modify this according to our perception of the quality of starting values for covariance components available, without the need to consider the ‘advanced’ options below.
If we are confident, that we have good starting values, this might cause an unnecessary computational overhead. Specifying --good reduces the maximum number of (PX-)EM iterates to 1. Similarly, for potentially bad starting values, estimation might converge more reliably if a few more initial (PX-)EM iterates were carried out. Specifying --bad sets this number to 8. If the increase in log likelihood during the initial (PX-)EM iterates is less than , WOMBAT will switch to the AI algorithms immediately.
WOMBAT uses a small positive value as operational zero to reduce numerical errors. The default value is . This can be changed specifying the run option --zero where is a single-digit integer. This option redefines the operational zero to be .
For variance component estimation parameterising to the elements of the Cholesky factors of covariance matrices, estimates are constrained to the parameter space by restricting the pivots in the decomposition to a small value. The default is . This can be changed through the run option --pivot where is the real value specifying the new limit.
WOMBAT writes out the currently best values of estimates of covariance components to the file BestPoint whenever the likelihood is increased. The option --best causes WOMBAT to read this file and write out the matrices of covariances and corresponding correlations in more readily legible format to the file BestSoFar.out. WOMBAT with this option can be used in a directory in which an estimation run is currently active, without interfering with any of the files used.
WOMBAT can be used for a simple BLUP run, using the ‘starting’ values given in the parameter files as assumed values for the true covariances. In this mode, no pruning of pedigrees is carried out. If -c is specified in addition, WOMBAT will try to read the values from the file BestPoint instead – this is useful to obtain ‘backsolutions’ after convergence of an estimation run. Solutions can be obtained either directly or iteratively:
HINT: For large problems, --solvit is best combined with --choozhz (see 5.3.1).
Change: The default for the PCG algorithm has been changed to the so-called
SSOR preconditioner. There are now five additional choices to vary the
preconditioner by appending the letter A, B, C, D or E:
--s1stepA invokes a simple diagonal preconditioning scheme.
--s1stepB provides a blockdiagonal preconditioner with the blocks equal to the effects for all traits in a multivariate analysis. However, if genetic groups are fitted as an additional random effect, the diagonal block for all levels (and traits) is used.
--s1stepC is like --s1stepB except that the full diagonal block for genotyped animals (all levels and traits) is utilised.
--s1stepD as for --s1stepC, full blocks for genotyped animals and genetic groups are used for preconditioning, but this is combined with the diagonal preconditioner for the remaining equations
--s1stepE provides a diagonal preconditioner for all effects other than genetic groups (equivalent to B for univariate nalyses).
Specifying --simul causes WOMBAT to sample values for all random effects fitted for the data and pedigree structure given by the respective files, from a multi-variate normal distribution with a mean of zero and covariance matrix as specified in the parameter file. Again -c can be used to acquire population values from the file BestPoint instead. No fixed effects are simulated, but the overall (raw) mean for each trait found in the data set is added to the respective records. Optionally, --simul can be followed directly (i.e. no spaces) by an integer number in the range of 1 to 999. If given, WOMBAT will generate simulated data sets (default ).
Simulation uses two integer values as seeds to initialise the pseudo-random number generator. These can be specified explicitly in a file RandomSeeds (see 22.214.171.124). Output file(s) have the standard name(s) SimData001.dat, SimData002.dat, , SimData.dat. These have the same layout as the original data file, with the trait values replaced by the simulated records; see 7.2.5.
This option is not available for models involving covariance option GIN (see 4.9.4).
Large sample theory indicates that maximum likelihood estimates are normally distributed with covariance matrix equal to the inverse of the information matrix. Hence, sampling from this distribution has been advocated as a simple strategy to approximate standard errors of ‘complicated’ functions of variance components without the need for a linear approximation or to evaluate derivatives .
WOMBAT provides the run option --sample to obtain such samples in a post-analysis step, with denoting the number of samples to be drawn. If is omitted, the number of samples is set to a value of . It requires output files from an estimation run (at convergence), namely BestPoint, AvInfoCovs and AvInfoParms to specify the multivariate Normal distribution to sample from. By default, samples for all covariance components in the model are generated. In addition, the covariance matrix for a single random effect only can be selected by specifying its name in a SPECIAL statement (see 4.16.7). Samples generated are written to a file with the standard name CovSamples_ALL.dat or CovSamples_.dat with the name of the random effect selected (see 7.2.12). These files are ‘formatted’ (text) files that are suitable for further analysis using standard statistical software packages. In addition, a file named SumSampleAI.out is written which summarizes details of the run together with means and variances across replicates.
This option is not implemented for random regression analyses or random effects with diagonal covariance matrices. It tends to work best for estimation runs with the PC option, even when matrices are estimated at full rank.
WOMBAT can be used as a ‘stand-alone’ program to invert a real, symmetric matrix. Both a ‘full’ inverse and a ‘sparse’ inverse are accommodated. ‘Full’ inversion of a dense matrix is limited to relatively small matrices - use run time option --limit to find the maximum size allowed in WOMBAT.
The matrix is expected to be supplied in a file, with one record per non-zero element in the upper triangle. Each record has to contain three space separated items: row number, column number and the matrix entry. There are several different ‘modes’:
This option should only be used for relatively small matrices.
HINT: Use this feature (with a minimum eigenvalue > 0) to modify an ‘invalid’ matrix of starting values for multivariate analyses.
The inverse is written out to filename.inv with one row per non-zero element, containing row number, column number and the element of the matrix (space separated).
Run option --hinv invokes a pre-analysis step to calculate the (inverse of) the joint relationship matrix between genotyped and non-genotyped animals in a single-step analysis. There are numerous options to select output, alignment and subsets of calculations. Documentation is available in Example 20 (9).
For some types of analyses a parameter ( e.g. the dilution factor for “social” genetic effects) is fixed at a given value and variance components are estimated for this value. To estimate the parameter then requires multiple runs for different values, each generating a point of the profile likelihood for this parameter. Provided an initial triplet of points can be established, comprised of a ‘middle’ parameter value with the highest likelihood bracketed by points with lower likelihoods, a quadratic approximation of the curve can be used to locate its maximum. WOMBAT collects the pairs of parameter values and corresponding likelihoods in a file with the standard name LogL4Quapprox.dat. Specifying the run option --quapp invokes an attempt at a quadratic approximation, utilizing the information from this file. If successful (i.e. if a suitable triplet of points can be found), the estimate of the parameter value at the maximum of the parabola is given, together with its approximate standard error.
For multivariate problems involving more than a few traits, it is often desirable to carry out analyses considering subsets of traits, for example, to obtain good starting values or to trace problems in higher-variate analyses back to particular constellations of traits.
WOMBAT provides the run time option --subset to make such preliminary analyses less tedious. It will cause WOMBAT to read the parameter file for a multivariate analysis involving traits and write out the parameter files for all uni- () or bi-variate () analyses possible. For , the program will prompt for the running numbers of the traits to be considered and write out a single parameter file. These subset analyses are based on the data (and pedigree) file for the ‘full’ multivariate model, using the facility for automatic renumbering of traits and subset selection, i.e. no edits of these parameter files are necessary.
N.B.: This option does not carry through any information from a SPECIAL block, and is not implemented for random regression models or analyses involving correlated random effects or permanent environmental effects fitted as part of the residuals.
On analysis, encountering the syntax for trait renumbering (see 4.9.7) causes WOMBAT to write out an additional file with the estimates for the partial analysis (Standard name EstimSubset.dat with to the trait numbers in the partial analysis, e.g. EstimSubset2+7.dat; see 7.2.6). In addition, the name of this output file is added to a file called SubSetsList.
HINT: WOMBAT will add a line to SubSetsList on each run – this may cause redundant entries. Inspect & edit if necessary before proceeding to combining estimates !
Combining estimates of covariances from analyses involving different subsets of traits is a regular task. This may be a preliminary step to a higher-dimensional multivariate analysis to obtain ‘good’ starting values. Alternatively, analyses for different subsets of traits may involve different data sets – selected to maximise the amount of information available to estimate specific covariances – and we may simply want to obtain pooled, possibly weighted estimates of the covariance matrices for all traits which utilise results from all partial analyses and are within the parameter space.
WOMBAT provides two procedures to combine estimates of covariance components from different analyses or modify existing matrices. These options are not available for analyses involving random regression models, correlated random effects or permanent environmental effects fitted as part of the residuals.
Option --itsum selects a run to combine estimates from partial analyses, using the ’iterative summing of expanded part matrices’ approach of Mäntysaari  (see also Koivula et al. ), modified to allow for differential weighing of individual analyses. For this run, a file SubSetsList is assumed to exist and list the names of files containing results from analyses of subsets, and, optionally, the weightings to be applied (see 7.3.9). Pooled covariance matrices are written to a file name PDMatrix.dat as well as a file named PDBestPoint (see 7.2.7).
HINT: Use of --itsum is not limited to combining bi-variate analyses or the use of files with standard names (EstimSubset.dat), but all input files must have the form as generated by WOMBAT.
To use --itsum to combine estimates from analyses involving different data sets, be sure to a) number the traits in individual analyses appropriately (i.e. with the total number of traits, not the number of traits in a partial analysis), and b) to use the syntax described in 4.9.7 to renumber traits – this will ‘switch on’ the output of subset results files.
Copy PDBestPoint to BestPoint and run WOMBAT with option --best to obtain a listing with values of correlations and variance ratios for the pooled results.
Option --pool is similar to --itsum but a) employs a maximum likelihood approach, as described by Meyer  , b) facilitates pooling of covariance matrices for all sources of variation simultaneously, and c) allows for penalties to be imposed aimed at ‘improving’ estimates by reducing sampling variation.
Input is as for --itsum and pooled estimates are written to files named PoolEstimates.out (summary file) and PoolBestPoint.
Option --expiry will print the expiry date for your copy of WOMBAT to the screen.
Option --limits can be used to find at the upper limits imposed on analyses feasible in WOMBAT, as ‘hard-coded’ in the program. N.B. Sometimes these are larger than your computing environment (memory available) allows.
Option --times causes WOMBAT to print out values for the CPU time used in intermediate steps.
Option --wide will generate formatted output files which are wider than 80 columns.
Run option --help causes a list of available run options to be printed to screen.
adiag: diagonal only, blox: trait x trait diag. blocks, full: full diag. block