sequenceserver 0.6.7

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+gem 'ptools'
+gem 'sinatra', '>=1.0'

data/LICENSE.txt

@@ -0,0 +1,64 @@
+SequenceServer (http://sequenceserver.com) 
+Copyright (c) 2010-2011  Yannick Wurm, Benjamin J. Woodcroft, Anurag Priyam. 
+
+
+1.  Definitions 
+
+The software: the SequenceServer software and associated documentation.
+The authors: Yannick Wurm, Anurag Priyam, Benjamin J. Woodcroft. 
+
+
+2. Fair usage
+
+Within not-for-profit and educational organizations the software can 
+be freely used by individuals and on internal and public websites.
+
+Installation of the software or use of the software by for-profit 
+organizations (including but not limited to companies, service providers 
+and consultancies) requires purchase of a usage license or other specific
+arrangements with the authors.
+
+
+3. Modifications
+
+Modifications can be made by not-for-profit and educational organizations. 
+However, citation requests and links to sequenceserver.com must remain
+visible and unaltered. 
+
+
+4. Redistribution of the software
+
+Redistribution without modification is permitted unless associated to 
+a financial transaction. In particular, the software may not be 
+distributed with nor installed via a commercial software package, nor 
+be made available by commercial service providers.  
+
+Redistribution with modification is permitted only if ALL of the 
+following conditions are respected:
+
+   a. no financial transaction is associated (see above). 
+   b. This license and copyright notices are included and remain
+      unchanged; citation requests and links to sequenceserver.com 
+      remain visible and unaltered. 
+   c. Modifications are made freely available on github.com (or an 
+      equivalent medium) and the authors are allowed to freely 
+      incorporate modifications into the software.
+
+
+5. Specific needs
+
+The authors reserve the right to make specific licensing, modification 
+and distribution  arrangements with interested parties. 
+
+
+6. Disclaimer
+
+THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.txt

@@ -0,0 +1,5 @@
+Thanks for downloading SequenceServer!
+
+Documentation available at http://www.sequenceserver.com
+
+-- Yannick Wurm, Ben Woodcroft, Anurag Priyam

data/bin/database_formatter

@@ -0,0 +1,195 @@
+#!/usr/bin/env ruby
+# copyright yannick . wurm at unil . ch
+# Finds files, reads first char. if its '>', read 500 lines. Guess sequence type, ask user for title to format as blast database.
+
+# ensure 'lib/' is in the load path
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'rubygems'
+require 'ptools' # for File.binary?(file)
+require 'find'
+require 'logger'
+require 'optparse'
+require 'sequenceserver'
+require 'sequenceserver/helpers.rb'
+require 'sequenceserver/sequencehelpers.rb'
+
+LOG = Logger.new(STDOUT)
+LOG.level = Logger::INFO
+
+class DatabaseFormatter
+    include SequenceServer
+	include Helpers
+    include SystemHelpers
+    include SequenceHelpers
+    
+    attr_accessor :db_path
+
+    def initialize(db_path = nil)
+      @app = SequenceServer::App
+      @app.config = @app.parse_config
+      @app.binaries = @app.scan_blast_executables(@app.bin).freeze
+
+      @db_path = (db_path or @app.database)
+    end
+
+    def format_databases
+      unless File.directory?(db_path)
+        LOG.fatal("Database directory #{db_path} not found. See './database_formatter --help' for instructions.")
+        exit
+      end
+
+        formatted_dbs = %x|#{@app.binaries['blastdbcmd']} -recursive -list #{db_path} -list_outfmt "%f" 2>&1|.split("\n")
+        commands = []
+        Find.find(db_path) do |file|
+            LOG.debug("Assessing file #{file}..")
+            if File.directory?(file)
+              LOG.debug("Ignoring file #{file} since it is a directory")
+              next
+            end
+            if formatted_dbs.include?(file)
+              LOG.debug("Ignoring file #{file} since it is already a blast database")
+              next
+            end
+            if File.binary?(file)
+              LOG.debug("Ignoring file #{file} since it is a binary file, not plaintext as FASTA files are")
+              next
+            end
+
+                if probably_fasta?(file)
+                    LOG.info("Found #{file}")
+                    ## guess whether protein or nucleotide based on first 500 lines
+                    first_lines = ''
+                    File.open(file, 'r') do |file_stream|
+                        file_stream.each do |line|
+                            first_lines += line
+                            break if file_stream.lineno == 500
+                        end
+                    end
+                    begin
+                        sequence_type = type_of_sequences(first_lines) # returns :protein or :nucleotide
+                    rescue
+                        LOG.warn("Unable to guess sequence type for #{file}. Skipping") 
+                    end
+                    if [ :protein, :nucleotide ].include?(sequence_type)
+                        command = ask_make_db_command(file, sequence_type)
+                        unless command.nil?
+                            commands.push(command)
+                        end
+                    else 
+                        LOG.warn("Unable to guess sequence type for #{file}. Skipping") 
+                    end
+                else
+                  LOG.debug("Ignoring file #{file} since it was not judged to be a FASTA file.")
+                end
+        end
+        LOG.info("Will now create DBs")
+        if commands.empty?
+          puts "", "#{db_path} does not contain any unformatted database."
+          exit
+        end
+        commands.each do |command|
+			LOG.info("Will run: " + command.to_s)
+            system(command)
+        end
+        LOG.info("Done formatting databases. ")
+        db_table(db_path)
+    end
+
+    def db_table(db_path)
+        LOG.info("Summary of formatted blast databases:\n")
+        output = %x|#{@app.binaries['blastdbcmd']} -recursive -list #{db_path} -list_outfmt "%p %f %t" &2>1 |
+        LOG.info(output)
+    end
+
+    def probably_fasta?(file)
+		return FALSE if File.zero?(file)
+        File.open(file, 'r') do |file_stream|
+            first_line = file_stream.readline
+            if first_line.slice(0,1) == '>'
+                return TRUE
+            else 
+                return FALSE
+            end
+        end
+    end
+
+
+    # returns command than needs to be run to make db
+    def ask_make_db_command(file, type)
+        LOG.info("FASTA file: #{file}")
+        LOG.info("Fasta type: " + type.to_s)
+        
+        response = ''
+        until response.match(/^[yn]$/i) do
+            LOG.info("Proceed? [y/n]: ")
+            response = STDIN.gets.chomp
+        end
+
+        if response.match(/y/i)
+            LOG.info("Enter a database title (or will use '#{File.basename(file)}'")
+            title = STDIN.gets.chomp
+			title.gsub!('"', "'")
+            title = File.basename(file)  if title.empty?
+            
+            return make_db_command(file,type,title)
+        end
+    end
+
+    def make_db_command(file,type, title)
+        LOG.info("Will make #{type.to_s} database from #{file} with #{title}")
+        command = %|#{@app.binaries['makeblastdb']} -in #{file} -dbtype #{ type.to_s.slice(0,4)} -title "#{title}" -parse_seqids|
+        LOG.info("Returning: #{command}")
+        return(command)
+    end
+end
+
+OptionParser.new do |opts|
+  opts.banner =<<BANNER
+NAME
+
+  database_formatter.rb - prepare BLAST databases for SequenceServer
+
+SYNOPSIS
+
+  ./database_formatter.rb [--verbose] [blast_database_directory]
+
+  Example:
+
+    $ ./database_formatter.rb ~/db   # explicitly specify a database directory
+    $ ./database_formatter           # use the database directory in config.yml
+
+DESCRIPTION
+
+  database_formatter recursively scans the given 'blast_database_directory' for
+  BLAST databases and formats them for use with SequenceServer.
+
+  It automagically detects the database type, and ignores non-db files and
+  pre-formatted databases. The 'parse_seqids' makeblastdb options is used.
+
+  'blast_database_directory' can be passed as a command line parameter or
+  through config.yml by setting the 'database' key (the same option used by
+  SequenceServer). See example.config.yml. database_formatter will check
+  config.yml only if the command line parameter is missing.
+
+  Failing both, database_formatter will look for 'database' directory relative
+  to the current working directory i.e ./database.
+
+  database_formatter can be used standalone too.
+
+OPTIONS
+
+BANNER
+
+  opts.on_tail('-h', '--help', 'Show this message') do
+    puts opts
+    exit
+  end
+
+  opts.on('-v', '--verbose', 'Print lots of output') do
+    LOG.level = Logger::DEBUG
+  end
+end.parse!
+
+app = DatabaseFormatter.new(ARGV[0])
+app.format_databases

data/bin/sequenceserver

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+# application root
+root = File.dirname(File.dirname(__FILE__))
+
+require 'rubygems'
+require File.join(root, 'lib', 'sequenceserver')
+
+# display name for tools like `ps`
+$PROGRAM_NAME = 'sequenceserver'
+
+SequenceServer::App.run!

data/config.ru

@@ -0,0 +1,5 @@
+# ensure 'lib/' is in the load path
+require File.join(File.dirname(__FILE__), 'lib', 'sequenceserver')
+
+SequenceServer::App.init
+run SequenceServer::App

data/example.config.yml

@@ -0,0 +1,39 @@
+# Path to the blast executables.
+# 
+# Sequence Server scans the given directory for blast binaries. Ideally it
+# should point the `bin` of your BLAST+ installation. Not setting this
+# value, or setting it to `nil` will default to searching the system `PATH`.
+#
+# Uncomment the following line, and change to appropriate value to use.
+#
+# bin: ~/ncbi-blast-2.2.25+/bin/
+
+# Path to blast database.
+#
+# Sequence Server scans the given directory (including the sub-directories)
+# for blast database. You can not specify more than one top-level directory.
+# Not setting this value, will default to searching `database` directory
+# relative to the current working directory.
+#
+# Uncomment the following line, and change to appropriate value to use.
+#
+# database: ~/blast_databases/
+
+# Port to run Sequence Server on.
+#
+# The app will then be accessible at http://your-ip:port. Defaults to 4567.
+# http://localhost:port is also valid for local access.
+#
+# Uncomment the following line, and change to appropriate value to use.
+#
+# port: 4567
+
+# number of threads to be use when blasting
+#
+# This option is passed directly to BLAST+. Setting this option to more
+# than 1 may crash BLAST+ if it was not compiled with threading support.
+# Default is to use the safe value of 1.
+#
+# Uncomment the following line, and change to appropriate value to use.
+#
+# num_threads: 1

data/lib/sequenceserver/blast.rb

@@ -0,0 +1,211 @@
+require 'tempfile'
+require 'open3'
+
+module SequenceServer
+  # Simple ncbi-blast wrapper. Check examples below.
+  class Blast
+    # blast method
+    attr_accessor :method
+
+    # database name
+    attr_accessor :db
+
+    # query sequence string
+    attr_accessor :qstring
+
+    # query file name
+    attr_accessor :qfile
+
+    # advanced blast options
+    attr_accessor :options
+
+    # command string to be executed
+    attr_reader   :command
+
+    # result of executing command
+    attr_reader   :result
+
+    # blast archive file output
+    attr_reader   :blast_archive_tempfile
+
+    # errors if any while executing command
+    attr_reader   :error
+
+    # Initialize a new blast search.
+    # ---
+    # Arguments(optional):
+    # * method(String)  - blast executable (shell executable, or absolute path)
+    # * db(String)      - database name as returned by 'blastdbcmd -list'
+    # * query(Hash)     - query string/file, and options.
+    #
+    # In the query Hash, use:
+    # * :qfile(String)   - to run Blast against a file.
+    # * :qstrin(String)  - to run Blast against a string.
+    # * :options(String) - to specify multiple blast options.
+    #
+    # Either :qfile, or :qstring should be used. If both are given, by design
+    # :qstring will be used to run blast.
+    # ---
+    # Examples:
+    #
+    #   b = Blast.new("blastn", "S.cdna.fasta", :qfile => 'query.seq', :options => "-html -num_threads 4")
+    #   b = Blast.new("blastn", "S.cdna.fasta", :qstring => 'ATGTCCGCGAATCGATTGAACGTGCTGGTGACCCTGATGCTCGCCGTCGCGCTTCTTGTG')
+    #
+    #   b.run!        => true
+    #   b.result      => "blast output"
+    #
+    #   # change the blast method.
+    #   b.method = 'blastp'
+    #
+    #   b.run!        => false
+    #   b.error       => "blast error output"
+    def initialize(method = nil, db = nil, query = {})
+      @method  = method
+      @db      = db
+      @qstring = query[:qstring]
+      @qfile   = query[:qfile]
+      @options = query[:options]
+    end
+
+    # Run blast everytime it is called. Returns the success
+    # status - true, or false. Blast method, db, and qfile/qstring
+    # need to be set before calling this method, else blast will fail.
+    #
+    #   b = Blast.new
+    #   b.run!   => false
+    #
+    #   # set blast method, and db
+    #   b.method = 'blastn'
+    #   b.db     = 'S.cdna.fasta'
+    #
+    #   b.run!   => false
+    #   b.errors => "blast error output"
+    #
+    #   # set qfile
+    #   b.qfile  = 'query1.seq'    
+    #
+    #   b.run!   => true
+    #   b.reuslt => "blast output"
+    def run!
+      # can not run blast if method is not specified
+      return false unless @method
+
+      # create a tempfile if qstring is given
+      if @qstring
+        @tempfile = Tempfile.new('qfile')
+        @tempfile.puts(qstring)
+        @tempfile.close
+        @qfile    = @tempfile.path
+      end
+
+      # form command to execute
+      @command = to_s
+
+      # execute command and capture both stdout, and stderr
+      Open3.popen3(@command) do |stdin, stdout, stderr|
+        @result = stdout.readlines # convert to string?
+        @error  = stderr.readlines
+      end
+
+      # set and return success status
+      return @success = @error.empty?
+
+    ensure
+      # delete tempfile if it was created
+      @tempfile.unlink if @tempfile
+    end
+
+    # Return the blast type used as a String.
+    #
+    #   b.method = '/home/yeban/opt/blastn'
+    #   b.type   => 'blastn'
+    def type
+      @type ||= @method[(@method.rindex('/') + 1)..-1]
+    end
+
+    # Return success status - true, false, or nil.
+    # 'nil' implies that blast has not been run yet.
+    def success?
+      @success
+    end
+
+    # String representation of the blast object - same as
+    # the command to be executed.
+    def to_s
+      s = "#@method "
+      s << "-db '#@db' " if @db
+      s << "-query #@qfile " if @qfile
+      s << @options.to_s if @options
+      s
+    end
+
+    # Especially helpful in irb - "status : command"
+    def inspect
+      return to_s if success?.nil?
+      (success? ? "success : " : "fail : ") + @command
+    end
+
+    # Run the blast with the options specified by the user, returning a blast archive file, which can be further transformed into other formats
+    def run_to_blast_archive!
+      @blast_archive_tempfile = Tempfile.open('seqserve_formatter')
+
+      # Add -outfmt 11 to list of options so that it outputs a blast archive
+      @options ||= ''
+      @options += " -outfmt 11 -out #{@blast_archive_tempfile.path}"
+
+      # Run the blast
+      run!
+      return @success unless @success
+    end
+
+    # convert the blast archive to a regular HTML result, stored
+    # as an instance variable Blast#result
+    def convert_blast_archive_to_html_result(blast_formatter_path)
+      @command = "#{blast_formatter_path} -archive #{blast_archive_tempfile.path} -html"
+
+      # execute command and capture both stdout, and stderr
+      Open3.popen3(@command) do |stdin, stdout, stderr|
+      @result = stdout.readlines # convert to string?
+      @error  = stderr.readlines
+      end
+    end
+
+    class << self
+      # shortcut method to run blast against a query file
+      def blast_file(method, db, qfile, options = nil)
+        b = Blast.new(method, db, :qfile => qfile, :options => options)
+        b.run!
+        b
+      end
+
+      # shortcut method to run blast against a query string
+      def blast_string(method, db, qstring, options = nil)
+        b = Blast.new(method, db, :qstring => qstring, :options => options)
+        b.run!
+        b
+      end
+
+      # shortcut method to run blast with a query string and return a
+      # blast archive, which can then be further processed into other useful
+      # output forms (e.g. HTML, GFF). If it ran successfully, the blast archive
+      # is a Tempfile accessible as an instance variable of the returned
+      # Blast object.
+      def blast_string_to_blast_archive(method, db, qstring, options = nil)
+        b = Blast.new(method, db, :qstring => qstring, :options => options)
+        b.run_to_blast_archive!
+        b
+      end
+
+      # shortcut method to run blast with a query string and return a
+      # blast archive, which can then be further processed into other useful
+      # output forms (e.g. HTML, GFF). If it ran successfully, the blast archive
+      # is a Tempfile accessible as an instance variable of the returned
+      # Blast object.
+      def blast_string_to_blast_archive(method, db, qstring, options = nil)
+      b = Blast.new(method, db, :qstring => qstring, :options => options)
+      b.run_to_blast_archive!
+      b
+      end
+    end
+  end
+end

data/lib/sequenceserver/customisation.rb

@@ -0,0 +1,60 @@
+module SequenceServer
+  module Customisation
+    ## When not commented out, this method is used to take a
+    ## sequence ID, and return a hyperlink that
+    ## replaces the hit in the BLAST output.
+    ##
+    ## Return the hyperlink to link to, or nil
+    ## to not not include a hyperlink.
+    ##
+    ## When this method
+    ## is commented out, the default link is used. The default
+    ## is a link to the full sequence of
+    ## the hit is displayed (if makeblastdb has been run with
+    ## -parse_seqids), or no link at all otherwise.
+    # def construct_custom_sequence_hyperlink(options)
+    #   ## Example:
+    #   ## sequence_id comes in like "psu|MAL13P1.200 | organism=Plasmodium_falciparum_3D7 | product=mitochondrial"
+    #   ## output: "http://apiloc.bio21.unimelb.edu.au/apiloc/gene/MAL13P1.200"
+    #   matches = options[:sequence_id].match(/^\s*psu\|(\S+) /)
+    #   if matches #if the sequence_id conforms to our expectations
+    #     # All is good. Return the hyperlink.
+    #     return "http://apiloc.bio21.unimelb.edu.au/apiloc/gene/#{matches[1]}"
+    #   else
+    #     # Parsing the sequence_id didn't work. Don't include a hyperlink for this
+    #     # sequence_id, but log that there has been a problem.
+    #     settings.log.warn "Unable to parse sequence id `#{options[:sequence_id]}'"
+    #     # Return nil so no hyperlink is generated.
+    #     return nil
+    #   end
+    # end
+
+    ## Much like construct_custom_sequence_hyperlink, except
+    ## instead of just a hyperlink being defined, the whole
+    ## line as it appears in the blast results is generated.
+    ##
+    ## This is a therefore more flexible setup than is possible
+    ## with construct_custom_sequence_hyperlink, because doing
+    ## things such as adding two hyperlinks for the one hit
+    ## are possible.
+    ##
+    ## When this method is commented out, the behaviour is that
+    ## the construct_custom_sequence_hyperlink method is used,
+    ## or failing that the default method of that is used.
+    # def construct_custom_sequence_hyperlinking_line(options)
+    #   matches = options[:sequence_id].match(/^\s*psu\|(\S+) /)
+    #   if matches #if the sequence_id conforms to our expectations
+    #     # All is good. Return the hyperlink.
+    #     link1 = "http://apiloc.bio21.unimelb.edu.au/apiloc/gene/#{matches[1]}"
+    #     link2 = "http://google.com/?q=#{matches[1]}"
+    #     return "<a href='#{link1}'>ApiLoc page</a>, <a href='#{link2}'>Google search</a>"
+    #   else
+    #     # Parsing the sequence_id didn't work. Don't include a hyperlink for this
+    #     # sequence_id, but log that there has been a problem.
+    #     settings.log.warn "Unable to parse sequence id `#{options[:sequence_id]}'"
+    #     # Return nil so no hyperlink is generated.
+    #     return nil
+    #   end
+    # end
+  end
+end

data/lib/sequenceserver/database.rb

@@ -0,0 +1,23 @@
+module SequenceServer
+  class Database < Struct.new("Database", :name, :title)
+    def to_s
+      "#{title} #{name}"
+    end
+
+    # Its not very meaningful to compare Database objects, however,
+    # we still add the 'spaceship' operator to be able to sort the
+    # databases by 'title', or 'name' for better visual presentation.
+    # 
+    # We use 'title' for comparison, while relying on 'name' as fallback.
+    #
+    # Trying to sort a list of dbs with 'title' set only for some of them
+    # will obviously produce unpredictable sorting order.
+    def <=>(other)
+      if self.title and other.title
+        self.title <=> other.title
+      else
+        self.name <=> other.name
+      end
+    end
+  end
+end