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
- Microsoft WindowsTM
i86 32 bit systems
R
- Linux (built on SUSE
V10.0)
- Microsoft Windows i86 32 bit
systems
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.
- Terminate any S-Plus sessions.
- Navigate to or create a directory to hold the asreml()
chapter
- Unpack the asreml archive asreml-win-32-200.zip
in the above directory
- 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.
- 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
- Install packages from local zip
files on the Packages menu in the RGui
- The install.packages()
function
- The batch processing command R CMD
INSTALL package
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:
- Initiate an R session using Rgui.exe
- Choose the Packages menu from
the main window bar
- Choose Install
packages from local zip files from the Packages
menu
- Navigate to the location of
the asreml-R
package file asreml_2.00.zip
- Select the archive name and
click Open
to install asreml()
in the default R library tree
- 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.
- Login as a user with write
permission to the target asreml()
directory
- 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.
- 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.
- These environment variables could be set on a per user basis at login by adding the following to the appropriate (for your shell) start-up script:
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.
- Alternatively, either or both environment
variables could be set on a per session basis by including the above
lines in the R start-up script which typically resides in /usr/bin.
This may not be the most satisfactory approach as the R start-up script
is overwritten by each new R installation and there is also a copy of
the R script in R_HOME/bin.
- The path to the shared libraries may also be set by including it in the /etc/ld.so.conf file. To do this switch user to root and:
- Edit the file /etc/ld.so.conf to add an entry for <lib-path>/asreml/libs
- Run /sbin/ldconfig to update the environment
- 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.
- 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.