TwinBLAST

View two BLAST reports at once

Download .zip Download .tar.gz Download .vdi View on GitHub

TwinBLAST - View two BLAST reports at once

TwinBLAST is a web-based tool for viewing 2 BLAST reports simultaneously side-by-side. It uses ExtJS (www.sencha.com/products/extjs/) to provide 2 independantly scrollable panels. BioPerl (www.bioperl.org) is used to index raw BLAST reports and Bio::Graphics is used to draw pictograms of the BLAST hits.

Try out a demo page at www.lgt.igs.umaryland.edu/twinblast. This page has a dataset of Drosophila mauritiana lateral gene transfers loaded into it. Those results are also available for download

TwinBLAST uses HTML and Javascript and should work in all modern web-browsers.

Instructions for the TwinBLAST Virtual Machine (VM)

  1. Download the VM containing TwinBLAST and all of its dependencies using the link towards the top of this page.
  2. Download and install VirtualBox if you do not already have it using this link
  3. Launch VirtualBox Manager and follow these steps:

    1. Select "New" in the top left
    2. Specify a name for the machine
    3. Type: Linux
    4. Version: Ubuntu (64-bit)
    5. Click "Continue"
    6. Select 2048 MB for memory size
    7. Click "Continue"
    8. Select "Use an existing virtual hard disk file" (choose the VDI downloaded in step 1)
    9. Click "Create"
    10. Double click the machine designated by the name from step 3.2 to start the new VM
    11. PLEASE NOTE: from this point forward, all steps will take place within the VM that was just booted, not in the host machine

  4. Navigate to TwinBLAST using Firefox and the URL: localhost/twinblast.html
  5. This is a default TwinBLAST page that requires the following inputs to be added in order to view the example data. Please note the arrows present on the page that let one expand and shrink the various panels as they see fit. With the top panel expanded, the following data can be entered:

    1. Blast File: SRX135546_UM_all_uniq_filtered.out (the contents of this file can be found within the VM at the path: /export/lgt/files/SRX135546_UM_all_uniq_filtered.out)
    2. Query List (optional): mauritiana_ids.txt (the contents of this file can be found at the path: /export/lgt/files/mauritiana_ids.txt. This optional file aims to refine the "query List" displayed to a specific subset of the main BLAST file. If this optional input is not specified, then all the results from the BLAST file will be displayed.)
    3. Left ID suffix: /1 (the chosen left ID suffix that follows each left/first query ID in the Blast File)
    4. Right ID suffix: /2 (the chosen right ID suffix that follows each right/second query ID in the Blast File)

  6. Once this information has been entered into the correct input areas, clicking "Reload" towards the bottom of the top panel will then populate the data within the "Query List" panel.
  7. After a dataset is loaded, either navigate to a particular ID using the "ID (prefix only)" input box under the "Analyze" header of the top panel or click on any of the IDs under the "Query List" panel.
  8. Each ID can be annotated using the "Analyze" section of the top panel. The default values "yes", "no", and "maybe" can be used or a custom value can be entered into the blank textbox after clicking the adjacent button. Once the annotation has been determined, click the refresh icon towards the bottom-right of the "Query List" panel to view that the curation note has been attached to the ID.

Customization of the VM

If curation is not a concern, one can place their properly formatted BLAST file (matches format of /export/lgt/files/SRX135546_UM_all_uniq_filtered.out where each pair of the two BLAST search results follows one after the other) in /export/lgt/files/ and TwinBLAST is ready for use without the need for configuring MySQL. The following sections go into detail as to how to configure Apache, MySQL, and the VM itself in order to achieve thorough customization of TwinBLAST.

Apache

  • The main Apache configuration occurs within '/etc/apache2/apache2.conf'
  • Changing lines 73 and 165 determine where the server and CGI executables, respectively, can be found
  • Line 151 denotes that the conf file at /etc/apache2/conf.d/twinblast.conf will be used for obtaining paths to directories like where to store the BLAST image outputs
  • The environment variable CHOSEN_DB in 'twinblast.conf' needs to be changed depending on which MySQL DB is desired for use when annotating results

MySQL

While MySQL is used in the default setup of TwinBLAST, it should be possible to use other databases like PostgreSQL with some modifications to the following scripts and file to convert from MySQL syntax to another database's format. Note that the .ini file needs to be changed to correspond with 'twinblast.conf' mentioned in the Apache section.

  • /var/www/html/cgi/guiblast
  • /var/www/html/cgi/twinblastDB
  • /var/www/html/conf/curation_db.ini

In order to add a new database compatible with the current set of scripts, follow these steps start in a terminal:

  1. Login to MySQL

    mysql -h localhost -u root

  2. Once in the MySQL prompt, first create the new custom database

    CREATE DATABASE custom_db_name

  3. Make sure TwinBLAST has permissions to make changes to the database

    GRANT ALL on custom_db_name.* TO 'twinblast'@'localhost';

  4. Switch to the new database to populate it

    use custom_db_name

  5. Add in the curation table that houses both the query ID and an ID to tie it to a particular curation note

    CREATE TABLE curation(seq_id VARCHAR(100), cv_id INT, PRIMARY KEY(seq_id));

  6. Create the table that houses the curation notes and insert the correct values into it

    CREATE TABLE cv(id INT, name VARCHAR(100), PRIMARY KEY(name));
INSERT INTO cv VALUES (1, ‘yes’);
INSERT INTO cv VALUES (2, ‘no’);
INSERT INTO cv VALUES (3, ‘maybe’);

  7. Now leave MySQL

    8. quit
  8. Copy lines 1-6 in '/var/www/html/conf/curation_db.ini' and make a new set of 6 lines replacing all instances of 'mauritiana' with the 'custom_db_name' specified in the MySQL step 2
  9. Modify line 10 in '/etc/apache2/conf.d/twinblast.conf' to the 'custom_db_name' specified in the MySQL step 2

Resizing the VM

The most recent version of the TwinBLAST VM has about 560 MB in free space available. If more storage is required the VM can be resized using the following steps assuming that the host computer has enough space to accommodate the size increase. A walkthrough for each step necessary to increase space and then partition that space can be found here.

Instructions for how to build a TwinBLAST server from scratch

The following packages are required in order to install and run TwinBLAST:

  • Apache
  • ExtJS
  • MySQL

Perl Modules:

  • BioPerl
  • CGI
  • Tie::File
  • File::Basename
  • Digest::MD5
  • URI::Escape
  • JSON
  • POSIX
  • Bio::Graphics
  • Config::IniFiles
  • File::Slurp

Installation

  1. Download and unpack the tarball/zip file from the top of the page

    tar xzvf IGS-twinblast-<build>.tar.gz

  2. Copy the cgi directory to the cgi-bin area of your apache install 

    cd IGS-twinblast-build
cp . -r www/cgi /var/www/cgi-bin/twinblast

  3. Copy the html directory to the htdocs area of your apache install

    cp . -r www/html /var/www/htdocs/twinblast

  4. Change the following values in /var/www/cgi-bin/twinblast/guiblast to reflect the install location

    # Root of the web site (usually htdocs or html)
my $www_root = '/var/www/';

# URL to web-accessible directory where image files are written.
my $img_url = '/twinblast/images/';

# Place where blast indexes should be written.
my $idx_dir = '/var/www/twinblast/indexes/';

# Required prefix for all files
my $prefix = '/var/www/twinblast/files/';

  5. Change the following values in /var/www/htdocs/twinblast/twinblast.js

    Ext.onReady(function(){

    // URL to the guiblast binary
    var GUIBLAST_URL = '/cgi-bin/twinblast_test/guiblast';

  6. Update the location of the extjs javascript and css files in twinblast.html

    <script type="text/javascript" src="/ext-4.1.1a/ext-all-debug.js"></script>
<script type="text/javascript" src="twinblast.js"></script>
<!-- Include Ext stylesheets here: -->

<link rel="stylesheet" type="text/css" href="/ext-4.1.1a/resources/css/ext-all.css">

  7. Now you should be able to load blast reports into the interface using the form at the top.

  8. To use the sample data, download the tarball and place it in the directory you specified as the prefix in step 4 (/var/www/twinblast/files/). Then unpack the tarball

    cp ~/Downloads/twinblast_mauritiana.tgz /var/www/twinblast/files/
cd /var/www/twinblast/files/
tar xzvf twinblast_mauritiana.tgz

  9. Now load the twinblast web form by entering in the ip address or hostname of your webserver with the url of the twinblast.html file (i.e. 192.168.100.1/twinblast/twinblast.html)

    When the page loads copy and paste the path to your blast output file into the 'Blast File' box (/var/www/twinblast/files/twinblast_mauritiana/SRX135546_UM_all_uniq_filtered.out)

    Now change the 'Left ID Suffix' and 'Right ID Suffix' to /1 and /2 respectively. These characters have been added to the read names to distinguish between read 1 and read 2.

    Next, copy and paste the path to the list of id's into the 'List of queries' box (/var/www/twinblast/files/twinblast_mauritiana/mauritiana_ids.txt)

    Now click the reload button and wait for your results to be indexed.