1

ASReml Installation Guide

Last updated: April 2018

Please email any questions, corrections and additions to Erik Postma (e.postma@exeter.ac.uk)

2

Contents

Read this before you begin 3

1. Downloading ASReml 4 and ASReml-R 3 4

Stand-alone ASReml v4 4

ASReml-R v3 4

2. Installing and registering the standalone version of ASReml 5

Windows 5

Mac OS 6

3. Running the standalone version of ASReml 7

Windows 7

Mac OS 10

4. Installing and registering ASReml-R 11

Windows 11

Mac OS 11

Appendix 1: Using ConTEXT with ASReml under Windows 14

Appendix 2: Obtaining a license file 15

Obtaining a personal license 15

Obtaining a network license 19

3

Read this before you begin As you will be installing new software and making some changes to your system, you will most likely need an administrator account and 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 of Windows. In Windows 10, you can find this by going to Settings ® System ® About, and looking under System type.

There are multiple ways of installing and registering ASReml. Here I explain only the one that I have found to be the easiest to explain. It is not necessarily the most efficient.

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.

If you do not have a license file yet, proceed with downloading (Section 1) and installing (Section 2) the standalone version of ASReml, as you will need this to obtain the license file. How to obtain a license file can be found in Appendix 2.

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 10) and Mac (assuming macOS X Sierra 10.12). 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://cdn.vsni.co.uk/downloads/asreml/release4/4.1.0.1839mr/linux/linux32-install.txt (32-bit) and http://cdn.vsni.co.uk/downloads/asreml/release4/4.1.0.1839mr/linux/linux64-install.txt (64-bit).

Please read before doing! It will be worth it J

4

1. Downloading ASReml 4 and ASReml-R 3 There are standalone ASReml and ASReml-R versions for Windows (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 you need for your system in a place where you can easily find them back, for example on your desktop.

Stand-alone ASReml v4 Windows (32-bit): http://cdn.vsni.co.uk/downloads/asreml/release4/4.1.0.1904mv/windows/ASReml-4.1.0.1904-Win32.msi

Windows (64-bit): http://cdn.vsni.co.uk/downloads/asreml/release4/4.1.0.1904mv/windows/ASReml-4.1.0.1904-Win64.msi

Mac OS X: http://cdn.vsni.co.uk/downloads/asreml/release4/4.1.0.1839mr/macOSX/ asreml4.1mr.dmg

ASReml-R v3 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

5

2. Installing and registering the standalone version of ASReml Windows Double-click the installation file that you downloaded under 1 (ASReml-4.1.0.1904-Win32.msi for the 32-bit version and ASReml-4.1.0.1904-Win64.msi for the 64-bit version).

‘Accept’ the License Agreement.

Choose the folder where ASReml should be installed. The default is C:\Program Files\ASReml4\, 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:

If you are using a standalone license and you have a ‘asreml.lic’ file, click ‘Browse’ and find the ‘asreml.lic’ file.

Select it and click ‘Open’

Click ‘OK’, which installs the license key, and click ‘OK’ a few more times to start ASReml-W.

Click ‘Cancel’ to close ASReml-W.

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 on, for example, your desktop.

6

Mac OS Double click the installation file (asreml4.1mv.dmg)

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

Enter your administrator passwords if required.

If you you have a ‘asreml.lic’ file, open a Finder window and copy the license file (asreml.lic) from where you saved it to /Applications/asreml4/bin

7

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\ASReml4\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, 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. However, don’t use MS Word!

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

To do this, go to ‘Settings’ ® ‘About’ ® ‘System info’. Now choose ‘Advanced system settings’ on the left.

Finally, click the ‘Environment variables’ button.

8

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

Click ‘New’ and enter ‘C:\Program Files\ASReml\bin’ (without quotes):

1 2

3

9

After you have restarted your system, Windows will always be able to find ASReml irrespective of the folder from which you are calling it.

Open the command prompt (Windows System ® 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’.

All your output files will be placed in the same folder.

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

10

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 of text editors 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/). Whatever you do, do not 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.

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/asreml/release4/bin/asreml.sh /usr/local/bin/asreml

Note that this is one line and there is a space between …asreml.sh and /usr…

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 dragging 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.

11

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

It is most straightforward to install the ASReml-R package from the R command prompt instead of via the menu.

Windows Start R or RStudio

Run the following at the command prompt, but don’t forget to change the file path (underlined):

install.packages("C:\\Users\\erik\\Downloads\\asreml_3.0.zip", repos = NULL, type="source")

When copying the above to R, make sure it doesn’t contain any characters that R doesn’t understand.

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 link above).

Mac OS For reasons discussed at the end of this section, I am assuming you are running R through RStudio.

Run the following at the command prompt, but don’t forget to change the file path (underlined). Instead of typing the path and filename, you can simply drag to file to the R prompt:

install.packages(‘/Users/erik/Desktop/asreml_3.0_R_jy-apple-darwin.tar.gz’, repos = NULL, type="source"

When copying the above to R, make sure it doesn’t contain any characters that R doesn’t understand.

On a Mac, 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:

[1] "/Users/erik/Library/R/3.3/library"

12

[2] "/Library/Frameworks/R.framework/Versions/3.3/Resources/library"

Now open your favorite text editor (e.g. TextMate or TextWrangler, but NOT TextEdit) and create a plain text file containing the following two lines: ASREML_LICENSE_FILE=/Applications/asreml/release4/bin/asreml.lic DYLD_LIBRARY_PATH=$LD_LIBRARY_PATH: "/Users/erik/Library/R/3.3/library/asreml/libs

However, replace the underlined part with the location where you installed the ASReml-R package provided by ‘.libPaths()’. If you didn’t specify a location at installation and ‘.libPaths()’ returned multiple entries (as above), it will be in the first one.

Save this as a plain text file called ‘.Renviron’ (do not add .txt or another extension!) in your home folder (the folder that probably has your name and which contains your Documents, Downloads, etc. folders). Also, make sure that you use LF and not CR line endings.

Ignore the warning that you are trying to save a file that starts with a period (.). Because of this ‘.’ in front of the filename, you won’t be able to see the file you just created, but trust me, it is there.

Restart R.

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

NOTE: At the time of writing, I have gotten ASReml-R to work fine in RStudio and from the terminal, but not using the R GUI. If I try the latter, it will produce the following error message that I have been unable to resolve:

13

14

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 PI

15

Appendix 2: Obtaining a license file There are two types of licenses, personal and network licenses.

Obtaining a personal license You need to obtain the license using the computer that you are going to use ASReml on.

Windows Run ASReml-W by double-clicking the shortcut that has appeared on your desktop after installing ASReml (see Section 2).

The following window pops up:

Press ‘Register’, which will open this window:

Click ‘Register Online’.

This will take you to the VSNi website:

16

You have been provided with either an Activation code or a Site Reference (the Site Reference for the University of Exeter is VS13AF18). Enter this here and click ‘Submit’. This will take you to another form:

Complete this form and click ‘Submit registration’. The asreml.lic file will be sent to the email address provided.

Mac To obtain your license file, you need to run RequestLicense.app. Unfortunately, this app doesn’t work very well on more recent versions of Mac OS. To get it to run, you need to do a few things to your system. This is all a lot easier if you are logged into an Administrator account.

Open System Preferences ® Security & Privacy ® General, and set ‘Allow apps downloaded from:’ to ‘App Store and identified developers’. You will need administrator privileges to do this.

17

The app uses Xquartz, which you might already have installed. Unfortunately, it doesn’t run with versions that are newer than 2.7.8. If you have a newer version, one solution is to downgrade. XQuartz 2.7.8 can be downloaded here: https://www.xquartz.org/releases/index.html

Alternatively, you can run the following to lines in a terminal:

sudo mv /opt/X11/lib/libXt.6.dylib{,.bak}

sudo cp /opt/X11/lib{/flat_namespace,}/libXt.6.dylib

You will need to enter your administrator password.

Don’t try to run the app by clicking its icon. Instead, after you have installed ASReml, open a Finder window and navigate to Applications ® ASReml ® release4 ® bin. Now right-click (or control-left-click) on RequestLicense and select ‘Open’. You might again have to enter you administrator password.

If all the above worked well, the following window should appear:

Click the Register Online button, which will take you to the VSN website:

18

You have been provided with either an Activation code or a Site Reference (the Site Reference for the University of Exeter is VS13AF18). Enter this here and click ‘Submit’. This will take you to another form:

Submit the completed form and you should receive the asreml.lic file by email.

19

Obtaining a network license Windows When running ASReml-W for the first time, the following window appears:

Click Install and the following window appears:

Select ‘Install the following license text:’ and paste the following in the text box: SERVER asreml.lic.exeter.ac.uk 005056883A49 6983 USE_SERVER

Click OK and you should be up and running. Mac Create a plain text file using TextMate or TextWrangler (and not TextEdit) that contains the information on your license server. Your system administrator will be able to provide you with this. To use the site license of the University of Exeter, type:

20

SERVER asreml.lic.exeter.ac.uk 005056883A49 6983 USE_SERVER

Save this file as ‘asreml.lic’ in ‘/Applications/asreml/release4/bin’. Make sure you save it using LF line endings.