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.
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.
- ASReml needs a license. As of 2018, I have purchased a pool of floating licenses, which means that the total number of simultaneous users is limited, but not the total number of installations. Please contact me for a license file. In return, I expect a contribution to the license costs, which will depend on how many people use the license. This file needs to be saved in the directory where ASReml resides, or in your home directory.
- I am running the license server outside the university network. This has the advantage that you can use asreml from everywhere, without VPN, as long as you have an internet connection.
- 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).
Fair use of your license
With our licensing model, only a limited number of people can use ASReml simultaneously.
- A floating license is claimed when you load the asreml library (e.g. library(asreml) in R)
- The license is only released once you terminate your R session
To play fair, please:
- Load asreml only when you really need it. Don't make it a habit to load it at the beginning of all your R scripts!
- Terminate your R session once you are done. Don't leave R open all day while writing manuscripts, or while you go to classes or for lunch. This will prevent other people from using ASReml in that time.
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:
- I don't use Macs and therefore cannot provide any support for this.
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).