>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

The package handles the pre-processing and normalization of Affymetrix 
GeneChip expression arrays, including Exon arrays. It is an R wrapper
to XPS (eXpression Profiling System), which is based on ROOT, an object-
oriented framework developed at CERN. Thus, the prior installation of
ROOT is a prerequisite for the usage of this package. ROOT can be
downloaded from http://root.cern.ch. 

Copyright (C) 2000-2010 Christian Stratowa, Vienna, Austria

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, a copy of the GNU General Public
License is available at http://www.gnu.org/copyleft/gpl.html. You
can also obtain it by writing to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA.


>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

Content:

I.   Install ROOT:
 Ia.  Install ROOT from source
 Ib.  Install ROOT for Windows
 Ic.  Install ROOT for Mac OS X
 Id.  Notes on  ROOT
II.  Install package 'xps':
 IIa.  Install 'xps' from source
 IIb.  Install 'xps' for Windows
 IIc.  Tested architectures
III. Learning how to use package 'xps'

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

I. Install ROOT:

 Ia.  Install ROOT from source:

   Installation from source is explained extensively on the ROOT website, see:
   http://root.cern.ch/drupal/content/installing-root-source

   1. get the sources of the latest ROOT from:
      http://root.cern.ch/drupal/content/downloading-root

      Note: you can unzip root locally in any directory, resulting in <path>/root

   2. set ROOTSYS to the `root' directory:

            sh family:
              export ROOTSYS=<path>/root
            csh family
              setenv ROOTSYS <path>/root

   3. now type the build commands:

            all shells:
              ./configure --help      [optional]
              ./configure [<arch>]    [e.g. <arch>= linux or macosx]
              make                    [or, make -j2 for dual CPU machines]

   4. add $ROOTSYS/bin to PATH and $ROOTSYS/lib to LD_LIBRARY_PATH:

            sh family: 
              export ROOTSYS=<path>/root
              export PATH=$ROOTSYS/bin:$PATH
              export LD_LIBRARY_PATH=$ROOTSYS/lib:$LD_LIBRARY_PATH
              export DYLD_LIBRARY_PATH=$ROOTSYS/lib:$DYLD_LIBRARY_PATH (MacOS X only)
            csh family:
              setenv ROOTSYS <path>/root
              setenv PATH ${ROOTSYS}/bin:${PATH}
              setenv LD_LIBRARY_PATH ${ROOTSYS}/lib:${LD_LIBRARY_PATH}
              setenv DYLD_LIBRARY_PATH ${ROOTSYS}/lib:${DYLD_LIBRARY_PATH} (MacOS X only)
              rehash

            Note: it is best to include above lines in e.g. ".bashrc" or ".bash_profile"

   5. try running root:

            all shells:
              root


 Ib.  Install ROOT for Windows

   For Windows users it is important to install the recommended binary version
   of ROOT, currently: root_v5.27.04.win32.vc90.msi
   WindowsXP/NT/w2000 with VC++ 9.0, version 5.27/04
   from: http://root.cern.ch/drupal/content/development-version-52704

   It is recommended to install ROOT in the default directory C:\root.
   Furthermore, it is necessary to set the environment variable ROOTSYS:
   under Windows 2000/XP/2003 you can use `System' in the control panel or the
   properties of `My Computer' (under the `Advanced' tab).
   Simply add: ROOTSYS=C:\root\bin 
          (or: ROOTSYS=C:\root      if you add %ROOTSYS%\bin to PATH)


 Ic.  Install ROOT for Mac OS X

   Mac users can either install ROOT from source or use the recommended binary
   version of ROOT, currently: root_v5.27.04.macosx105-i386-gcc-4.0.tar.gz
   This is the binary version for Leopard 32 bit, since the xps binary for
   BioC 2.8 is built for 32 bit (since the 32 bit version of root is installed).
   (For Snow Leopard there exist 32 bit and 64 bit binaries of ROOT.)

   Personally, I am a Mac user and do all my development on my MacBook Pro,
   where I have installed WinXP and openSUSE 11.3 using VMware Fusion in order
   to test xps for these architectures. I prefer to install root from source.


 Id.  Notes on  ROOT:

   Note 1: Alternative ROOT installation
   If you want to install ROOT in a fixed location, not depending on ROOTSYS,
   please see: http://root.cern.ch/drupal/content/installing-root-source

   Note 2: ROOT demos
   Like R, ROOT contains many examples demonstrating the abilities of ROOT.
   These examples can be run to test if ROOT has been installed correctly.
   There are two kind of examples, located in subdirectories tutorials and
   test, respectively:

   1. tutorials:
   To test root and try some of its tutorials, do:
      cd root/tutorials
      root
      root [0] .x demos.C
   For other tutorials, see the README file in the tutorials directory.

   2. tests:
   Examples in the test subdirectory need to be compiled first:
      cd root/test
      make
      root
      root [0] gSystem.Load("Tetris")
      root [1] Tetris t
   For other tests, see the README file in the test directory.
   
   Note 3: Source vs binary
   In principle, it is also possible to download and install binaries
   for some architectures. However, this is not recommended, since the
   sources for package 'xps' depend on the ROOT framework, and need
   to be compiled with the same compiler version as ROOT itself.

   Furthermore, daily versions from ROOT can be downloaded via svn and
   should work fine with 'xps', however, the current versions 5.24/00 and
   5.27/06 have been used to test 'xps' for both Linux openSUSE 11.3 and
   MacOS X and WinXP.

   Note 4: ROOT fails to compile
   Like R, the ROOT framework can be installed on many architectures, see
   the list of supported architectures, when running  "./configure --help".
   However, ROOT may also compile on a number of other architectures. 
   In case, the current official source files "root_v5.27.04.source.tar.gz"
   or "root_v5.24.00.source.tar.gz" fail to compile, you can download the 
   current development version from svn, see:
      http://root.cern.ch/drupal/content/subversion-howto

   If this still fails and you are still interested to compile ROOT, please
   contact the RootTalk forum at: http://root.cern.ch/phpBB3/
   This will help the ROOT developers to eliminate potential problems.
   
   Note 5: Can I use ROOT for other purposes?
   ROOT is a powerful professional C++ framework with many classes,see:
      http://root.cern.ch/drupal/content/users-guide
      http://root.cern.ch/drupal/content/reference-guide

   However, even if you never intend to use any of these classes or not
   even to use C++, but want to develop your own C functions, as many
   R developers do, ROOT may be of interest to you, since by typing "root"
   you start a C/C++ interpreter, which allows you to test your functions
   without the need to compile them first. Simply create a text file, 
   called a macro, containing your C functions.

   As an example create a text file "helloROOT.C" (the '.C' extension is
   important), containing the simple function:

         void hello_root()
         {
            cout << "Hello R, welcome to ROOT!" << endl;
         }

   After starting ROOT, type: ('.L' will load your text file)

         root [0] .L helloROOT.C
         root [1] hello_root()
         Hello R, welcome to ROOT!
         root [2] .q

   When your function works, then you can compile it directly within
   a ROOT session by typing ".L helloROOT.C+". Adding the '+' will
   automatically start the compiler and create a shared library.
   However, in this case you need to include the necessary header
   files first, in this case "#include <iostream>", then start ROOT:

         root [0] .L helloROOT.C+
         Info in <TUnixSystem::ACLiC>: creating shared library /Volumes/CoreData/CRAN/./helloROOT_C.so
         root [1] hello_root()   
         Hello R, welcome to ROOT!
         root [2] .q

   For more information, please contact the ROOT User Guide:
      http://root.cern.ch/drupal/content/users-guide


>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

II.  Install package 'xps':

 IIa.  Install 'xps' from source

   Currently, xps can be downloaded as gezipped source file "xps_1.10.0.tar.gz"
   for MacOS X (Intel and PPC) and for Linux

   It can be installed with:
      R CMD INSTALL xps_1.10.0.tar.gz
   or e.g. on a Mac in the User library:
      R CMD INSTALL -l ~/Library/R/library xps_1.10.0.tar.gz

   However, the recommended way to install packages from source is:
      source("http://bioconductor.org/biocLite.R")
      biocLite("xps", type="source")


 IIb.  Install 'xps' as binary

   Package xps can also be installed as binary for MacOS X and Windows from the 
   Bioconductor website using:
      source("http://bioconductor.org/biocLite.R")
      biocLite("xps")

   Important note: 
   Please note that Bioconductor has built the xps binaries for release BioC 2.8
   using ROOT version root_v5.27.04. Thus it is absolutely essential to install
   this ROOT version first, and not the currently recommended version, otherwise
   calling xps will result in an error message.You can always download any version
   of root from: ftp://root.cern.ch/root


 IIc.  Install 'xps' for Windows

   The Windows binary of xps can be downloaded from the Bioconductor web site, and
   installed using: biocLite("xps")

   If you run xps from Rterm check if `System' in the control panel does contain the 
   following environment variables:
      PATH:   C:\Programs\R\R-2.12.0\bin;%ROOTSYS%\bin;
      ROOTSYS:C:\root

   If you want to install xps from source, then you need to do the following:
   You can still install the binaries for ROOT and R but in addition you need 
   to install the following:
   - Rtools.exe from: http://www.murdoch-sutherland.com/Rtools/
   - Visual C++: you can download the image "VS2008ExpressENUX1397868.iso" for the
     current version "Visual Studio 2008 Express" from the Microsoft web site.

   Before building xps from source you need to start the VC++ batch file provided
   by Microsoft:
      C:\Program Files (x86)\Microsoft Visual Studio 9\VC\vcvarsall.bat (or a similar path).
   Then you can install xps from source as usual:
      R CMD INSTALL xps_1.10.0.tar.gz


 IId.  Tested architectures

   Currently, package 'xps' has been built (with R CMD INSTALL) and
   passed R CMD check with no errors and no warnings on the following computers:
   1. MacBook Pro Core 2 Duo 2GHz with 2 GB RAM running MacOS X 10.6.3 and 10.4.11
      R versions tested: R-2.7.x, R-2.8.x, R-2.9.x, R-2.10.x, R-2.11.x, R-2.12.x
   2. PowerBook Titanium G4 550MHz with 1 GB RAM running MacOS X 10.4.9 and 10.4.11
      R versions tested: R-2.5.0, R-2.6.0, R-2.8.0
   3. HP Compaq nx6110 Intel Centrino 1.4 GHz with 512 MB RAM with Fedora Core 4
      R versions tested: R-2.4.1, R-2.6.0, R-2.7.0, R-2.7.1
   4. HP Compaq nx6110 Intel Centrino 1.4 GHz with 512 MB RAM with Windows XP
      R versions tested: R-2.6.2, R-2.7.0, R-2.7.1
   5. VMware Fusion on MacBook Pro running Windows XP or openSUSE 11.3
      R versions tested: R-2.9.x, R-2.10.x, R-2.11.x, R-2.12.x
      

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

III. Learning how to use package 'xps'

   The best way to learn how to use package 'xps' is to follow the examples
   in the enclosed vignette "An Introduction to the xps Package".

   As next step it is recommeded to follow the step-by-step examples in the
   script "script4xps.R", which is available in the "examples" subdirectory of
   'xps'. Directory xps/raw contains four CEL-files for chip Test3.CDF, which
   are used in most of the examples. However, real world examples in this script
   include a subset of the Affymetrix Exon Array Dataset human Tissues for  
   HG-U133_Plus_2 arrays, HuEx-1_0-st-v2 arrays and HuGene-1_0-st-v1 arrays.
   The corresponding CEL-files must be downloaded from the Affymetrix web site.

   The use of Affymetrix human Tissues dataset is also explained in more detail
   in the example script "script4exon.R".

   Comments regarding the tested architectures:
   1. MacBook Pro Intel Core 2 Duo 2GHz with 2 GB RAM running MacOS X 10.4.11
      All examples were tested, including the Affymetrix human mixture
      dataset for HG-U133_Plus_2, HuGene-1_0-st-v1 AND HuEx-1_0-st-v2.r2

   2. PowerBook Titanium PowerPC G4 550MHz with 1 GB RAM running MacOS X 10.4.9
      Most examples were tested, including the Affymetrix human mixture
      dataset for HG-U133_Plus_2 (HuEx-1_0-st-v2.r2 should also run, as
      I have tested them earlier, but they are very slow on G4 550 MHz)

   3. HP Compaq nx6110 Intel Centrino 1.4 GHz with 512 MB RAM with Fedora Core 4
      All examples were tested, including the Affymetrix human mixture
      dataset for HG-U133_Plus_2  but NOT HuEx-1_0-st-v2.r2.

   4. HP Compaq nx6110 Intel Centrino 1.4 GHz with 512 MB RAM with Windows XP
      Most examples were tested, including the Affymetrix human mixture
      dataset for HG-U133_Plus_2,  HuGene-1_0-st-v1 AND HuEx-1_0-st-v2.r2.
      Note: I could indeed run RMA using 6 exon arrays of the Affmetrix dataset
            with only 512 MB of RAM. However, it may not be possible to run MAS5,
            since the MAS5 background correction uses lots of RAM.
            Furthermore, it was not possible to create the scheme for the exon
            arrays with "import.exon.scheme()", since the Affymetrix files are
            too large; you need at least 1GB RAM.


>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>


