Wwwblast

A wwwblast installation allows a researcher to use BLAST to search a sequence database using a graphical user interface. There are several differences when compared to using BLAST from the command line (as is described in Wikiomics:BLAST_tutorial for instance):
 * After setup, researchers use the program by accessing a web page, not using the command line. This can make it more suitable for computer-shy biologists.
 * The output includes a diagrammatic overview of the BLAST hits' coverage of the query sequence, whereas command line BLAST does not generate this.
 * It is more difficult to use when dealing with large numbers of sequences, and is not amenable to parsing using a BioPerl parser, for instance.

=Setting up a wwwblast server with the Apache web server=

Install the pre-requisites
wwwblast requires csh and apache to be installed. On OSX, these are installed by default. It can be setup on windows computers, but that is not dealt with here.

Download and extract
Download the wwwblast program from the NCBI FTP site.

Extract the contents of the downloaded archive into the default apache directory (the DocumentRoot, in apache parlance): You can extract using a graphical user interface, but also on the command line. For instance, on Linux, $ cd /var/www $ sudo tar xzf /home/ben/Downloads/wwwblast-2.2.24-ia32-linux.tar.gz Afterwards, the folder /Users/ /Sites/blast should exist (or the equivalent on other operating systems). Technically there is no reason it cannot be in any directory in the DocumentRoot e.g. /Users/ben/Sites/myblasts/blast, but the simplest directory is assumed in this howto. For the rest of the tutorial the directory /User/ben/Sites/blast is assumed to be base directory of the blast installation, and 'ben' is assumed to be the user logged into the computer.
 * On OSX, this site is /Users/ben/Sites (replacing ben with your login name)
 * On Ubuntu and other linux distributions, use /var/www

Turning on the webserver
Enabling the Apache web server is different on different platforms. On OSX, enable the personal web sites option (System Preferences - Network/Sharing - Personal Web Sharing). On Ubuntu, install the apache2 package.

When this step is correctly carried out, the webpage http://localhost should work.

Modifying the apache configuration file
Add the following text entry to the apache config file. You will need administrator privileges. AddHandler cgi-script .cgi  Options FollowSymLinks +ExecCGI +Indexes  After saving the file, restart the apache webserver. The simplest way is to restart the computer. If restarting the computer is not possible you can restart the server using apache2ctl, with administrator privileges: $ sudo apache2ctl graceful
 * On OSX (only older versions?) this file is /etc/httpd/users/ben.conf
 * On Ubuntu and some other Linux distributions, create a new file /etc/apache2/conf.d/blast.conf
 * 1) Added below to get wwwblast to work

After restarting, you should be able to run a blast against the default test databases. You can use the sequence TACTGTTATCGATCCGGTCGAAAAACTGCTGGCAGTGGGGCATTACCTCGAATCTACCGTCGATATTGCT to test, against test_na_db using blastn. You should get a hit, not a half-blank page.
 * On OSX, the URL will be http://localhost/~ben/blast/blast.html.
 * On Linux, the URL will be http://localhost/blast/blast.html.

Getting the BLAST overview image to work
If there is no image showing how the blast sequence worked, and instead in its place was the an error message similar to below though with the numbers being different: fail to open file TmpGifs/1804289383790.gif

This can be fixed by giving every user on the computer write access to the TmpGifs folder. In a terminal (on Linux, need administrator privileges): $ chmod o+w /Users/ben/Sites/blast/TmpGifs/ There should be no output from this command. If the permissions have been changed correctly, the overview image should work.

Creating custom databases
By default, wwwblast only comes with a few databases that are generally not useful. Instead the researcher wants to BLAST against sequences generated in their own lab, for instance. To make a custom sequence database from a FASTA file, 3 steps are required: converting the fasta file into a binary blast database, changing the blast.html so that the database can be selected from the drop-down menu, and modifying blast.rc.

Converting a fasta file into a binary BLAST database
A binary BLAST database is a collection of multiple files (.nhr, .nin and .nsq files for nucleotide databases). They must be created from a fasta file in a terminal, using the BLAST+ toolkit, available from NCBI (PubMed citation). The legacy BLAST toolkit can be used to achieve the same goal, though the command line syntax differs.

NOTE: If you are planning on using Blast_link, follow the instructions on that wiki page for this section, as it differs slightly.

After copying the fasta file (called for example 'my_nucleotide_sequences.fasta') to the db directory of the wwwblast installation (e.g. /Users/ben/Sites/blast/db), enter the following in a terminal: $ cd /Users/ben/Sites/blast/db $ makeblastdb -in my_nucleotide_sequences.fasta -dbtype nucl Building a new DB, current time: 09/23/2010 14:12:18 New DB name:  my_nucleotide_sequences.fasta New DB title: my_nucleotide_sequences.fasta Sequence type: Nucleotide Keep Linkouts: T Keep MBits: T Maximum file size: 1073741824B Adding sequences from FASTA; added 1620 sequences in 0.207906 seconds. For amino acid sequence fasta files, use '-dbtype prot' instead of '-dbtype nucl'

Adding the custom database to the drop-down box
To search against a custom database, it must be able to be selected from the drop-down box in blast.html. To add a database to the drop-down box, modify blast.html in a text editor, such as TextWrangler on OSX, notepad on windows, or gedit on linux. An example:   My nucleotide sequences  test_na_db  test_aa_db After the HTML has been modified correctly, the custom database should be able to be found when viewing the blast page with an internet browser, for example at http://localhost/blast/blast.html.

Modifying blast.rc
Without modifying the blast.rc file correctly for a given database, the following error will appear when a blast is run: Error 9 in submitting BLAST query Short error description:

The combination of database and program, that you provided in your message is invalid or not acceptable by BLAST search system. Please look at current possible combinations in BLAST help. To fix it, change the blast.rc file, which is in the blast folder to something akin to below: blastn test_na_db my_nucleotide_sequences.fasta blastp test_aa_db blastx test_aa_db tblastn test_na_db my_nucleotide_sequences.fasta tblastx test_na_db my_nucleotide_sequences.fasta As many databases can be added space separated as required after each program.

After completing this step, you should be able to run your blast from http://localhost/blast/blast.html. It is a good idea to run a positive control. Take a section of sequence from the fasta file of the database you are blasting against, and query the database with it. A positive control is a good idea because wwwblast reporting "no hits found" can be misleading - see the troublshooting section.

=Troubleshooting=

Cannot find makeblastdb
Specify the full path to the makeblastdb executable. TODO.

No hits found
Somewhat misleadingly, if the binary databases are not in the correct place, but blast.rc is specified correctly, then wwwblast will not warn of this directly. Instead, it will display "***** no hits found *****" but not complete the web page by adding database statistics. If there really are no hits found, the statistics about the database will be displayed below. See the two contrasting pictures to the right of this text.

Internal Server Error
If a webpage is encountered that says "Internal Server Error", something has gone wrong while the webserver was running wwwblast. To find out more about this error, look at the end of the apache error log. The error log is a file, which might be /var/log/httpd/error_log or /var/log/apache2/error.log.

Exec of blast.cgi failed
If you end up with an error like this: No such file or directory: exec of ‘/var/www/blast/blast.cgi’ failed, referer: http://localhost/blast/blast.html This might be because:
 * 1) csh is not installed. This is unlikely to be the case on OSX because csh comes installed by default
 * 2) blast.cgi does not have execute permissions.

=Missing Features of WWW-BLAST= Even when properly setup, the default installation of wwwblast has some missing features;
 * No access to the entire hit sequence. When the query sequence has a hit against the database, there is no way to retrieve the entire hit sequence for further analysis. This may be fixed by installing the blast_link add-on.
 * No security. By the methods shown above, the sequences in the database are accessible to everyone on the internet. A username and password system may be added by configuring apache basic authentication.
 * No dead-easy installer. If you've followed the above tutorial, you'll realise that installation of www-blast is more complicated than installing the average program. Sorry about this one folks, but there's no known fix.
 * Cannot search multiple databases simultaneously. The database selection is a drop-down box, not a list of checkboxes. So only one database can be searched at a time.

=See also=
 * BLAST - the underlying algorithm that wwwblast uses
 * Blast_link - an extension of wwwblast that allows access to the full sequences of the hits
 * apache basic authentication - a way to password-protect the wwwblast webpage

=Free alternatives=
 * SequenceServer A BLAST server that is probably easier to setup than wwwblast, but is still in development.

=Acknowledgements= Creation of this wiki page was funded by the Molecular Geo- and Palaeobiology Lab of the Ludwig-Maximilians-Universität (LMU).