Installing ASReml

Rationale

I provide this summary because I am repeatedly asked how to install ASReml for use with R. Please also read the installation instructions that are provided by VSNI. Generally, everything is explained, and there is no need to contact the VSNI support.

I am writing these notes mostly from memory, and would be happy if you let me know if there are mistakes/inconsistencies.

General information

ASReml, as used from R, comes in two pieces. First, there is the stand-alone software ASReml that needs to be installed and licensed. Then, there is a separate R package (ASReml-R) that provides the interface glue to drive the ASReml functions from R. You generally need to install both unless you want to work from the relatively primitive command interface provided by ASReml (not ASReml-R). This is recommended for very large data sets that R cannot handle.

Step by step instructions

  • First, register on the VSNI web site. You will need your login credentials later.
  • Then, download ASReml and ASReml-R from https://www.vsni.co.uk/downloads/asreml/upgrade/. Make sure you have the version that goes with your operating systems (Windows, Mac, Linux; 32 or 64bit).
  • Install ASReml, the stand-alone software. This software will need to be licensed to run, which is described below.
    Under Linux, I usually install it under /usr/local/asreml3, and create a symbolic from /usr/local/asreml3/bin/asreml.sh to /usr/local/bin/asreml. On a Mac, I'd install it in /Applications/asreml3.
  • Install ASReml-R, the R package that is used to interface ASReml from R. There are several ways in which you can do this:
    • If you use a R GUI (e.g. RStudio), then there generally is an option in the menu to install R packages from a local file. Under Windows, select the .zip file you downloaded. Under OS X or Linux, this will be a .tar.gz file.
    • Everything should also work by using install.packages(path_to_your_asreml-R.zip_or_tar.gz_file,repos=NULL) from the R command line. Under Windows and newer R versions, you may have to add the option type="binary"
    • From a terminal, under OS X or Linux, you can also use "R CMD INSTALL -l /usr/lib/R/site-library asreml_3.0_R_hj-linux-ia32.tar.gz", or "R CMD INSTALL asreml_3.0_R_hj-apple-darwin.tar.gz". The location where the library is installed may need to be adapted, and you may need superuser rights. The advantage will be that all users on this computer will have this R package available. However, only install the package this way if you know what you are doing.
  • Start the RequestLicense program to request a license file. It is located in the same directory as the ASReml executable. You'll need an activation code that you can obtain from me or from Bernhard Schmid for this step. You'll then get the license file by email, with instructions on how to install it. Essentially, you need to save it in the directory where ASReml resides.
  • From R, use library(asreml) to load the R package providing the interface glue. If you have a Mac and it says the license is not found (especially when using RStudio), you have to make sure an environment variable is set that tells ASReml where the license file is located. There are several options where you can set it in FreeBSD (the Unix underlying MacOS X), including a ".profile" file in your home directory, but it seems not all are considered depending on how R is started from within RStudio. What should work though is to put a file named ".Renviron" in your home directory. This file should contain the single line ASREML_LICENSE_FILE='/Applications/asreml3/bin/asreml.lic' (of course this needs to be adapted if you installed ASReml in another directory, or your license file has a different file name). If ASReml-R pesters about a missing license, check using "Sys.getenv()" that this environment variable is properly set, and that a valid "asreml.lic" file is really found there. As a quick hack you can also include Sys.setenv(ASREML_LICENSE_FILE="/Applications/asreml3/bin") at the beginning of your R script (assuming you put ASReml in this directory).
  • Under Linux, the automatically generated license files regularly fail, because the license manager software fails to read my hard drive's serial number (If that happens, you see that in the error message generated, which contains Hostid: DISK_SERIAL_NUM=0). In these cases, I contact Amanda Cox from VSNI, who can provide a special license files that also works under these conditions.
  • The ASReml license needs to be renewed after one year. Note that there is no grace period, i.e. ASReml will stop working from one day to the next. Generally, the new license codes are not available in advance.

Update regarding the installation on OS X (June 2017)

  • Make sure you allow the execution of software other than from Apple's app store. Apple seems to lock out everything that is not from "their" environment.
  • The new Quartz libraries have a structure that does not work with the "RequestLicense" program you need to activate ASReml. One solution is to downgrade Quartz, but what is preferable is setting a library load path to a version that (currently at least) is provided for compatibility:
    export DYLD_LIBRARY_PATH=/opt/X11/lib/flat_namespace
  • I don't use Macs and therefore cannot provide any support for this.

License renewal

To renew the ASReml license, simply remove the old, expired license file (asreml.lic) and re-register as described above (On Windows: start ASReml-W; on Linux: execute ./RequestLicense). There is no need to uninstall or re-install ASReml.

Additional resources

If you need to allow for negative variance components in your models, or just want nicely formatted output with Wald tests with denominator degrees of freedom, stars indicating significances, variance components, and (if available) stratum variances, then you might want to consider the test.asreml and asreml.nvc functions in my R package (http://www.ieu.uzh.ch/staff/leaders/niklaus/Rstuff.html).