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

$Id: INSTALL 345 2007-06-27 19:47:01Z 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.

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.

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

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

Specifically, the BASE2Core.jar file in use by the server running the
BASE web application must be available at compile/install time.


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

''RMAExpressConsole''

Pre-requisite for RMAExpress plug-in (both binary package and
subversion tree installs) to work 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/

(Microsoft Windows instructions) RMAExpressConsole is a part of the
Microsoft Windows pre-built binary package available from the
RMAExpress web site. Install the package and locate the
RMAExpressConsole.exe, wxbase26_gcc_custom.dll, and
wxmsw26_core_gcc_custom.dll files (these will be copied to the plug-in
location later).

(Linux and MacOSX instructions) 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) to work 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 external binaries''

You should install the external binaries, RMAExpressConsole (with the
DLLs in case of Microsoft Windows install) 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 2 or 3 below
depending on whether you perform a pre-compiled or source package
installation). These two conditions are hard coded in the plug-ins.

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


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

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

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 or a
source package.

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 ==

=== 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.