1

ASReml Installation Guide

Zurich, May 2014

Please email any questions, corrections and additions to Erik Postma (erik.postma@ieu.uzh.ch)

Contents Read this before you begin 2  

1. Downloading ASReml 3 and ASReml-R 2  Stand-alone ASReml 2  ASReml-R 2  

2. Installing and registering the standalone version of ASReml 3  Windows 3  Mac OS 4  

3. Running the standalone version of ASReml 5  Windows 5  

1) Using a graphical user interface 5  2) From the command line 5  

Mac OS 7  

4. Installing and registering ASReml-R 8  Windows 8  Mac OS 8  

Appendix 1: Using ConTEXT with ASReml under Windows 10  

 

2

Read this before you begin - As you will be installing new software and making some changes to your system, you will need the

administrator password. As always, be careful and proceed at your own risk!

- If you are a Windows user, you will need to find out whether you are running a 32-bit or a 64-bit version. In Windows 7, you can find this by going to Control Panel → System and Security → System, under System - System type. Although I did not test this for ASReml, in principle you should be able to run the 32-bit version on a 64-bit platform, but not the other way around.

- There are multiple ways of installing and registering ASReml. Here I explain only the one that I have found easiest.

- The instructions assume that you already have a license file (asreml.lic). Make sure that the file is named exactly like this, and save it in a location where you can easily find it back, for example on your desktop.

- Especially on a Windows platform, installing ASReml-R is easier when you first install the stand-alone version. I therefore recommend installing both.

- Here I will only provide instructions for Windows (assuming Windows 7) and Mac (assuming OS X 10.9). I am assuming that if you are running Linux, you have already done much more complicated things than installing ASReml, so you should be able to get it up and running yourself using the official instructions at http://www.vsni.co.uk/downloads/asreml/release3/linux32-install.txt.

- Please read before doing! It will be worth it!

1. Downloading ASReml 3 and ASReml-R There are standalone ASReml and ASReml-R versions for Windows and Linux (either 32 and 64-bit), as well as Mac OS (both 32 and 64-bit). Below you find the direct link to the various installation packages. Save the files in a place where you can easily find them back, for example on your desktop.

Stand-alone ASReml

Windows (32-bit): http://www.vsni.co.uk/downloads/asreml/release3/ASReml-3.0.22.2-vb_x86.msi

Windows (64-bit): http://www.vsni.co.uk/downloads/asreml/release3/ASReml-3.0.22.2-vb_x64.msi

Mac OS X: http://www.vsni.co.uk/downloads/asreml/release3/3.0.22.2vb/asreml3.0vb.dmg

ASReml-R

Windows (32- and 64-bit): http://www.vsni.co.uk/downloads/software/asreml-r/release3/R3.0.0/asreml_3.0.zip

Mac OS X: http://www.vsni.co.uk/downloads/software/asreml-r/release3/R3.0.0/asreml_3.0_R_jy-apple-darwin.tar.gz

If these links don’t work, or if you need a Linux installer or an older version, go to http://www.vsni.co.uk/downloads/asreml/latest?data=upgrade

3

2. Installing and registering the standalone version of ASReml

Windows

Double-click the installation file that you downloaded under 1 (ASReml-3.0.22.2-vb_x86.msi for the 32-bit version and ASReml-3.0.22.2-vb_x64.msi for the 64-bit version).

‘Accept’ the License Agreement.

Choose the folder where ASReml should be installed. The default is C:\Program Files\ASReml3\, which should be fine for most users.

Click ‘Install’.

Most likely you will now be asked for your administrator password.

This will have created a shortcut on your Desktop to ASReml-W, which is a (not very good) graphical user interface (GUI) for ASReml.

Double-click this icon, which will open a window telling you that you don’t have a valid license key.

Click the ‘Install’ button:

‘Browse’ to the ‘asreml.lic’ file, select it and click ‘Open’

Click ‘OK’, which installs the license key, and click ‘OK’ another two times to start ASReml-W.

Click ‘Cancel’ to close ASReml-W.

4

We will not use this GUI, so you can delete the shortcut if you want to. As the license file has been copied to its correct location, you can also delete the license file that you saved, for example on your desktop.

Mac OS

Double click the installation file (asreml3.0vb.dmg)

In the window that opens, drag the asreml3 icon over into the Applications folder, as indicated by the big arrow:

Enter your administrator passwords if required.

Now copy the license file (asreml.lic) from where you saved it into /Applications/asreml3/bin

5

3. Running the standalone version of ASReml

Windows

Windows users can run ASReml in 2 ways:

1) through a graphical user interface 2) from the command line

Below I will explain how to set up both.

1) Using a graphical user interface

Although ASReml comes with its own graphical user interface (GUI), ASReml-W, most people don’t use this. Instead they use the free text editor ConTEXT, which can communicate directly with ASReml. This allows the user to prepare and edit input files, run the job, and view the output files in a single software environment. Although it is no longer maintained, ConTEXT can still be downloaded from here: http://www.contexteditor.org

Instructions for configuring ConTEXT come with the current distribution of ASReml. The text of the readme.txt file, which together with the file ASReml.chl (which is the highlighter for ASReml) can be found at C:\Program files\ASReml3\Context after a standard installation, can be found in Appendix 1.

If you have got everything set up correctly, you should be able to run ASReml by pressing ‘F9’ while you have the command file you want to run open.

ConTEXT is not essential for the course, so it is not necessary to set it up if you don’t want to.

2) From the command line

Alternatively, you can run ASReml from the command line. To do this, you will still need a text editor to write the input files. This doesn’t have to be ConTEXT, however.

To be able to run ASReml from any folder when using the command line, it is recommended to add the location of ASReml3.exe (most likely ‘C:\Program Files\ASReml3\bin’) to the list of folders that Windows automatically searches for executable files (listed in the so-called PATH environment variable).

To do this, click the Start button, right-click ‘Computer’ and select ‘Properties’:

Select ‘Advanced system settings’ and enter your administrator password:

6

Now click the ‘Environment variables’ button:

Under System variables, scroll down to the line that says ‘Path’. Select this line and click ‘Edit’:

Go to the end of the line and add (without the quotes) ‘; C:\Program Files\ASReml3\bin’

After you have restarted your system, Windows will always be able to find ASReml.

7

Now open the command prompt (Start → All Programs → Accessories → Command prompt)

Navigate to the folder containing your input files by typing ‘cd ’ (without the quotes, including the space), followed by the path to the folder (for example \users\erik\documents\asreml\analysis1. To save yourself some typing, you can also drag the folder in to the Command prompt window.

To run asreml, type ‘asreml ’ followed by the name of the command file, e.g. my_analysis.as, so asreml my_analysis.as

To rerun my_analysis.as, you simply press the up-key, and press return again.

Mac OS

There is no convenient user interface for Mac users. However, you will soon find that you don’t really need one. All you will need is a good text editor. Although there are plenty around, I would recommend using one that allows you to have multiple files open in different tabs, and which automatically shows you the latest content of a file without having to refresh or reopen the file. I have found TextMate to be very useful (http://macromates.com/). Don’t use MS Word or Pages!

To be able to run ASReml from any folder you want, you have to tell the system where to find it by creating a symbolic link. You only have to do this once.

To do this, start by opening a terminal. You will find this in your Applications\Utilities folder.

At the prompt in your terminal window, type

sudo ln -s /Applications/asreml3/bin/asreml.sh /usr/local/bin/asreml

Press enter and type your administrator password.

To run ASReml, you open a terminal and you navigate to the folder containing your input files by typing ‘cd ’ (without the quotes, including the space) and drag the folder that contains the file to the terminal. Alternatively you can of course write out the path yourself.

To run a script called my_analysis.as, you write ‘asreml my_analysis.as’ and press return.

To rerun my_analysis.as, you simply press the up-key, and press return again.

 

8

4. Installing and registering ASReml-R Only in case you want to do something special, then will need the detailed installation guide, which can be found here: http://www.vsni.co.uk/downloads/asreml/release3/install-asreml-R.pdf

Windows

Start R

Go to ‘Packages’ → ‘Install package(s) from local zip files’

Navigate to the ‘asreml_3.0.zip’ file, select it and click ‘Open’

Load the package with ‘library(asreml)’

It will automatically check for the license file in the default location. If you have followed the instructions for the stand-alone version above, you should be all set now. If you didn’t install the standalone version, or if your license file is location in a different folder, read the detailed installation guide (see above).

Mac OS

Start R

Go to ‘Packages & Data’ → ‘Package Installer’

Change ‘CRAN (binaries)’ to ‘Local Source Package’

Click ‘Install’, navigate to ‘asreml_3.0_R_jy-apple-darwin.tar.gz’, select it and click ‘Open’.

ASReml-R doesn’t automatically know where to look for the license file. Furthermore, it needs to know where to find your other libraries. To tell it this, do the following:

Open R and type ‘.libPaths()’

This will give you something like this:

"/Library/Frameworks/R.framework/Versions/3.0/Resources/library"

9

Now open your favorite text editor and create a plain text file containing the following two lines. However, replace the underlined part with the output of ‘.libPaths()’ that got above, without the quotes: ASREML_LICENSE_FILE=/Applications/asreml3/bin/asreml.lic DYLD_LIBRARY_PATH=$LD_LIBRARY_PATH:/Library/Frameworks/R.framework/Versions/3.0/Resources/library/asreml/libs

Save this as a plain text file called .Renviron in your home folder (the folder that probably has your name and which contains your Documents, Downloads, etc. folders).

If you are using TextEdit, be sure to format it as plain text, rather than as rich text, by going to Format → Make Plain Text. If you only see the option Make Rich Text, then you are already in Plain Text mode.

Ignore the warning that you are trying to save a file that starts with a period (.)

Close and restart R.

You should now be able to load the ASReml-R library in R or R-Studio with library(asreml).

10

Appendix 1: Using ConTEXT with ASReml under Windows

Context Notes on using ASReml v3 from Context ======= ===================================== ConText is a popular choice among ASReml users on the Windows platform. This is a third party product and ASReml support does not include user support with respect to the use of Context. ConText is available from http://www.context.cx/. To install Context, download and run this file. Then copy the file ASReml.chl to C:\Program Files\Context\Highlighters. A little bit of setting up is required to run ASReml conveniently. We assume ASReml is installed in the standard location: C:\Program files\ASReml3\bin\asreml.exe. To enable ASReml to run from Context under <F9>, type <Options> <Environment Options> <Execute keys> <Add> file extensions: as, asr <F9>Execute "C:\Program files\ASReml3\bin\asreml.exe" Start In %p Parameters %f Hint ASReml To access the User Guide by typing <F12>, find <ADOBE ACROBAT path> by right clicking the ADOBE READER icon and selecting <Properties>. Then continue with: <F12>Execute <ADOBE ACROBAT path> Start In %p Parameters "C:\Program files\ASReml3\doc\UserGuide.pdf" Hint User Guide In a similar way, you can setup Context to process a standard .pin file by typing: <Options> <Environment Options> <Execute keys> <Add> file extensions: pin <F9>Execute "C:\Program files\ASReml3\bin\asreml.exe" Start In %p Parameters -p %f Hint ASReml PIN