Installing and Configuring R and Rstudio with ASReml-R

Authors

Biometry Hub, University of Adelaide

biometrytraining@adelaide.edu.au

Published

September 2023

Introduction

These instructions assume you already have a working version of R on your computer. If this is not yet the case, please follow these instructions: https://biometryhub.github.io/installing-r/installing-r.html

This guide does not assume any particular R development environment - it will work equally well with any option. You can find a PDF version of this guide here: https://biometryhub.github.io/installing-r/installing-asreml.pdf

This guide assumes you are running a relatively recent version of Microsoft Windows, for example Windows 8 or later, or Mac OS X/macOS 10.11 (El Capitan) or later. The guide will likely work for Debian based Linux distributions as well (E.g. Ubuntu flavours), however it is not extensively tested under those scenarios.

ASReml-R Installation

biometryassist

You will need the biometryassist package, which can be installed from CRAN via

if(!require(biometryassist)) install.packages("biometryassist")

ASReml-R

Once biometryassist is installed, the latest version of ASReml-R can then be installed with the commands

library(biometryassist)
install_asreml()

The install_asreml() function comes from the biometryassist package, hence the need to install and load that first.

All going well, you should get a confirmation that ASReml-R is installed successfully.

Activate ASReml-R

After you have installed ASReml-R, you will need to activate it. To do this, you will need to provide a licence code from VSNi, and possibly open two ports on your computer to allow communication over the internet with the VSNi licence server. To enter the licence code, use the following commands:

library(asreml)
asreml.license.activate()

This will result in a prompt such as:

Please enter your activation code (RET or 0 to exit):

The licence code is usually in the format AAAA-BBBB-CCCC-DDDD. Once entered, your computer will connect to the VSNi licence server to check the code is correct, and you will be informed of the outcome.

A successful licence activation will result in a message like the following:

Licensed to ABcDEfg
Ref: ABC12345 Expires: 2023-06-30, 487 days.

Additional Packages (Optional)

If you are participating in an intership with the Biometry Hub, you may require additional packages installed, such as ASMap and wgaim. Advice on further packages to install will be provided by your supervisor, but in many cases they can be installed using the same method as above.

CRAN packages

Most packages for R are available on CRAN, and can be installed with the following command:

install.packages(c("ASMap", "wgaim"))

GitHub packages

Some packages are not available on CRAN. These are commonly available to install via GitHub, but occasionally require a local installation.

To install packages from GitHub, you will first require the remotes package:

if(!require(remotes)) install.packages("remotes")

Once this is installed, you can install packages from GitHub with just the knowledge of the owner and repository names as in the following example:

remotes::install_github("biometryhub/weathervane")

The package in this example is called weathervane. It exists in a repository with the owner “biometryhub”. You can see this on the GitHub page here: https://github.com/biometryhub/weathervane.

The command above will download and install the package directly from GitHub, and may prompt you to update old packages that are already installed.

Other packages

Some packages are not available on CRAN or GitHub, and must be installed via an alternative method. One example of this is the ASExtras package, which adds additional functionality to asreml. To install this you will need to:

  1. Download the relevant package file for your Operating System and version of R. In the ASExtras example, the package website has the appropriate links for the files: https://mmade.org/asextras4/
  2. Once you have downloaded the file, you need to select it for installation. If using Rstudio, you can use the “Install” button in the Packages tab, and change the option in the top box (“Install from:”) to “Package Archive File (.zip, .tar.gx)”. This will cause a window to pop up to allow you to select the file you just downloaded.
  3. Alternatively you can use the command below, substituting the appropriate file path to the .zip or .tar.gz file.
install.packages("path/to/package.zip", repos = NULL)  # Windows version
install.packages("path/to/package.tar.gz", repos = NULL)  # macOS/Linux version

This should now proceed just like a regular package installation, though you may need to install additional dependency packages of the package you just installed.

Further resources

The above will get your basic setup ready but here are some links if you are interested in reading a bit further.