Project Site
============
http://sourceforge.net/projects/shap/
SHAP Basic-System Quick Start
=============================
The SHAP basic-system is completely self-contained and intended to get SHAP up and running quickly and easily. Our intention is that end-users can assess the utility of the software without a minimum of trouble. To make that possible, the database provider and web server have been embedded within the application itself. End users should be able to run SHAP with little to no configuration changes.
As an alternative, SHAP can also be tested using our configured Amazon Machine Imagine on EC2. Please consult our Sourceforge project for further details.
In providing this basic system, we have made choices to keep the configuration simple. In the long run not all of these choices may be suitable for your day-to-day system. The installation includes the external tools: blastall, hmmpfam, aragorn and metagene, sufficient to get a sense of using SHAP for your work.
It is important to note that the version of hmmpfam supplied has been specially modified to write XML output. It has therefore been renamed hmmpfam_xml to avoid the possibility of clashing with a preexisting vanilla installation of HMMER.
Blastall, aragorn and metagene are standard vanilla binaries and could be replaced with those you might already have installed on your system.
You could also extend the supplied analyzer configuration to make use of larger reference databases (Refseq, NR, TIGRFAM, etc) than we have included for testing purposes.
Though we have configured the system for single-threaded analysis, the embedded system still supports the concurrent model and therefore it is possible to make use of as multiple CPU cores. However, running multiple simultaneous at the command line should be avoided as it may lead to database access violations.
Please refer to the full documentation on the SourceForge project page if you wish to make a complete installation and tailor it to your system.
Step 1: Shell environment setup
===============================
The basic installation of SHAP uses some environmental variables to setup paths to the included executables and reference databases.
To make this easy and quick, end-users should only need to run the Bash script shap-settings.sh to configure the system.
In a Bash shell execute,
. shap-settings.sh
This can also be placed in your bashrc or bash_profile.
## NOTE ##
You must set the SHAP_HOME variable within this script before it can be successfully executed.
Set the SHAP_HOME environment variable
--------------------------------------
Assuming you extracted the shap-basic tarball to your home directory. Then SHAP_HOME would be set to the following.
export SHAP_HOME=${HOME}/shap-basic
Step 2: Initialization and analysis
===================================
Initialize a basic analyzer setup
---------------------------------
Run configSetup.sh, answering "yes" to both questions.
configSetup.sh basic-config.xml
Populate the database with an example dataset
---------------------------------------------
./populate.sh
This script creates a project and sample and a single-genome sized metagenomic example dataset.
Analyze the example dataset
---------------------------
Run feature detection on the example dataset as follows
jobControl --submit plans/gsb-detect.xml
Once this has completed, you should now run the annotation. This will take longer as the basic system has not been configured to make use of concurrency. It is possible to enable concurrency in shap.properties if you wish.
jobControl --submit plans/gsb-annotate.xml
When complete, you may view the results either with the web application described below or your favourite SQL database client. The URI is "jdbc:derby:shapdb".
Step 3: Using the Web Application
=================================
Indexing
--------
The web application makes use of Apache Lucene for search capability. Lucene in turn makes use of an index, which is stored on the filesystem. For shap-basic, the index is stored within the application directory. Make sure this path is writeable by whoever
wishes to create the index.
At present, the index must be manually updated when new data has been added analyzed. This mass indexing is performed using the index.sh command. Answer yes to reindexing.
index.sh
Starting the local web application
----------------------------------
The embedded web application can be started as follows,
web-server.sh
Once start-up is complete, users can access the analysis results with their prefered web-browser.
By default, the URL is,
http://localhost:8090/shap
Only a superuser 'admin' exists to begin with, password 'shap01'. Web application only provides read access to data, but it is good practice to use non-privileged users for regular access.
Done!
=====
Please refer to the complete documentation and the project website for more information.
Matthew DeMaere
matt.demaere@gmail.com
