source: extensions/net.sf.basedb.genepattern/trunk/README @ 1138

== Requirements ==

 1. BASE 2.13 or later.
 2. Ant 1.7 or later (for installation only).
 3. Access to a GenePattern server (3.2 or higher recommended).
 
== Introduction ==

This package is an extensions/plug-in package to BASE that integrates BASE
with GenePattern. Some of the features:

 * Export experimental data in various GenePattern file formats.
 * Run jobs on a GenePattern server using files from BASE. Module
   parameters are entered in the BASE web interface.
 * Start GenePattern visualizer modules with files from BASE.

This extension doesn't include any GenePattern software. It uses
web services to communicate with GenePattern servers. BASE users
that want to use GenePattern must have an account on a separate 
GenePattern server.

For more information:

 * The homepage for this extension: 
   http://baseplugins.thep.lu.se/wiki/net.sf.basedb.genepattern
 * The GenePattern homepage: 
   http://www.broad.mit.edu/cancer/software/genepattern/index.html

== Installation ==

 1. Download the gp-integration-*.tar.gz file.
 2. Unpack the downloaded file to a directory of your choice.
 3. Download GenePattern files from a GenePattern server.
    Type `ant -f download.xml`. This will dowload the files from the public
    GenePattern server at http://genepattern.broad.mit.edu/gp. You may
    download from an alternate location by setting the `genepattern.url`
    property: `ant -f download.xml -Dgenepattern.url=http://your.genepattern.server/gp`
    This will download the following files.
     * runVisualizer.jar: This file is added to gp-integration.jar/resources/visualizer
     * GenePattern.zip: The `GenePattern.jar` and `lib/gp-modules.jar` are extracted
       to the `lib/genepattern` directory.
 4. Copy the `gp-integration.jar` file and the `lib` directory, including sub-
    directories and files, to your BASE extensions directory, `WEB-INF/extensions`.
 5. Run the 'Extensions -> Manual scan' command if you have disabled automatic
    installation. Otherwise, just wait a bit and the automatic installation will
    find and install the new extension.
 6. Run the plug-in installation wizard by clicking the 'New' button on the
    'Administrate -> Plugins -> Definitions' page. Make sure the option for
    the 'Extensions directory' is selected. Install all plug-ins found in 
    the gp-integration.jar file.
 7. Done. 

== Using ==

'''Register GenePattern account with BASE'''[[br]]
BASE users that want's to use this extensions must have access to at
least one GenePattern server. The first step is to register the account
information with BASE. Go to `Extensions -> GenePattern options`. Add
information for one or more GenePattern servers. For each server the
following information should be provided:

 * Server url: Only include the root url (not the /gp)
 * Login: Your login information (email)
 * Password: If the server requires a password
 * BASE server URL: The URL to BASE as seen from the GenePattern server.
   The default value is usually correct, but may need to be changed due
   to, for example, proxies.

Use the `Test` button to verify the login information. If there is problem with
transfering files to the GenePattern server an incorrect value for the BASE server 
URL is most likely the cause.

'''Configuring the GenePattern analysis plug-in'''[[br]]
Before it is possible to run jobs on a GenePattern server the `GenePattern analysis`
plug-in must be configured. Each GenePattern module requires a separate configuration.
Go to the `Administrate -> Plugins -> Definitions` page and find the 
`GenePattern analysis` plug-in. Create a new configuration and start the 
configuration sequence.

 1. In the first step you select a GenePattern server and a module. Use the
    `Get list` button to retrieve a list of installed modules on the selected
    GenePattern server. Note! The selected GenePattern server is used only 
    during configuration. Users may select a different server (as long as
    the module is installed there) for executing jobs.
 2. In the second step you can set default values for all non-file parameters
    and link file parameters with BASE file types. The linking to file types 
    makes it possible for BASE to suggest a default file that is already
    associated with the bioassay set.

'''Using the GenePattern analysis plug-in'''[[br]]
To run a job on a GenePattern server the `GenePattern analysis` plug-in is
used from the bioassay set view. 

 1. In the first step some information about the new child bioassay set can
    be entered. The user must also select a GenePattern server and specify
    a directory in the BASE file system were the result files should be
    saved.
 2. In the second step input files and other parameter values are entered.

To run a visualizer module, use the `GenePattern visualizer` button
from the bioassay set view.

 1. In the first step you select a GenePattern server and a module. Use the 
    `Get list` button to retreive a list of installed modules on the selected
    GenePattern server.
 2. In the second step input files and other parameter values are entered.
 3. After this, the visualizer applet is started. This applet is just a wrapper
    that downloads the required module and the data files to the local computer 
    and starts a Java program. Please be patient as this may take some while.

== Known issues ==

None.

== Compiling ==

To compile this package you also need:
 
 1. Ant 1.7
 2. Java 1.6

Follow these instructions:

 1. Download the source code from the subversion repository. See
    http://baseplugins.thep.lu.se/wiki/net.sf.basedb.genepattern
    for instructions.
 
 2. Type `ant download-lib` to automatically download the BASE and GenePattern 
    files that are needed for compilation. 

 3. Type 'ant' to compile the code and generate the 'gp-integration.jar' file
    in the project directory.

 4. Use 'ant package' to create a downloadable tar.gz package. Note that this
    package doesn't include any of the GenePattern files.
 
Tip: If you need different values for any of the properties defined in
the 'build.xml' file, create a file named 'build.properties' and set
the values there.