source: trunk/se/lu/thep/affymetrix/INSTALL @ 337

$Id: INSTALL 295 2007-05-23 12:40:10Z jari $

----------------------------------------------------------------------
{{{
Copyright (C) 2006 Jari Häkkinen
Copyright (C) 2007 Jari Häkkinen, Peter Johansson

This file is part of se.lu.thep.affymetrix package for BASE,
http://baseplugins.thep.lu.se/wiki/se.thep.lu.se.affymetrix

se.lu.thep.affymetrix package for BASE 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.

se.lu.thep.affymetrix package for BASE 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, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
USA.
}}}
----------------------------------------------------------------------


= Installation Guide for se.lu.thep.affymetrix =

This file contains installation information for two plug-ins: RMAExpress
and Plier.

== 0. Introduction ==

=== Short intro: ===

The route for successful first time installation of this RMAExpress plug-in is
  i. Install the plug-in.
  i. Install wxWidgets.
  i. Install RMAExpressConsole.
  i. Make BASE aware of the new plug-in.

The route for successful first time installation of this Plier plug-in is
  i. Install the plug-in.
  i. Install apt-probeset-summarize.
  i. Make BASE aware of the new plug-in.

Upgrading the plug-in is even easier, see item 5) below.

=== Longer intro: ===

There are two supported ways to install this Affymetrix package, you
either download a pre-compiled package or you checkout the latest
source from the subversion repository. The below instructions covers
both installation options since major parts of the installation is the
same for the different cases. There is also a source package available
for download but installation from that package is currently not
supported, it is supplied for reference only.

Note, the underlying algorithms RMA and Plier are not part of this
package. This package contains the plug-in code needed for hooking up
RMAExpress and Plier to BASE as a plug-in. The underlying binaries,
RMAExpress and Plier, must be installed for the corresponding plug-in
to work. See more in item 1.ii below.

Users who prefer the install from pre-compiled packages must go
through all items below except 1.iii) and 2.iv).

Users who prefer the live on bleeding edge software and compiles the
source from the subversion repository must go through all items except
3.v).

If you are upgrading a previously installed RMAExpress or Plier
plug-in for BASE you can safely skip to item 5) below.


== 1. Pre-requisites ==

=== BASE 2 ===
This plug-in package will only work with BASE 2.0 or later, i.e. BASE
1.2.x is not (and will never be) supported.

=== RMAExpressConsole and apt-probeset-summarize === 

''RMAExpressConsole''

Pre-requisite for RMAExpress plug-in (both binary package and
subversion tree installs) is that RMAExpressConsole is installed.

RMAExpressConsole is available in the RMAExpress package written by
Ben Bolstad, and the official RMAExpress web site is
http://rmaexpress.bmbolstad.com/

You must download and compile RMAExpressConsole. This requires that
wxWidgets (a.k.a. wxWindows) is installed on your system. wxWidgets is
found at http://www.wxwidgets.org. The compilation of
RMAExpressConsole is straightforward (at least on OpenSuSE 10.0 and
10.2, and
MacOSX 10.4.9). Download the source for v1.0beta1 and unpack the tar
file. Unfortunately the source will not work out of the box in some
operating systems. You have to add
{{{
#include <cmath>
}}}
to `RawDataVisualize.cpp` before issuing 'make'. After this patch
RMAExpressConsole will be compiled (together with some other binaries
which are of no interest here.

''apt-probeset-summarize''

Pre-requisite for Plier plug-in (both binary package and
subversion tree installs) is that apt-probeset_summarize is installed.

apt-probeset-summarize is available in the Affymetrix Power Tools
(APT) package available through Affymetrix home page
http://www.affymetrix.com/support/developer/powertools/index.affx

APT is available as a Windows installer package and pre-built binaries
for Linux and Mac OS-X. If you prefer building yourself, the source
code is available as well. Though, it should be noted, we have
experienced some problems building APT and at the time being we have
not succeeded.

''Installation of binaries''

You should install the binaries (RMAExpressConsole and
apt-probeset-summarize) such that they are readable for the user running
your BASE application server. The name of the binaries MUST be
`RMAExpressConsole` and `apt-probeset-summarize`, respectively. Also
binaries must be copied into the same directory as the plug-in (see
item 3.v below). These two conditions are hard coded in the plug-ins.

Install of the BASE plug-in will succeed even if this requisite is not
fulfilled, but execution of the plug-in within BASE will fail.

=== Compile time access to BASE core jar file. ===

This is only needed for compilation and installation from a subversion
tree, i.e., it is not needed when installing a pre-compiled package. 

The BASE2Core.jar (from BASE 2.0 and later) file in use by the server
running the BASE web application must be available when compiling
se.lu.thep.affymetrix.jar.

== 2. Compilation and installation from a subversion tree ==

You should skip this section if you downloaded a pre-compiled package.

iv) When installing from a subversion working copy you must compile
the plug-in, do

  `make`

This assumes that BASE is installed in `/usr/local/base`. If this is not
the case do

  `make BASEROOT=<base-dir>`

where `<base-dir>` is to be replaced with the path to BASE. When the
compilation finishes you install the plug-in into the BASE application
server file system with

  `make install`    or    `make BASEROOT=<base-dir> install`

The plug-in will install in the recommended directory
`<base-dir>/www/plugins/se/lu/thep/affymetrix`, i.e., if you prefer
another location please refer to the Makefile (which supports further
options).

For advanced users only: `<base-dir>` can really be any directory
readable for the user running your tomcat server. This may be handy if
you run several servers on one machine but only want one common
directory hierarchy for the plug-ins. Or, if you update the BASE
application frequently and in the process create new directories for
the newer application. More information about this is available in the
Makefile.

Remember the plug-in location for configuration of BASE below.


== 3. Installation from a pre-compiled package ==

You should skip this section if you use the subversion repository.

v) Install the plug-in in the BASE application server file system. If
BASE is installed in `/usr/local/base` simply do

  `make install-precompiled`

If BASE is installed elsewhere, do

  `make BASEROOT=<base-dir> install-precompiled`

where `<base-dir>` is to be replaced by the path to BASE. The plug-in
will install in the recommended directory
`<base-dir>/www/plugins/se/lu/thep/affymetrix`, i.e., if you prefer
another location please refer to the Makefile (which supports further
options).

For advanced users only: `<base-dir>` can really be any directory
readable for the user running your tomcat server. This may be handy if
you run several servers on one machine but only want one common
directory hierarchy for the plug-ins. Or, if you update the BASE
application frequently and in the process create new directories for
the newer application. More information about this is available in the
Makefile.

Remember the plug-in location for configuration of BASE below.


== 4. BASE configuration ==

=== vi) Make BASE aware of the new plug-ins ===

You need to perform the below steps for both plug-ins in this
package. Currently there is no way to install all plug-ins in one
package.

 * Log in to BASE with plug-in administrative privileges.

 * Choose 'Administrate' -> 'Plugins' -> 'Definitions'.

 * Click on 'New...'. This will open up the 'Create plugin' pop-up
   window. Type `se.lu.thep.affymetrix.RMAExpress` in the 'Class'
   field and
   `/path/to/base/www/plugins/se/lu/thep/affymetrix/affymetrix.jar" in
   the 'Path' field. Obviously, if you have chosen another location
   for the jar above you should adapt to that. Click on the 'Save'
   button.

 * Share the plug-in to all users/roles/groups that should have access
   to it (sharing it to group 'Everyone' should be sufficient in most
   cases).

 * Redo the third and fourth step above for Plier where you use
   `se.lu.thep.affymetrix.Plier` in the class field.

 * That's it, now you need to BASE skills to actually make use of the
   plug-in.

== 5. Updating a plug-in in BASE. ==

You may update the underlying binaries (RMAExpress or
apt-probeset-summarize) or the plug-in.

=== Updating RMAExpressConsole or apt-probeset-summarize ===

Installing a new binary is trivial, just replace the old binary with
the new binary. However, make sure that the input and output formats
has not changed.

=== Update RMAExpress or Plier plug-ins for BASE ===

This is straightforward:

   - Replace the old jar-file and

   - Log in to BASE with plug-in administrative privileges.

   - Choose 'Administrate' -> 'Plugins' -> 'Definitions'.

   - Locate the plug-in (RMAExpress or Plier) in the list and click on it.

   - Click on the 'Unload' button if it is available. This will
     remove the old plug-in from the application.

   - Click on 'Edit...'. This will open up the 'Edit plugin'
     pop-up window. No parameter changes are need, just click on
     the 'Save' button.

   - Done.