\chapter{Installation}

To use Zelig, you must install the statistical program R (if it is not
already installed), the Zelig package, and some R libraries (coda,
MCMCpack, sandwich, VGAM, and zoo).  

Note: In this document, {\tt >} denotes the R prompt.  

\subsubsection{If You Know R} 

We recommend that you launch R and type 
\begin{verbatim}
> source("http://gking.harvard.edu/zelig/install.R")
> library(Zelig)
\end{verbatim}
then proceed to \Sref{overview}.  For Windows R, you may edit the 
{\tt Rprofile} file to load Zelig automatically at launch (after which you
will no longer need to type {\tt library(Zelig)} at startup).  Simply
add the line:
\begin{verbatim}
options(defaultPackages = c(getOption("defaultPackages"), "Zelig"))
\end{verbatim}

\subsubsection{If You Are New to R}

If you are new to R, we recommend that you read the following section
on installation procedures as well as the overview of R syntax and
usage in \Sref{a:R}.

This distribution works on a variety of platforms, including Windows
(see \Sref{ss:win}), MacOSX (see \Sref{ss:osx}), and Linux (see
\Sref{ss:unix}).  Alternatively, you may access R from your PC using a
terminal window or an X-windows tunnel to a Linux or Unix server (see
\Sref{ss:unix}).  Most servers have R installed; if not, contact your
network administrator.

There are advantages and disadvantages to each type of installation.
On a personal computer, R is easier to install and launch.  Using R
remotely on a server requires a bit more set-up, but does not tie up
your local CPU, and allows you to take advantage of the server's speed.

\section{Windows}\label{ss:win}

\subsubsection{Installing R}

Go to the Comprehensive R Archive Network website
\url{(http://www.r-project.org)} and download the latest
\hlink{installer for
  Windows}{http://cran.us.r-project.org/bin/windows/base/} at
\hlink{\url{http://cran.us.r-project.org/bin/windows/base/}}{http://cran.us.r-project.org/bin/windows/base/}
Double-click the {\tt .exe} file to launch the R installer.  We recommend
that you accept the default installation options if this your first
installation.

\subsubsection{Installing Zelig}

Once R is installed, you must install the Zelig and VGAM packages.  There
are three ways to do this.  
\begin{enumerate}
\item We recommend that you start R and then type:
\begin{verbatim}
> source("http://gking.harvard.edu/zelig/install.R")
> library(Zelig)
\end{verbatim}
\item Alternatively, you may install each component package individually 
in R:
\begin{verbatim}
> install.packages("Zelig")
> install.packages("zoo")
> install.packages("sandwich")
> install.packages("MCMCpack")
> install.packages("coda")
> install.packages("lattice")
> install.packages("mvtnorm")
> install.packages("VGAM")
> install.packages("sna")
> install.packages("systemfit")
> install.packages("nnet")
> install.packages("gee")
> install.packages("mgcv")
> library(Zelig)
\end{verbatim}
Zelig will load the optional libraries whenever their functions are
needed; it is not necessary to load any package other than Zelig at startup.  

\item \label{manual.windows}Alternatively, you may use the drop down
  menus to install Zelig.  This requires four steps.
\begin{enumerate}
\item \label{win.zelig} Go to \hlink{the Zelig
    website}{http://gking.harvard.edu/bin/windows/contrib/\rvers/} and
  and download the latest release of Zelig.  The VGAM, MCMCpack,
coda, zoo, and sandwich packages are available from
\hlink{CRAN}{http://cran.r-project.org/src/contrib/PACKAGES.html}.  Store these
  \texttt{.zip} files in your R program directory.  For example, the
  default R program directory is {\tt C:$\backslash$Program
  Files$\backslash$R$\backslash$\rwvers$\backslash$}.\footnote{Note
  that when updating R to the latest release, the installer does not
  delete previous versions from your {\tt C:$\backslash$Program
  Files$\backslash$R$\backslash$} directory.  In this example, the
  subdirectory {\tt $\backslash$\rwvers$\backslash$} stores R version
  \fullrvers.  Thus, if you have a different version of R installed,
  you should change the last part of the R program directory file path
  accordingly.}
\item Start R.  From the drop-down menus, select the ``Packages'' menu
  and then the ``Install Files from Local Zip Files'' option.
\item A window will pop up, allowing you to select one of the
  downloaded files for installation.  There is no need to unzip the
  files prior to installation.  Repeat and select the other downloaded
  file for installation.
\item At the R prompt, type \texttt{library(Zelig)} to load the
  functionality described in this manual.  Note that Zelig will
  automatically load the other libraries as necessary.
\end{enumerate}

\item An additional \emph{recommended but optional step} is to set up
  R to load Zelig automatically at launch.  (If you skip this step,
  you must type {\tt library(Zelig)} at the beginning of every R
  session.)  To automate this process, edit the {\tt Rprofile} file
  located in the R program subdirectory ({\tt C:$\backslash$Program
    Files$\backslash$R$\backslash$\rwvers$\backslash$etc$\backslash$}
  in our example).  Using a text editor such as Windows notepad, add
  the following line to the {\tt Rprofile} file:
\begin{verbatim}
options(defaultPackages = c(getOption("defaultPackages"), "Zelig"))
\end{verbatim}
\end{enumerate}

Zelig is distributed under the \hlink{GNU General Public License,
  Version 2}{http://www.gnu.org/licenses/gpl.txt}.  After
installation, the source code is located in your R library directory,
which is by default {\tt C:$\backslash$Program
  Files$\backslash$R$\backslash$\rwvers$\backslash$library$\backslash$Zelig$\backslash$}.

\subsubsection{Updating Zelig}

There are two ways to update Zelig.
\begin{enumerate}
\item We recommend that you periodically update Zelig at the R prompt
  by typing:
\begin{verbatim}
> update.packages()
> library(Zelig)
\end{verbatim}
\item Alternatively, you may use the procedure outlined in
  \Sref{win.zelig} to periodically update Zelig.  Simply download the
  latest {\tt .zip} file and follow the four steps.
\end{enumerate}

\section{MacOS X}\label{ss:osx}

\subsubsection{Installing R}  

If you are using MacOS X, you may install the latest version of R
(\fullrvers\ at this time) from the CRAN website \hlink{
  http://cran.us.r-project.org/bin/macosx/}{http://cran.us.r-project.org/bin/macosx/}.
At this time, Zelig is not supported for R on MacOS 8.6 through 9.x.

\subsubsection{Installing Zelig}\label{osx.manual}

Once R is installed, you must install the Zelig and VGAM packages.
There are several ways to do this.
\begin{enumerate}
\item {\bf For RAqua}:
  \begin{enumerate}
    
  \item We recommend that you start R, and then type:
\begin{verbatim}
> source("http://gking.harvard.edu/zelig/install.R")
> library(Zelig)
\end{verbatim}
(You may ignore the warning messages, unless they say ``Non-zero exit 
status''.)
\item Alternatively, to avoid the warning messages, you need to install 
each package individually and specify the specific installation path:
\begin{verbatim}
> install.packages("Zelig", lib = "~/Library/R/library")
> install.packages("zoo", lib = "~/Library/R/library")
> install.packages("sandwich", lib = "~/Library/R/library")
> install.packages("MCMCpack", lib = "~/Library/R/library")
> install.packages("coda", lib = "~/Library/R/library")
> install.packages("lattice", lib = "~/Library/R/library")
> install.packages("mvtnorm", lib = "~/Library/R/library")
> install.packages("VGAM", lib = "~/Library/R/library")
> install.packages("sna", lib = "~/Library/R/library")
> install.packages("systemfit", lib = "~/Library/R/library")
> install.packages("nnet", lib = "~/Library/R/library")
> install.packages("gee", lib = "~/Library/R/library")
> install.packages("mgcv", lib = "~/Library/R/library")
> library(Zelig)
\end{verbatim}
    where \texttt{\~{}/Library/R/library} is the default local library
    directory. Zelig will load the other libraries whenever their functions
    are needed; it is not necessary to load these packages at startup.
    
  \item Alternatively, you may use the drop down menus to install
    Zelig.  This requires three steps.  
  \begin{enumerate} 
  \item Go to \hlink{the Zelig
      website}{http://gking.harvard.edu/src/contrib/} and 
    download the latest release of Zelig.  The VGAM, MCMCpack,
coda, zoo, and sandwich packages are available from
\hlink{CRAN}{http://cran.r-project.org/src/contrib/PACKAGES.html}.
Save these \texttt{.tar.gz} files in a convenient place.
  \item Start R.  From the drop-down menus, select the ``Packages''
    menu and then the ``Install Files from Local Files'' option.
  \item A window will pop up, allowing you to select the one of the
    downloaded files for installation.  There is no need to unzip
    the files prior to installation.  Repeat and select the other
    downloaded file for installation.
  \end{enumerate} 
  
\end{enumerate}

\item {\bf For command line R:} 
  \begin{enumerate}
  \item Before installing command line R, you need to create a local R
    library directory.  If you have done so already, you may skip to
    the next step.  Otherwise, at the terminal prompt in your home
    directory, type:
\begin{verbatim}
% mkdir ~/Library/R ~/Library/R/library
\end{verbatim}
  \item Modify your configuration file to identify {\tt
      \~{}/Library/R/library} as your R library directory.  There are
    two ways of doing this:
    \begin{enumerate}
    \item Open the {\tt .Renviron} file (or create one, if you don't
      have one) and add the following line:
\begin{verbatim} 
R_LIBS = "~/Library/R/library"
\end{verbatim}
    \item {\it Alternatively}, you may modify your shell configuration
      file.  For a Bash shell, open your {\tt .bashrc} file and add
      the following line:
\begin{verbatim}
export R_LIBS="$HOME/Library/R/library"
\end{verbatim} %$
      \end{enumerate}
    \item Start R and at the prompt, type:
\begin{verbatim}
> source("http://gking.harvard.edu/zelig/install.R")
> library(Zelig)
\end{verbatim}
(You may ignore the warning messages, unless they say ``Non-zero exit 
status''.)
\item Alternatively, to avoid the warning messages, you need to install 
each component package separately and specify the installation path:
\begin{verbatim}
> install.packages("Zelig", lib = "~/Library/R/library")
> install.packages("zoo", lib = "~/Library/R/library")
> install.packages("sandwich", lib = "~/Library/R/library")
> install.packages("MCMCpack", lib = "~/Library/R/library")
> install.packages("coda", lib = "~/Library/R/library")
> install.packages("lattice", lib = "~/Library/R/library")
> install.packages("mvtnorm", lib = "~/Library/R/library")
> install.packages("VGAM", lib = "~/Library/R/library")
> install.packages("sna", lib = "~/Library/R/library")
> install.packages("systemfit", lib = "~/Library/R/library")
> install.packages("nnet", lib = "~/Library/R/library")
> install.packages("gee", lib = "~/Library/R/library")
> install.packages("mgcv", lib = "~/Library/R/library")
> library(Zelig)
\end{verbatim}
      Although the {\tt lib} argument is optional, we recommend that
      you set it to the default RAqua directory
      (\verb|"~/Library/R/library"|), in case you later decide to
      install the RAqua GUI (which has a different default directory).
      \end{enumerate}
\end{enumerate}
  
At the R prompt, type \texttt{library(Zelig)} to load the
functionality described in this manual.  Note that Zelig will
automatically load the other packages as necessary.
  
Zelig is distributed under the \hlink{GNU General Public License,
  Version 2}{http://www.gnu.org/licenses/gpl.txt}.  After
installation, the source code is located in your R library directory,
{\tt \~{}/Library/R/library/Zelig/}.

\subsubsection{Updating Zelig}
  
There are two ways to update Zelig.
\begin{enumerate}

\item We recommend that you start R and, at the R prompt, type:
\begin{verbatim}
> update.packages()
\end{verbatim}
  
\item Alternatively, you may remove an old version by command by
  typing {\tt R CMD REMOVE Zelig} at the terminal prompt.  Then
  download and reinstall the package using the installation
  procedures~\Sref{osx.manual} outlined above.
\end{enumerate}

\section{UNIX and Linux}\label{ss:unix}

\subsubsection{Installing R}
Type {\tt R} at the terminal prompt (which we denote as {\tt \%} in
this section) to see if R is available. (Typing \texttt{q()} will
enable you to quit.)  If it is installed, proceed to the next section.
If it is not installed and you are not the administrator, contact that
individual, kindly request that they install R on the server, and
continue to the next section. If you have administrator privileges,
you may download the latest release at the
\hlink{CRAN}{http://cran.r-project.org} website.  Although
installation varies according to your Linux distribution, we provide
an example for Red Hat Linux 9.0 as a guide:

\begin{enumerate}

\item Log in as root.

\item Download the appropriate binary file for Red Hat 9 from CRAN.
  For example, for Red Hat 9 running on the Intel 386 platform, go to
  \url{http://cran.r-project.org/bin/linux/}. 

\item Type the following command at the terminal prompt:\newline {\tt
    \% rpm -ivh R-\fullrvers-1.i386.rpm}

\end{enumerate}

\subsubsection{Installing Zelig}\label{sss:unix.library}

Before installing Zelig, you need to create a local R library
directory. If you have done so already, you can skip to
\Sref{unix.zelig}. If not, you must do so before proceeding because
most users do not have authorization to install programs globally.
Suppose we want the directory to be {\tt \~{}/.R/library}.  At the
terminal prompt in your home directory, type:
\begin{verbatim}
% mkdir ~/.R ~/.R/library
\end{verbatim}
Now you are ready to install Zelig.\label{unix.zelig} There are two
ways to proceed.

\begin{enumerate}
\item Recommended procedure: 
  \begin{enumerate}
  \item Open the {\tt \~\,/.Renviron} file (or create it if it does
    not exist) and add the following line:
\begin{verbatim}
R_LIBS = "~/.R/library"
\end{verbatim}
    You only need to perform this step once.
  \item Start R.  At the R prompt, type:
\begin{verbatim}
> source("http://gking.harvard.edu/zelig/install.R")
> library(Zelig)
\end{verbatim}
(You may ignore the warning messages, unless they say ``Non-zero exit 
status''.)
\item Alternatively, you can avoid the warning messages by installing each 
component package separately and specifying the installation path:  
\begin{verbatim}
> install.packages("Zelig", lib = "~/Library/R/library")
> install.packages("zoo", lib = "~/Library/R/library")
> install.packages("sandwich", lib = "~/Library/R/library")
> install.packages("MCMCpack", lib = "~/Library/R/library")
> install.packages("coda", lib = "~/Library/R/library")
> install.packages("lattice", lib = "~/Library/R/library")
> install.packages("mvtnorm", lib = "~/Library/R/library")
> install.packages("VGAM", lib = "~/Library/R/library")
> install.packages("sna", lib = "~/Library/R/library")
> install.packages("systemfit", lib = "~/Library/R/library")
> install.packages("nnet", lib = "~/Library/R/library")
> install.packages("gee", lib = "~/Library/R/library")
> install.packages("mgcv", lib = "~/Library/R/library")
> library(Zelig)
\end{verbatim}
\item Finally, create a {\tt .Rprofile} file in your home directory, containing the line:
\begin{verbatim}
library(Zelig)
\end{verbatim}
This will load Zelig every time you start R.  
  \end{enumerate}  

\item \label{unix.manual} Alternatively: 
  \begin{enumerate}
  \item Add the local R library directory that you created above ({\tt
      \~\,/.R/library} in the example) to the environmental variable
    {\tt R\_LIBS}.
%  If you do not know how to
%    define an environmental variable, download the script {\tt
%      Rloclib} from the \hlink{Zelig download
%      directory}{http://gking.harvard.edu/R/CRAN/src/contrib/}, and
%    run it by typing at the terminal prompt:
%\begin{verbatim}
% bash Rloclib [path]
%\end{verbatim}
%    where {\rm [path]} is an optional input for the local library
%    directory path. If you don't specify a path, the default value is
%    {\tt \~\,/.R/library}.
  \item Download the latest bundles for Unix from the \hlink{Zelig
      website}{http://gking.harvard.edu/src/contrib/}, and (for
    the VGAM, MCMCpack, coda, sandwich, and zoo packages) from the
    \hlink{CRAN}{http://cran.r-project.org/src/contrib/PACKAGES.html}
    website.
  \item If {\tt XX} is the current version number, at the terminal
    prompt, type:
\begin{verbatim}
% R CMD INSTALL Zelig_XX.tar.gz
% R CMD INSTALL zoo_XX.tar.gz
% R CMD INSTALL sandwich_XX.tar.gz
% R CMD INSTALL MCMCpack_XX.tar.gz
% R CMD INSTALL coda_XX.tar.gz
% R CMD INSTALL lattice_XX.tar.gz
% R CMD INSTALL mvtnorm_XX.tar.gz
% R CMD INSTALL VGAM_XX.tar.gz
% R CMD INSTALL sna_XX.tar.gz
% R CMD INSTALL systemfit_XX.tar.gz
% R CMD INSTALL nnet_XX.tar.gz
% R CMD INSTALL gee_XX.tar.gz
% R CMD INSTALL mgcv_XX.tar.gz

% rm Zelig_XX.tar.gz zoo_XX.tar.gz sandwich_XX.tar.gz MCMCpack_XX.tar.gz coda_XX.tar.gz lattice_XX.tar.gz mvtnorm_XX.tar.gz mvtnorm_XX.tar.gz VGAM_XX.tar.gz sna_XX.tar.gz systemfit_XX.tar.gz nnet_XX.tar.gz  gee_XX.tar.gz mgcv_XX.tar.gz
\end{verbatim}
\item Create a {\tt .Rprofile} file in your home directory, containing the line:  
\begin{verbatim}
library(Zelig)
\end{verbatim}
This will load Zelig every time you start R.  
  \end{enumerate}
\end{enumerate}

Zelig is distributed under the \hlink{GNU General Public License,
  Version 2}{http://www.gnu.org/licenses/gpl.txt}.  After
installation, the source code is located in your R library directory.
If you followed the example above, this is {\tt ~/.R/library/Zelig/}.

\subsubsection{Updating Zelig} \label{sss:unix.updating}

There are two ways to update Zelig.  

\begin{enumerate}

\item We recommend that you start R and, at the R prompt, type:
\begin{verbatim}
> update.packages()
\end{verbatim}
  
\item Alternatively, you may remove an old version by command by
  typing {\tt R CMD REMOVE Zelig} at the terminal prompt.  Then
  download and reinstall the package using the installation
  procedure Section \ref{sss:unix.library} outlined above.

\end{enumerate}

\section{Version Compatability}

In addition to R itself, Zelig also depends on several R packages
maintained by other development teams.  Although we make every effort
to keep the latest version of Zelig up-to-date with the latest version
of those packages, there may occasionally be incompatabilities.  See
\ref{table.compat} in the Appendix for a list of packages tested to be
compatabile with a given Zelig release.  You may obtain older versions
of most packages at \url{http://www.r-project.org}.  

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: t
%%% End: 
