Analysis of Mixed Models

for S language environments

ASReml-R & ASReml-S installation notes


David Butler
Department of Primary Industries and Fisheries, Toowoomba, Queensland
david.butler@dpi.qld.gov.au


1 Introduction

The ASReml() functions and precompiled binaries of the numerical routines are available for the following configurations:

S-Plus  6/7
R
1.1 S-Plus
ASReml-S is distributed as a compressed archive to be unpacked in an appropriate library tree. Users must use the attach() or the library() mechanism to add the ASReml-S directory to the S-Plus session search path. The installation contains a prototype S.init file that may be used to create or replace an existing S.init in the local directory of the S-Plus installation tree to automate the attachment process . The shared object  ASReml-S.dll and the license manager are loaded using a .on.attach() function in the .Data directory of the ASReml-S installation. The scripts and data files used in the Reference Manual are installed in a subdirectory Examples of the ASReml-S installation directory.
1.2 R
ASReml-R is distributed as an R binary package and installed in an R library tree.  Users must use a mechanism such as library() to add the ASReml-R package directory to the R session search path. The shared object  ASReml-R.so or ASReml-R.dll is loaded by library.dynam() when the ASReml() library is attached.
1.3 Licensing
Use of the compiled routines requires a license key that must be obtained from VSN International. This will restrict usage to a specified machine, group of machines, or network. Initial use of ASReml on Microsoft Windows systems will generate a demonstration key that is valid for 30 days.

2 Installation

2.1 Installing on Microsoft Windows systems

2.1.1 S-Plus
The ASReml() functions and compiled code for S-Plus 6 and 7 systems are embedded in a compressed archive, ASReml-win-32-xxx.zip where xxx is a 3 digit version number.

  1. Terminate any S-Plus sessions.
  2. Navigate to or create a directory to hold the ASReml() chapter
  3. Unpack the ASReml archive ASReml-win-32-200.zip in the above directory
  4. The file S.init provides a simple way to execute system wide S-Plus commands at start-up. This script file resides in the local subdirectory of the S-Plus installation hierarchy. A prototype containing sample commands to attach the ASReml() chapter is restored in the ASReml-S installation directory.

    Assuming a standard S-Plus installation, edit the contents of the prototype S.init to reflect your local settings and append the contents to any existing C:\Program Files\Insightful\S-Plus70\local\S.init file.
  5. Installation is complete; the ASReml() directory should now appear in the S-Plus search path at startup.
2.1.2 R
The ASReml() functions and compiled code are assembled as an R binary package in zip format, ASReml_x.xx.zip where x.xx is a 3 digit version number. One of
can be used to install from the ASReml-R archive. On Windows systems, the first option will install ASReml() in the default library tree and is the most convenient for most users:
  1. Initiate an R session using Rgui.exe
  2. Choose the Packages menu from the main window bar
  3. Choose Install packages from local zip files  from the Packages menu
  4. Navigate to the location of the ASReml-R package file ASReml_2.00.zip 
  5. Select the archive name and click Open to install ASReml() in the default R library tree
  6. The R function call library(ASReml) will add ASReml() to the current R session search path. Consult the R documentation for ways to automate this or for alternative methods.

2.2 Installing ASReml() on Linux systems

ASReml-R is distributed as a binary package in tar.gz form, ASReml_x.xx_R_i686-pc-linux-gnu.tar.gz, where x.xx is a 3 digit version number. In addition to unpacking the ASReml-R installation into a library tree, two environment variables must be set to ensure that the license management system is accessible and that the license file can be found. If you choose to install ASReml() in the system library directory you may need super user privileges to complete the installation depending on how R has been installed.
  1. Login as a user with write permission to the target ASReml() directory
  2. At the system command prompt execute

    R CMD INSTALL [--library lib] ASReml_2.00_R_i686-pc-linux-gnu.tar.gz

    The target library tree can be optionally specified via the --library flag.  By default, packages are installed in the library tree rooted at the first directory given in the environment variable R_LIBS if this is set and non-null, and into the default R library tree (/usr/lib/R/library) otherwise.
  3. The path to the shared object libvl.so (installed in the libs subdirectory of the ASReml-R library tree) must be available to the dynamic linker, either through the LD_LIBRARY_PATH environment variable or the file /etc/ld.so.conf (if supported). In addition, the environment variable ASREML_LICENSE_FILE must contain the full path to the license file ASReml.lic provided by VSN International. This file can reside on any accessible file system.


    ASREML_LICENSE_FILE=<lic-path>/ASReml.lic
    export ASREML_LICENSE_FILE
    LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<lib-path>/ASReml/libs
    export LD_LIBRARY_PATH

    where <lic-path> is the fully qualified path to the directory containing ASReml.lic and <lib-path> is the path to the root of the ASReml-R installation tree.



     
  4. The R function call library(ASReml) will add ASReml() to the current R session search path. Consult the R documentation for ways to automate this or for alternative methods.
  5. If you see the error message "Error: cannot restore segment prot after reloc: Permission denied" when trying to use the ASReml() function, you may be experiencing problems due to the default configuration of the SELinux kernel extensions. One possibile solution is to change the default security context for ASReml by issuing the command:
    • chcon -t texrel_shlib_t /usr/lib/R/library/ASReml/libs/*.so*

3 Installing the ASReml() license

All license manager information is currently reported in the convergence monitoring window, that is, when an ASReml() job is executed. The job will not proceed when the license manager reports an error.

3.1 Microsoft Windows systems

In the absence of any license files, ASReml() will prompt the user to generate a demonstration license which will remain valid for 30 days. A registration file  ASRemlRegister.txt is written to the working directory; complete the details in this file and email to  sales@VSNi.co.uk to obtain a valid license. Upon receipt of the license file (ASReml.lic), it is recommended that it be saved in c:\Program Files\Common Files\VSN International\Licenses\ASReml.lic.

3.2 UNIX systems

ASReml() will not generate a demonstration license on UNIX systems. If ASReml() cannot find a license file, a registration file ASRemlRegister.txt is written to the current working directory. This file contains both the hostid and hostname of the system and when completed should be emailed to sales@VSNi.co.uk to obtain a valid key. Upon receipt of the license file (ASReml.lic), save it to a convenient location and ensure the environment variable ASREML_LICENSE_FILE is set correctly.

4 Testing the Installation

Running a quick test will make sure that the software and license are installed correctly. For example, the split-plot example from the ASReml-R Reference Manual can be run as follows:

> library(ASReml)
Loading required package: lattice
Loading required package: grid
> data(oats)
> names(oats)
[1] "Blocks"   "Nitrogen" "Subplots" "Variety"  "Wplots"   "yield"   
> oats.asr <- ASReml(fixed = yield ~ Variety+Nitrogen+Variety:Nitrogen,
+ random = ~Blocks + Blocks:Wplots, data=oats)

ASReml(): 2.00 Library: 2.00bf  Run: Thu Aug  9 12:08:54 2007
Licensed to: VSN International Ltd
Serial Number: 12348765 Expires: 31-Aug-2007 (22 days)

Equations:  44 (20 dense)
Initial update shrinkage factor: 0.316
8 singularities detected in design matrix

     LogLik         S2      DF

   -216.5453    306.1641    60  12:08:54
   -213.5687    256.3384    60  12:08:54
   -211.0520    214.6065    60  12:08:54
   -209.6629    186.6835    60  12:08:54
   -209.4004    179.2338    60  12:08:54
   -209.3782    177.3097    60  12:08:54
   -209.3779    177.0864    60  12:08:54

Finished on: Thu Aug  9 12:08:54 2007
 
LogLikelihood Converged 

5 Support

If you are unable to install or run ASReml(), or if you require further information or help, please contact VSN International:

VSN International Ltd.
5 The Waterhouse
Waterhouse Street
Hemel Hempstead
Herts HP1 1ES
United Kingdom
Tel: +44 (0)1442 450230
Fax: +44 (0)870 1215653
http://www.vsni.co.uk
support@vsni.co.uk



Copyright Notice 
R
is a trademark of The R Foundation for Statistical Computing.
S-Plus is a trademark of Insightful Corporation.
Windows is a trademark of Microsoft Corporation.