Welcome to ASReml for R. This introduction is aimed at getting users working with ASReml in the R statistical environment as quickly as possible.

ASReml-R fits the general linear mixed model to moderately large data sets with complex variance models, using the Average Information (AI) algorithm and Residual Maximum Likelihood (REML) to estimate variance components, and sparse  matrix methods for computational efficiency. The R implementation offers a compact formula based syntax for specifying the linear model, and associated variance models for the random effects.

This guide covers the fundamental steps to working effectively with ASReml-R:

  1. System requirements
  2. Getting the software
  3. The ASReml license
  4. Installing ASReml-R
  5. Updating ASReml-R
  6. Running ASReml in R
  7. Getting help

(Editorial comment: An alternative navigation guide to this page, compared to the clickable TOC above, is to have expandable/collapsible sections - so the reader can expand the sections they are interested in.)

System requirements

ASReml-R requires a recent, though rarely the absolute latest, version of R for your computing platform; a warning is issued when the package is installed if the running version of R is not sufficiently recent. Pre-compiled versions of R for most common operating systems can always be found via the R website. This is all that is required to begin working with ASReml-R, however, additional R packages or external editing environments referred to below may provide for a more productive user environment.

Getting ASReml-R

ASReml-R binary packages are available for Windows 32 bit systems, and for Linux and Mac-OSX hosts in both 32 and 64 bit versions. The latest packages are always available here and are posted on the VSN website typically within two business days of an update.

The ASReml license

The sources of the ASReml compiled code are protected, and a license to use the shared library must be obtained from VSN International. On Windows systems, a 30 day trial license is automatically generated when the asreml() function is first called, however, this facility is not available on other systems. In either case, the file asremlregister.txt containing necessary registration information is created and should be sent to VSN so a valid license can be generated. Installation details of the VSN license file are included in the package and on the installation page.

Installing ASReml-R

The ASReml-R package is available as an R zip archive for Windows or in tar.gz format for other platforms. The installation instructions include details for all versions.

Updating ASReml-R

Upgrading to a more recent version of ASReml-R simply involves downloading the appropriate package and repeating the steps in the installation instructions that are relevent to unpacking and installing the archive. That is, unless the (re)installation location has changed, or the license file has been moved, any environment variables previously set will not need to be altered, and the package needs only to be installed into an R library tree in the usual way. ASReml-R does not need to be uninstalled prior to upgrading, but the upgrade process will fail if the asreml package is attached to the R session prior to commencing the install process.

Running ASReml in R

R provides the power and flexibility of a command line interface (CLI) to access its rich array of computational methods. Other user interfaces exist, or are under development, and progress in this area can be followed by subscribing to the R special interest group on graphical user interface (GUI) development. However, there are no current plans to add asreml to any of the menu/dialogue box style GUIs under development, and the CLI is fundamentaly the preferred method of running asreml. This clearly a longer learning curve for novice or occasional users, but such effort is recognized as profitable in the longer term.

A powerful companion to the CLI is a fully featured text editor that is aware of the R language, which facilitates writing R script files, and provides a simple mechanism to submit selected regions within a script to an R command line process (and capture the results). On Linux systems the Emacs text editor combined with application specific plug-ins has long provided what is arguably one of the most powerful program editing environments.The S language plug-in, Emacs Speaks Statistics (ESS), extends this capability to R command scripts and allows interaction with an R command line session running in an Emacs window. ESS is offered as an official RPM package for some popular Linux distributions.

On Windows systems, an R command line window (Rterm) runs within the Rgui, and an associated script window with basic capabilities is available from the File drop-down menu. A convenient all-in-one Emacs distribution for Windows that bundles ESS and other useful Emacs plug-ins can be downloaded from Vincent Goulet's webpage. Other alternatives exist, such as Tinn-R, and as the choice of an interface to R can be a personal one, users are encouraged to explore the options available at the R GUI website.

A brief introduction to running asreml in an Emacs session is included in the Users Guide.

Getting help

The Users Guide is included in the doc subdirectory of the ASReml-R installation tree and is available (when the asreml library is loaded) from within R via the function call. Help on individual asreml functions is available via the normal R help system using, for example, help(asreml), and as reference cards in portable document format.

A set of worked examples is included among the how-tos along with special interest topics supported by R code, and finally a comprehensive exposition of the underlying theory appears in the e-Book.