ncgr/quorum

A flexible bioinformatics search tool.

Quorum <img src=“https://secure.travis-ci.org/ncgr/quorum.png?branch=master” alt=“Build Status” /> <img src=“https://gemnasium.com/ncgr/quorum.png” alt=“Dependency Status” />¶ ↑

A flexible bioinformatics search tool.

Quorum is a Rails 3.1 mountable engine that supports the following bioinformatics search tools.

• NCBI Blast+ (blast.ncbi.nlm.nih.gov)

Dependencies:

• Ruby >= 1.9.2

• Rails >= 3.1.0

• Redis >= 0.900 for Resque (github.com/defunkt/resque)

• NCBI Blast+ (ftp.ncbi.nlm.nih.gov/blast/executables/blast+/LATEST)

• Emboss (emboss.sourceforge.net)

See the gem in action.

medplants.ncgr.org/quorum/jobs/new

Installation¶ ↑

Use the latest stable Rails release with Quorum.

gem install quorum

After you install Quorum and add it to your Gemfile, run the generator.

rails generate quorum:install

The generator will create a directory in your application’s root path

quorum/

as well as the necessary config files to run and customize Quorum. You MUST customize “config/quorum_settings.yml” before using Quorum. See Remote Machine Setup below if you choose to execute Quorum remotely.

Migrate the database.

rake quorum:install:migrations
rake db:migrate

Upgrading?¶ ↑

Follow these steps to safely upgrade Quorum.

• Make a copy of “config/quorum_settings.yml”.

  cp config/quorum_settings.yml config/quorum_settings.yml.old

• If you overrode Quorum’s styles and / or views, make a copy of the existing directories before upgrading.

  cp -R app/assets/stylesheets/quorum app/assets/stylesheets/quorum_old cp -R app/views/quorum/jobs app/views/quorum/jobs_old

• Run the install generator and answer “Yes” to all conflicts.

  rails generate quorum:install

• Copy the old Search Database(s) to the newly generated “config/quorum_settings.yml” file.

• Update the database migrations.

  rake quorum:install:migrations rake db:migrate

• If applicable, override Quorum’s views, styles and images.

• Update the remote machine(s).

Getting Started¶ ↑

NCBI Blast+ Setup¶ ↑

Build your NCBI Blast+ database(s) using the rake task below.

rake quorum:blastdb:build

Arguments:

• DIR= - path to {.tgz, .tar.gz, .tbz, .tar.bz2} files containing raw data. Separate multiple directories with a colon (:).

  DIR=/path/to/dir:/path/to/another/dir

• TYPE= - type of Blast database to build {both, prot, nucl}. Defaults to both.

• PROT_FILE_NAME= - name of the file containing protein data. Defaults to peptides.fa.

• NUCL_FILE_NAME= - name of the file containing nucleotide data. Defaults to contigs.fa.

• REBUILD_DB= - removes existing blast database(s) before building {true or false}. Defaults to false.

• EMPTY= - skip makeblastdb and create necessary directories {true or false}. Defaults to false. Set this argument to true if you wish to create your own Blast database(s).

Example:

rake quorum:blastdb:build DIR=/path/to/dir:/path/to/another/dir TYPE=nucl \
NUCL_FILE_NAME=my_contigs.fa REBUILD_DB=true

Empty example:

rake quorum:blastdb:build EMPTY=true

For a full list of supported arguments.

rake -D

Don’t forget to update “config/quorum_settings.yml” with your newly created database(s).

Download Blast Hit Sequence¶ ↑

Quorum provides a link to download a Blast hit sequence in the detailed report. For this process to work smoothly, the sequence identifier MUST be unique across ALL Blast databases.

Example: “example_blast_database/contigs.fa”

>my_unique_sequence_identifier_201201201327077953
ATGC...

“another_example_blast_database/contigs.fa”

>my_unique_sequence_identifier_201201201327078017
CGTA...

If the sequence identifiers are not unique across all Blast databases and you wish to remove the link to download a Blast hit sequence, follow the steps below.

• Override Quorum’s views (see Customize Quorum below)

• Comment out or remove the lines below in “app/views/quorum/jobs/templates/_blast_detailed_report_template.html.erb”

  <p class="small">
    <a id="download_sequence_{{= id }}"
     onclick="downloadSequence(<%= @jobs.id %>, {{= id }}, '{{= algo }}', this)">
     Download Sequence
    </a>
  </p>

Remote Machine Setup – Recommended for Production Use¶ ↑

Follow the steps below to execute Quorum remotely via Net::SSH.

• Ensure your ActiveRecord Database adapter in “config/database.yml” is set to any supported adapter other than sqlite3.

• Ensure your database host is set and accessible via the remote machine(s).

• Ensure you have supplied the necessary information in “config/quorum_settings.yml” to execute Quorum remotely.

  blast:

  remote: true
  ssh_host: remote.machine.org
  ssh_user: remote_user

Net::SSH.start() optional params (net-ssh.github.com/ssh/v2/api/index.html)

ssh_options:
  password: "secret"
  port: 8888

• Tar and compress quorum.

  tar -czvf quorum.tar.gz quorum/

• Copy the newly created tarball to the remote machine.

  scp quorum.tar.gz <username>@<host>:/path/to/install

• Expand the tarball on the remote machine.

  ssh <username>@<host>

  tar -xzvf quorum.tar.gz

• Ensure Quorum script dependencies are added to the remote machine’s PATH. If the remote machine doesn’t have a .bashrc file, create one.

  touch /path/to/.bashrc

and add script dependencies to PATH.

echo "export PATH=/path/to/dependencies:$PATH" >> /path/to/.bashrc

Customize Quorum’s Views, Styles and Images¶ ↑

To override Quorum’s default views, run the generator.

rails generate quorum:views

A copy of Quorum’s layouts and views can be found in your application under “app/views/layouts/quorum/” “app/views/quorum/”.

To override Quorum’s default styles, run the generator.

rails generate quorum:styles

A copy of Quorum’s styles can be found in your application under “app/assets/stylesheets/quorum/”. If your application has existing styles, it’s a good idea to remove

*= require_tree .

in “app/assets/stylesheets/application.css” and require your stylesheets individually.

To override Quorum’s default images, run the generator.

rails generate quorum:images

A copy of Quorum’s images can be found in your application under “app/assets/images/quorum/”.

jQuery UI¶ ↑

Don’t like Quorum’s jQuery UI theme? Override it!

• Override Quorum’s styles and images.

• Roll your own jQuery UI theme. jqueryui.com/themeroller

• Replace Quorum’s theme in “app/assets/{stylesheets:images}/quorum” with your own.

Don’t plan on supporting all of Quorum’s alogrithms?¶ ↑

Override Quorum’s views and comment out any unwanted algorithms in “app/views/quorum/jobs/new.html.erb” and “app/views/quorum/jobs/show.html.erb”.

For example:

Remove Blastp in “app/views/quorum/jobs/new.html.erb”

<%# Search Algorithms %>
<%# Comment out an algorithm below to remove it from the form. %>

<%# blastn %>
<%= render :partial => "quorum/jobs/form/blastn_form", :locals => {
  :f => f, :blast_dbs => @blast_dbs } %>

<%# blastx %>
<%= render :partial => "quorum/jobs/form/blastx_form", :locals => {
  :f => f, :blast_dbs => @blast_dbs } %>

<%# tblastn %>
<%= render :partial => "quorum/jobs/form/tblastn_form", :locals => {
  :f => f, :blast_dbs => @blast_dbs } %>

<%# blastp %>
<% render :partial => "quorum/jobs/form/blastp_form", :locals => {
  :f => f, :blast_dbs => @blast_dbs } %>

<%# End Search Algorithms %>

Remove Blastp in “app/views/quorum/jobs/show.html.erb”

<div id="tabs">
  <ul>
    <li><a href="#tabs-1">Blastn</a></li>
    <li><a href="#tabs-2">Blastx</a></li>
    <li><a href="#tabs-3">Tblastn</a></li>
    <%#
    <li><a href="#tabs-4">Blastp</a></li>
    %>
  </ul>

  <%# Search results per algorithm %>
  <div id="tabs-1">
    <h2>Blastn</h2>
    <div id="blastn-results">
      Searching... <%= image_tag "quorum/loading.gif" %>
    </div>
  </div>

  <div id="tabs-2">
    <h2>Blastx</h2>
    <div id="blastx-results">
      Searching... <%= image_tag "quorum/loading.gif" %>
    </div>
  </div>

  <div id="tabs-3">
    <h2>Tblastn</h2>
    <div id="tblastn-results">
      Searching... <%= image_tag "quorum/loading.gif" %>
    </div>
  </div>

  <!--
  <div id="tabs-4">
    <h2>Blastp</h2>
    <div id="blastp-results">
      Searching... <%= image_tag "quorum/loading.gif" %>
    </div>
  </div>
  -->
</div>

Don’t like Quorum’s default show template?¶ ↑

Override Quorum’s views and specify your own JavaScript callback function!

See “app/views/quorum/show.html.erb” for more details.

For an example using d3.js (github.com/mbostock/d3) see: github.com/ncgr/lis_sequence_search

Redis¶ ↑

For detailed Redis installation instructions, follow the links below.

• Redis (redis.io)

• Resque (github.com/defunkt/resque)

Resque¶ ↑

Quorum provides a simple Rails environment rake task for spawning Resque workers. To customize Resque workers by adding monitoring etc., follow the link below.

• Resque (github.com/defunkt/resque)

Resque Web Interface¶ ↑

Quorum mounts Resque’s web interface by default via

mount Resque::Server.new, :at => "/quorum/resque"

in “config/routes.rb”. The line above is fine for development, however, in production it’s best to grant authenticated users access to “/quorum/resque”.

HTTP Basic Example: “config/initializers/resque_http_auth.rb”

Resque::Server.use(Rack::Auth::Basic) do |user, password|
  user     == "resque"
  password == "secret"
end

Devise Example: “config/routes.rb”

authenticate :user do
  mount Resque::Server.new, :at => "/quorum/resque"
end

Devise plus Declarative Authorization Example: “config/routes.rb”

# Only superusers can access Resque's web interface.
resque_constraint = lambda do |request|
  request.env["warden"].authenticate? &&
  request.env["warden"].user.role_symbols.include?(:superuser)
end

constraints resque_constraint do
  mount Resque::Server.new, :at => "/quorum/resque"
end

I18n¶ ↑

To customize Quorum flash messages, edit “config/locales/quorum.en.yml”.

Additional Information¶ ↑

Bugs?¶ ↑

github.com/ncgr/quorum/issues

Contributing¶ ↑

• Fork Quorum

• Create a topic branch git checkout -b my_branch

• Push to your branch git push origin my_branch

• Create a pull request from your branch

• Find your name added to the README under Contributors

TODO¶ ↑

• Add GFF3 annotations to detailed Blast reports

• Add link to download multiple Blast hit sequences in detailed report

• Support Hmmer3

Maintained By¶ ↑

• Ken Seal (github.com/hunzinker)

Contributors¶ ↑

• John Crow (github.com/crowja)

• Andrew Farmer (github.com/adf-ncgr)

License¶ ↑

MIT License. Copyright NCGR ncgr.org