= Quorum {<img src="https://secure.travis-ci.org/ncgr/quorum.png?branch=master"alt="Build Status" />}[http://travis-ci.org/ncgr/quorum]

A flexible bioinformatics search tool.

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

* NCBI Blast+ (http://blast.ncbi.nlm.nih.gov)

Dependencies:

* Ruby >= 1.9.2
* Rails >= 3.1.0
* Redis >= 0.900 for Resque (https://github.com/defunkt/resque)
* NCBI Blast+ (ftp://ftp.ncbi.nlm.nih.gov/blast/executables/blast+/LATEST)
* Emboss (http://emboss.sourceforge.net)

See the gem in action.

http://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".

  <tt>cp config/quorum_settings.yml config/quorum_settings.yml.old</tt>

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

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

* Run the install generator and answer "Yes" to all conflicts.

  <tt>rails generate quorum:install</tt>

* Copy the old Search Database(s) to the newly generated
  "config/quorum_settings.yml" file.

* Update the database migrations.

  <tt>rake quorum:install:migrations
  rake db:migrate</tt>

* 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 (http://net-ssh.github.com/ssh/v2/api/index.html)

  ssh_options:
    password: "secret"
    port: 8888

* Tar and compress quorum.

  <tt>tar -czvf quorum.tar.gz quorum/</tt>

* Copy the newly created tarball to the remote machine.

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

* Expand the tarball on the remote machine.

  <tt>ssh <username>@<host></tt>

  <tt>tar -xzvf quorum.tar.gz</tt>

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

  <tt>touch /path/to/.bashrc</tt>

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. http://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.

=== Redis

For detailed Redis installation instructions, follow the links below.

* Redis (http://redis.io)
* Resque (https://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 (https://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?

https://github.com/ncgr/quorum/issues

=== Contributing

* Fork Quorum
* Create a topic branch <code>git checkout -b my_branch</code>
* Push to your branch <code>git push origin my_branch</code>
* 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 (https://github.com/hunzinker)

=== Contributors

* John Crow (https://github.com/crowja)
* Andrew Farmer (https://github.com/adf-ncgr)

== License

MIT License. Copyright NCGR http://ncgr.org