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

Installation of NLME under S-PLUS 5.1

Version 3.3.1 - September 2001

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

Port of NLME 3.x to S-PLUS 5.1 done with the help of Saikat DebRoy,
Dept. of Statistics, U. of Wisconsin.


1) Expand the tar file.

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

 % tar zxf nlme_SP5_3_3_1.tar.gz  

otherwise, use

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

(To distinguish commands to the shell from S-PLUS commands we will use
"%" as the shell prompt and ">" as the S-PLUS prompt. We use the
standard name "Splus5" to refer to the S-PLUS 5.1 script.)

You have probably already done this if you are reading this file.
Expanding the tar file creates three directories, NLME, NLMEDATA, and
SAS_Mixed, with subdirectories NLME/.Data, NLME/.Data/__SHelp,
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/__SHelp
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 PDF file, Usinglme.pdf, 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-PLUS, you should expand the tar
file in the directory $SHOME/library where $SHOME stands for the home
directory for S-PLUS.  You can determine the value of $SHOME by

 % Splus5 SHOME

2)  Install the code in the NLME directory

First, cd to that directory and create the file "makefile" with the
shell command 

 % Splus5 CHAPTER 

Initialize the S chapter, including the compilation of the C code with

 % Splus5 make 

and install the S source code in the .Data directory with

 % cat *.q | Splus5

You will see several warning messages of conflicting definitions of
functions, because an older version of NLME is included with the
standard distribution of S-PLUS 5.1; these can be ignored (see the
note at the end of this file).

3) Test the installation by sourcing the file "tests" within an S-PLUS
session started from the NLME directory.
 
 > options(conflicts.ok = T)
 > source("tests")

If the tests run properly, there should be no output before a new
prompt from S-PLUS. (The call to options(conflicts.ok = T) is used to
prevent warning messages about conflicting definitions of functions.) 

4) Install the help files with

 % Splus5 CATHELP_SGML .Data

This will convert the sgml files in the .Data/__Shelp directory to
html format, putting the resulting files in the .Data/__Hhelp
directory. The make_install script also handles the installation of
help files.

5) Using the functions in the NLME chapter 

After the NLME S chapter has been created, you can:

 - start S-PLUS 5.1 from within the NLME directory, in which case all 
   functions in NLME 3.3.1 will be automatically available.

 - attach the NLME S chapter to an S-PLUS session started in another
   directory, using

   > attach("NLME directory path")

   with the appropriate path of the NLME directory being provided.

 - attach the NLME S chapter as a library. If the NLME directory has
   been installed in $SHOME/library, you should use

   > library(NLME, first = T)

   (The first = T is required, as older versions of NLME functions are
   included in the "splus" library.) If NLME has been installed in
   another directory, say "mydir", you should use

   > library(NLME, first = T, lib.loc = "mydir")

6) Load the data sets in the directories NLMEDATA and SAS_Mixed/data

The data sets are included as separate S source files. You will need
to create separate S chapter in each directory by following
the same steps as in 2) above, after you cd to the appropriate
directory. A make_install script is also included in the each
directory to create the S chapter. 

After the S chapters have been created, you can attach them to an
S-PLUS session using the procedures described in 4) above. 

7) Examine the help files, with the NLME S chapter attached.

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

NOTE: The examples in the help files assume that the the data sets in
the NLMEDATA directory are available in the current S-PLUS
session. Because the standard version of S-PLUS includes older
versions of some of the datasets in NLMEDATA, not attaching the
NLMEDATA chapter may cause problems with the examples in the help
files. 

8) User's guide and help files 

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

NOTE: Because an older version of NLME is included with the standard
distribution of S-PLUS 5.1, warnings messages about conflicting
definitions of functions on databases ".Data" and "splus" will be
printed when functions in NLME 3.x are used. To prevent
the warning messages from being printed, you can set

 > options(conflicts.ok = T)


