Motif Tool Manager

This section will walk you through the steps necessary to install the motif analysis system. Once this installation is complete users will be able to define motif finding jobs, run them through the request queue, and then compare the output graphically with the motifCompare nodes. We have packaged the entire system, so that you only have to extract a tarball and change a couple of settings.

Prerequisites

• Download the code motifAnalysis_1.2.tar.gz. Once you unzip it, you will find the companion database to be installed.
• Motif Finding programs must be installed separately and the paths must be known (DME, MDScan, AlignACE, Bioprospector, MEME, MotifSampler). All of these programs are free for education/research purposes, but some might require you to obtain a license to run on your site. Please do so. These programs are configured to work on our Debian server. We suggest that you install and configure each of these programs to ensure that each runs on your Linux server.
• Any requirements needed to use WebLogo (http://weblogo.berkeley.edu/).
• A Linux based server running Apache, PHP, MySQL. The code that runs background processes is unique to Linux.
• wget (http://www.gnu.org/software/wget/) is used to run programs in the background and must be installed. This is a pretty standard program on most linux-based systems.

Steps to follow for complete system installation

1. Obtain the code and untarball it into the directory that will serve as the web root for Drupal
   Untar instruction: tar zxpvf motifAnalsyis_1.x.tar.gz
2. Update Settings
   In the file sites/default/settings.php, you will need to tell the system your username and password for the database yo u will use. On line 94, you will see something like this
$db_url = 'mysql://username:password@localhost/databaseName';
. Update the username, password, and databaseName to reflect your setup.

   In the file motifCron.php, you need to replace "YourWebRoot" with the appropriate URL that directs to your website.

3. Import the default system
   The default database is located in the root directory, motifAnalysis_1.x.sql. It should be loaded into mysql using the appropriate information (username/password): mysql -u mysql_user -p mysql_database < motifAnalysis_1.x.sql.

   It is important to note that this is a complete installation, so this should be done with an empty database.

4. You should immediately change the email/password for users admin and demo. The default admin username is admin with default password 123456. Also, go to ?q=admin/settings/site-information and configure the appropriate information for your site.
5. Make sure storage directories are writable

These directories are used by the system: files, imgTmp and tmp. They must be writable by apache. The -p option used to untar the files previously, should preserve the permissions. The default permission states that the directories are writable by everyone, so Apache will be assured to write to these directories. This is rather insecure, so you might want to check with your system administrator to verify if this is ok to do.

6. Setup the motif finding programs
   The system expects for the motif finding programs to all be located in the directory motifPrograms. By default, our package includes the following popular motif finding programs:

   
motifPrograms/AlignAce
motifPrograms/bioprospector
motifPrograms/DME
motifPrograms/MDScan
motifPrograms/MEME
motifPrograms/MotifSampler

   It is a good idea to ensure that these programs can be run on your server. If not, you need to recompile these programs, in which case please maintain the same file structure as above. These programs are all free for educational purposes, but you might need to obtain licenses to run them.

   note: MEME is a directory containing all of the MEME files. It is not simply a binary, but depends on a number of things, so the entire directory should be in motifPrograms. Same is true for MotifSampler. You might want to look into the file sites/all/modules/motif/motifPrograms.inc to see how the paths to these programs are configured.

   If you decide that you would rather change the references to the programs in the code, check out step 4 in the module install tutorial below.

7. Try the included example
   Click on the Request Queue and you should find several jobs that have been processed (one for each motif finding program). You can either create a motif comparison by checking the checkboxes and clicking submit, or you can click Motif Comparisons in the left navigation and select the ready made comparison.

That's it.

Install the modules using a current Drupal system (choose this installation only you are confident with configuring Drupal).

1. Obtain an install file and untarball the files into the Drupal root directory
   You will need the file with a name like motifAnalysis_1.x_module.tar.gz
   untarball the file:
   
gzip -d motifAnalysis_1.x_module.tar.gz
tar -xvf motifAnalysis_1.x_module.tar


   Files and Directories created:
   
_motifCron.php motifCron.php loading.gif MOTIFINSTALL.txt
weblogo/*
sites/all/modules/motifcompare/*
sites/all/modules/motif/*
cckExport/*
motifPrograms/*


2. Tell the system where your website is
   In the file 'motifCron.php' the path needs to be changed to reflect your setup. It should point to _motifCron.php
   through a URL.
3. Create directories for storage

   imgTmp -- used to store the weblogo images
   This directory must be writable by apache, as apache will be executing the programs
   that create the weblogos.
   ** Note: If this directory is not in the Drupal web root, then a global variable must be changed
   as described in step 4.

   tmp -- used to store session files. Also must be writable by Apache.

4. Specify locations of motif-finding software.
   The system is setup by default to look for the motif finding programs in the directory motifPrograms from the Drupal installation root. The easiest way to complete this step is to simple move or copy the programs to a directory of the same name. The files expected are:
   
motifPrograms/AlignAce
motifPrograms/bioprospector
motifPrograms/dme
motifPrograms/MDscan
motifPrograms/meme
motifPrograms/MotifSampler

   note: meme is a directory containing all of the meme files. It is not simply a binary, but depends on a number of things, so the entire directory should be in motifPrograms

   If you cannot put the program files in motifPrograms, then some variables need to be changed within the code. The file 'sites/all/modules/motif/motifPrograms.inc' contains a block at the top where global variables are set.
   The location of the motif finding programs as well as temporary storage directories and the directory for storage
   of the weblogo images MUST be configured. The .inc file has more comments on the specifics.

5. Create content types with cck exports

   CCK should be installed and directions on how to do that can be found here (http://drupal.org/project/cck).
   FileField should be installed and directions on how to do that can be found here (http://drupal.org/project/filefield).

   The content types can be imported by going to Administer->Content Types->Import. The content of each file in cckExport
   should be copied and pasted, separately, into the textarea on the import screen.

6. Enable both the motifcompare and motif modules

   This can be done through Administer->Modules

7. Test Your Install

   The instalation can be tested by defining jobs and running them via the request queue, then comparing them by creating motifcompare nodes.

   If jobs are not in the request queue, verify that the motif_queue mysql table was created.

   If jobs are showing up in the queue but are not executing, verify that motifCron.php has the correct path in the wget statement.

   If jobs show error status, make sure that the paths set in 'sites/all/motif/motifPrograms.inc' correctly point to their respective programs.

   If the jobs execute and the motifcompare nodes do not show any images, check your imgTmp directory to make sure they were generated.
   The naming convention is 'weblogo_nodeId_*' where nodeId is the id of the node they should be created for and *
   is a number from 0-M. M is the number of motifs minus 1. If the output from the programs is received correctly and stored in the database,
   then there is a problem with the weblogo stuff. Make sure the path to the weblogo/createLogos.cgi program is configured in 'sites/all/motif/motifPrograms.inc'