$Id: INSTALL,v 1.4 2001/09/24 21:26:37 pinheiro Exp $ 
Copyright (C) 1999, 2000, 2001  Jose C. Pinheiro and Douglas M. Bates

Installation of Mixed-Effects Code for S and S-plus

Version 3.3.1 - September 2001

Authors: Jose Pinheiro, Bell Labs, Lucent Technologies
         Douglas Bates, Dept. of Statistics, U. of Wisconsin - Madison



The first step in installing this code is to expand the tar file.
After that you follow different procedures depending on whether you
are running S or you are running S-plus for Unix, versions 3.1 through
3.4.

1) Expand the tar file.

If you are using the GNU version of tar, you can use

 % tar zxf nlme3_3_1.tar.gz  

otherwise, use

 % gunzip -d -c nlme3_3_1.tar.gz | tar xf    

(To distinguish commands to the shell from S commands we will use "%"
as the shell prompt and ">" as the S prompt.)

You have probably already done this if you are reading this file.
Expanding the shar file creates three directories, NLME, NLMEDATA, and
SAS_Mixed, with subdirectories NLME/.Data, NLME/.Data/.Help,
SAS_Mixed/data, and SAS_Mixed/transcripts. The S source, the S data
for tests, and the C source files are in the directory NLME.  This
documentation is also in the directory NLME.  The help files for all
the S functions will be installed in the NLME/.Data/.Help
directory. The NLMEDATA directory contains data sets that illustrate
the use of the functions and methods available in the NLME
directory. The SAS_Mixed directory some of the data sets from the book
"SAS System for Mixed Models" by Littell, Milliken, Stroup, and
Wolfinger (1996) SAS Institute and a PostScript file with the paper
"lme for SAS PROC MIXED Users" describing how the data sets can be
analyzed using the lme function. If you wish to make the nlme code
part of your standard version of S, you should expand the tar file in
the directory $SHOME/library where $SHOME stands for the home
directory for S or S-plus.  You can determine the value of $SHOME by
either

 % S SHOME

or

 % Splus SHOME

2)  Install the code

2.1) Installation using S-plus version 3.1 or later.

Create the file "Makefile" with the shell command

 % Splus CHAPTER  *.c *.q

If you are familiar with the "make" utility you may wish to inspect
the Makefile and decide if you want to modify it for a dynamic load or
a static load.  By default, the Makefile will be set for a static load.

Install the S source code and the documentation with the shell command

 % make install

This produces a considerable amount of output including some warning
messages.  Assume that it worked correctly unless there are explicit
error messages.

Finally, compile the C code and create a loadable version with

 % make

Again, there will probably be some error codes from trying to create
directories that already exist but they will also indicate that they
are being ignored.

Go to step 3 for testing.

2.2) Installation under S or S-plus version 3.0

(If you have S-plus version 3.0, replace all references to "S" by
"Splus" in the following commands.)

Install the S source code in the .Data directory with

 % cat *.q | S

Note: Next we create the file Makefile with the CHAPTER command to S.
If this is the first time the CHAPTER command is being used at your
installation, you will have to correct a bug in the shell script.  See
the notes on "Repairing the CHAPTER shell script" below.

Create the file Makefile with

 % S CHAPTER *.c

Under S a file called "makefile" is created.  It will contain the
local definitions of CFLAGS, FFLAGS and LDFLAGS.  Under Splus the file
is called "Makefile" and will not contain a full definition of CFLAGS
or a definition of FFLAGS or LDFLAGS.  You will need to add these by
hand.  They are the options for the C compiler, the Fortran compiler,
and the loader, respectively.  Generally you would add "-O" to the
definition of CFLAGS and FFLAGS.  Other flags will depend on your
local system.

Note:  If you are going to use dyn.load2 to load the compiled code,
read the documentation for dyn.load2.  On MIPS-based workstations,
such as DECstations or Silicon Graphics, special flags must be given
to the C compiler and the loader so dyn.load2 will work correctly.

Compile the C code and make a statically loaded version of the code.

There is again a difference between S and Splus version 3.0.  Under S,
this can be done by

  % S make all

Under Splus, you must set an environment variable SHOME.  The method
for doing this depends on whether you are using the C-shell or another
shell such as the Bourne shell, ksh, or bash.  For the C-shell, use
  % setenv SHOME `Splus SHOME`
For other shells use
  % export SHOME; SHOME=`Splus SHOME`

Now the compilation is done by

  % make all

See the notes below on "Dynamic Loading" if you wish to create a
version for dynamic loading.

3) Test the installation by sourcing the file "tests" within S or
S-plus.  (If you created a dynamically loaded version, you will first
need to load the object file as indicated in the section on "Dynamic
Loading".)

  > source("tests")

If the tests run properly, there should be no output before a new
prompt from S.

4) Load the data sets in the directory NLMEDATA

The data sets are included as separate S source files. To load it into
S or Splus use 

 % cat *.q | S

where S should be replaced by Splus, when appropriate. Alternatively
you may source the files directly in S or Splus.
 
 % S 
 > source("Alfalfa.q")
 . . .


5) Load the data sets in the directory SAS_Mixed/data

The data sets are included as separate S source files. To load it into
S or Splus use 

 % cat *.q | S

where S should be replaced by Splus, when appropriate. Alternatively
you may source the files directly in S or Splus.
 
 % S 
 > source("Animal.q")
 . . .

6) Examine the help files.

 % S
 > help(lme)               # on-line documentation
 > help(lme, offline = T)  # print a copy of the documentation.
 > q()

NOTE: The examples in the help files assume that the the data sets in
the NLMEDATA directory have been properly loaded. Because the standard
version of S-PLUS includes older versions of some of the datasets in
NLMEDATA, not loading the newer data sets may cause problems with the
examples in the help files.

7) User's guide and help files 

A user's guide is available in the postscript file U_Guide.ps in the
NLME directory. It contains examples of the use of the code. The
postscript file HelpFunc.ps in the NLME directory contains copies of
all the help files available in NLME/.Data/.Help. The postscript file
HelpData.ps in the NLMEDATA directory contains descriptions of the
data sets included in that directory.

				NOTES

Note 1:  Repairing the CHAPTER shell script.

While testing a similar installation procedure, we discovered a bug in
the script $SHOME/cmd/make.init.  This bug is present in versions of S
up to the April 1992 version and in Splus 3.0.  For us, the script
never gets beyond the section

    # if input is a file, source in the definitions from the file
    if test -f $input
    then
	    S < $input || echo "make.init: Problem with S functions in file $input"; exit 1
	    input=./.Data
    fi

The fix is to have your S administrator change this to

    # if input is a file, source in the definitions from the file
    if test -f $input
    then
	    S < $input || { echo "make.init: Problem with S functions in file $input"; exit 1;}
	    input=./.Data
    fi


Note 2:  Dynamic Loading.

The S functions and accompanying C code can be used three ways;
dynamically loaded by the user, statically loaded by the user, and
statically loaded by the S administrator.

The commands in part (2) should have generated a library called
NLME.a and several object files including nlmefit.o and nlme_i.o.
If you are using S-plus version 3.1 or higher and modify the Makefile
to use dynamic loading, a file called "NLME_l.o" will automatically be
created. Otherwise, you must create the file NLME_l.o with
    % ld -r -o NLME_l.o nlmefit.o NLME.a
If you use dyn.load2(), you do not need to do this but there is no
harm in doing it.  This is only done once. If you modified the
Makefile to use dynamic loading with a shared object, a file called
"NLME.so" will automatically be created.

Each time you run S, you will have to load the compiled code with
one of the following lines of S code.  (NOTE: you only need to use
ONE)

    % S
    > dyn.load("NLME_l.o")    # if dyn.load() is available
    > dyn.load2("NLME_l.o")   # if you ran ld -r -o ... as above
    > dyn.load.shared("NLME.so") # shared object
    > dyn.load2("nlmefit.o", user="NLME.a") # otherwise
    > dyn.load2("nlme_i.o", user="NLME.a")# alternate version


Note 3:  Adding the nlme library to the standard libraries

To add the nlme library to the standard library, you must be able to
log in as "s".  The shar file containing this file should be expanded
in $SHOME/library to form a directory $SHOME/library/nlme.  Then go
through steps 1 - 4.  Compare the makefile in this directory with the
one in the maps library directory and make the appropriate changes.
(You are supposed to know what you are doing if you have read this
far.)  Add this library to $SHOME/library/what.to.make and
$SHOME/library/what.to.glue then follow the instructions in section 4
of the S Administration documentation.  Also, rename the file
README.library as README and modify the $SHOME/library/README file by
adding a reference to this library.

Note 4: Trellis library

All plotting functions included with LME 3.0 make use of functions
defined in the trellis library. They will not work unless the trellis
library is available in your S-PLUS session.



