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.

Dependencies:

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 .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 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 or false. Defaults to false.

  • EMPTY= - skip makeblastdb and create necessary directories 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.

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 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

Contributors

License

MIT License. Copyright NCGR ncgr.org