Chapter 3
Getting started with WOMBAT



3.1 Installation

WOMBAT is distributed as a pre-compiled executable file. A number of versions are available. The main target operating system is Linux. In addition, executable files for Windows environments are available.

3.1.1 Installation for Linux operating systems

1.
Download the version appropriate to your machine from
http://didgeridoo.une.edu.au/km/wombat.php
2.
Uncompress and unpack the file (nn optional/depending on version) using
   tar -zxvf wombatnn.tar.gz
This will create the directory WOMBAT which contains the executable wombat.
3.
Check that your system recognises wombat as an executable file, e.g. using
   ls -l WOMBAT/wombat
If necessary, use the chmod command to add executable permission or access permission for other users, e.g.
   chmod a+x WOMBAT/wombat.
4.
Make sure that the operating system can find wombat, by doing one of the following :

HINT: PATH is set in your login file, e.g. .login_usr, or shell start-up file, e.g. .tcshrc; use printenv PATH to check your current PATH settings.
You make have to log out and log in again before changes in your PATH are recognised, and wombat is found by the system.

3.1.2 Installation under Windows

As a courtesy, a 64-bit version of WOMBAT, womba_W64.zip, is available that will run under Windows. This has been cross-compiled under Linux and appears to run in MSYS and CYGWIN environments or a DOS window.

This can be downloaded from
http://didgeridoo.une.edu.au/km/wombat.php

For MSYS or CYGWIN adapt the Linux instructions for installation. Otherwise unzip wombat_W64.zip. This will give you the executable file wombat.exe.

3.1.3 Running WOMBAT

WOMBAT is expected to be run from a command line interface, i.e. you need to open a ‘terminal’ window and type in the appropriate command, hitting return to start the program running.

The general form of the command (under Linux and its emulation) is
   wombat options parfile
with parfile the ‘parameter file’ specifying everything WOMBAT needs to know about the input files and models of analysis (see chapter 4 for full details), and options any run time options you may wish to give (see chapter 5). If you have not put the executable file somewhere the operating system can find it (or have not modified your PATH settings), you will need to replace wombat above by the full path, e.g. /home/agbu/WOMBAT/wombat if the program has been placed in /home/agbu/WOMBAT.

3.1.3.1 Running WOMBAT under Windows

If you have installed MinGW/MSYS, you should open such ‘terminal’ and run WOMBAT in it in the same way as under Linux. Otherwise, you should open a DOS type window and type the command in it. Remember to use backwards rather than forward slash(es) if you need to type a full path to the executable.

You can run wombat.exe by simply double-clicking on it. However, this is not recommended! WOMBAT creates screen output which lets you monitor how a run is progressing. More importantly, this screen output will provide some diagnostics when something has gone wrong, e.g. help you remedy errors in the parameter or other input files. Hence, if you really want to start WOMBAT by double-clicking on an icon, you should make sure that the window which is opened does not close automatically after the run finishes or aborts! A simple way to do this is to create a .bat file.

rem Simple .bat file to run WOMBAT in a DOS window 1
rem Assumptions: 2
rem  1) parameter file is wombat.par 3
rem  2) other run time options are given in wombat.par 4
rem  3) wombat.exe resides in  C:\Program_Files\WOMBAT 5
@echo off 6
color 70 7
echo "Ready to run WOMBAT" 8
pause 9
C:\Program_Files\WOMBAT\wombat -v 10
echo "WOMBAT has finished" 11
pause 12
exit 13

3.1.4 Examples and testing

A number of worked examples, complete with output files and captured screen output, are provided; see chapter chapter 9 for further details. These can be downloaded and installed in analogous manner to the program. This description is appropriate for Linux and Cygwin; for Windows adjust as appropriate, e.g. by replacing forward with backward slashes, etc.

1.
Download examples.tar.gz from
http://didgeridoo.une.edu.au/km/wombat.php
2.
Uncompress and unpack the file using
   tar -zxvf examples.tar.gz
Do this in the same directory as above! This will create the directory Examples with subdirectories Example1, , Examplen.

Each subdirectory contains the input and output files for a run of WOMBAT, together with a records of the screen output in the file typescript. To test your installation,

1.
Choose an example and change into its directory.
2.
Make a new temporary subdirectory, e.g. try.

N.B.: This should be a ‘parallel’ directory to sub-directories A,B,, i.e. Examplen/try not Examplen/A/try. Otherwise, you need to adjust the paths to the data and pedigree files in the parameter file for WOMBAT to be able to find them !

3.
Copy all input files to the temporary directory.
4.
Change into the temporary directory and run WOMBAT, using the same command line options (if any) as shown in the beginning of typescript.
5.
Compare your output files with those supplied – apart from date and time they should be virtually identical; small discrepancies in higher decimals may occur though.
6.
Delete temporary subdirectory.

Repeat for at least one more example.

3.1.5 Compilation notes

3.1.5.1 Linux

64-bit versions of WOMBAT have been compiled under Ubuntu 14.04 the Intel ifort (version 19.0.3.199) compiler together with the MKL library to provide highly optimised BLAS and LAPACK routines. Parallel execution is achieved by loading the multi-threaded version of this library together with OpenMP instructions.

32-bit versions are no longer maintained.

3.1.5.2 Windows

The Windows versions of WOMBAT have been ‘cross-compiled’ under Linux using the gfortan compiler (version 7.3) together with the OpenBLAS library. Only a 64-bit versions is supplied.

Previous versions compiled under Cygwin or MinGW are no longer maintained.

3.1.6 Updates

WOMBAT is set up to ‘expire’ after a certain date. Usually this is approximately 5–6 years after compilation (not download!) date. This feature aims at reducing the number of outdated copies being used, and any associated problems. WOMBAT will print out a warning message when used in the month preceding the expiry date. In addition, a run time option is available to query the program for this date.

If your copy of WOMBAT has expired – or you simply want to update to a newer version, please repeat the installation steps outlined above (section 3.1).

3.2 Using the manual

WOMBAT caters for novice users by supplying defaults for most aspects of estimation. Essential sections of the manual to ‘get started’ are :

The most ‘difficult’ part of using WOMBAT is to correctly set up the parameter file. The detailed rules given in chapter 4 are best understood following some example(s). The suite of examples provided templates for various types of analyses performed by WOMBAT, and a range of different models.

HINT: A suitable strategy might be

i)
Choose the type of analysis you are interested in, and decide on the model of analysis. Start with a relatively simple scenario.
ii)
Try to find an example which matches the type of analysis and fits a not too dissimilar model.
iii)
Inspect the example parameter and input files.
iv)
Read the description of individual entries in the parameter file (Chapter 4). Compare each section to the relevant section in the example parameter file.
v)
Try to modify the example file for your data (& pedigree) file and model.

3.3 Troubleshooting

WOMBAT has undergone fairly rigorous testing, more so for some models than for others. However, there are bound to be errors and inconsistencies – especially early in its development.

Errors in the input files are the most likely source of problems which are not a program bug. Some of these are trapped, leading to a programmed error stop (with a screen message of “exit WOMBAT” or “Programmed (error) stop for WOMBAT encountered”). Almost certainly, this is due to erroneous input, in particular a mistake in the parameter file ! You should be able to figure out what is wrong from the accompanying brief error message and fix it. Others might simply cause the program to abort.

If – after thoroughly checking your parameter file and other input files – you think you have encountered a genuine error in the program, please submit a ‘bug report’, as specified below1 .

To submit an informative ‘bug report’, please carry out the following steps:

1.
Download the latest version of WOMBAT which has been compiled with optimisation switched off, and checks switched on from
http://didgeridoo.une.edu.au/km/wombat.php

and extract the executable wombat_chk as described above.

2.
Use wombat_chk for run(s) to demonstrate the error.
3.
Try to recreate the problem using one of the test data sets and pedigree files supplied. Edit these as appropriate to generate the structure causing the problem if necessary, e.g. delete or add records or effects in the model.
Only if absolutely necessary, use a small subset of your data and pedigree files – the smaller the better – but definitely less than 100 animals in the pedigree and less than 500 records !
4.
Use a new, ‘clean’ directory for the run(s).
5.
Run wombat_chk with the -v or -d option.
Remember that wombat_chk is compiled with checking switched on and thus will require several times longer than wombat for the same task.
6.
Capture all screen output using the script command.
7.
tar the complete directory and gzip it (or use any other common compression utility), and send it to me.
I need all input files, output files and the typescript file !
8.
If you have any theory on what might be the problem, please tell me.

This may sound like a lot of work, but is necessary to for me to even begin to try understanding what is going on !

3.4 Additional documentation

3.4.1 On-line version of the manual

didgeridoo.une.edu.au/km/WOMBAT/WWW/manual.html

3.4.2 Notes distributed with specific examples

As time progressed, additional specialised capabilities have been added to WOMBAT which are not (yet) fully covered in the manual. Some notes are distributed together with the examples illustrating these features, e.g.

3.4.3 Wiki pages

The “Wicked WOMBAT Wiki” can be found at
didgeridoo.une.edu.au/womwiki

It provides a selection of notes related to WOMBAT and general issues of REML estimation. In particular, there are frequently asked question sections covering