scbi_blast 0.0.30 → 0.0.31

data/History.txt

@@ -1,3 +1,9 @@
+=== 0.0.31 2011-04-28
+
+* First release at rubygem:
+  * Added documentation
+
+
 === 0.0.1 2010-10-19
 
 * 1 major enhancement:

data/Manifest.txt

@@ -18,4 +18,4 @@ lib/scbi_blast/blast_table_result.rb
 lib/scbi_blast/blast_xml_result.rb
 lib/scbi_blast/blast_simplexml_result.rb
 lib/scbi_blast/batch_blast.rb
-lib/scbi_blast/dust_masker.rb
+lib/scbi_blast/dust_masker.rb

data/README.rdoc

@@ -1,32 +1,100 @@
 = scbi_blast
 
-* http://github.com/#{github_username}/#{project_name}
+* http://www.scbi.uma.es/downloads
 
 == DESCRIPTION:
 
-FIX (describe your package)
+scbi_blast is a ruby gem to handle blast+ executions without the need of temporary files, 
+it has been developed at [SCBI](http://www.scbi.uma.es) by Almudena Bocinos & Dario Guerrero.
 
-== FEATURES/PROBLEMS:
+== FEATURES:
 
-* FIX (list of features or problems)
+* Execute blast within ruby without creating temporary files (using pipes)
+* Parse XML and table results into Query and Hit objects
+* Execute DustMasker without temporary files (using pipes)
 
 == SYNOPSIS:
 
-  FIX (code sample of usage)
+scbi_blast can handle *blastn*, *blastp* and *dustmasker* applications from NCBI blast package. 
+Input sequences can be supplied as an array (see the example below) or as a chunk of text 
+inside a string variable.
+
+There are two output formats supported (_table_ and _xml_) by the built-in parsers.
+
+scbi_blast returns an object with all data parsed and splitted into querys and their respective hits. 
+
+=== Blast
+
+Here is an example that shows how to use it to do a blastn:
+
+  require 'scbi_blast'
+
+  # create a blast processor object pointing to a formatted blast database 
+  # that uses a blastn with 4 parallel threads
+
+  blast=BatchBlast.new('-db formatted_blast_db.fasta','blastn','--num_threads 4')
+
+  # fill in some sample sequences (in your code those sequences will come
+  # from a file, an output of another process, etc...)
+
+  seqs=[]
+  seqs << ">GFIXVR"
+  seqs << "GACTACACGACGACCCGACGACGACGAGAGNGNGGACCCGACGACG"
+  seqs << ">GFIM12"
+  seqs << "GACTACACGACGACTAGACCCGACGACGTGACCCGACGACG"
+
+
+  # execute blast
+  res=blast.do_blast(seqs)
+
+
+  # iterate over results printing hit id, start and end positions.
+
+  res.querys.each do |query|
+    query.hits.each do |hit|
+      puts hit.subject_id, hit.q_beg, hit.q_end
+    end
+  end
+  
+
+=== DustMasker
+
+An example that shows how to use it to find dust into some sequences:
+
+  require 'scbi_blast'
+
+  # create DustMasker object
+  dust_masker=DustMasker.new()
+
+  seqs=[]
+  seqs << ">GFIXVR"
+  seqs << "GACTACACGACGACCCGACGACGACGAGAGNGNGGACCCGACGACG"
+  seqs << ">GFIM12"
+  seqs << "GACTACACGACGACTAGACCCGACGACGTGACCCGACGACG"
+
+  dust_regions = dust_masker.do_dust(seqs.join("\n"))
+
+  puts "Found #{dust_regions.count} dust regions"
+
+  dust_regions.each do |dust|
+    # region is defined as an array, where element [0] is the start
+    # of the region, and [1] is the end
+    puts dust.join(',')
+  end
 
 == REQUIREMENTS:
 
-* FIX (list of requirements)
+* NCBI blast+ already installed
 
 == INSTALL:
 
-* FIX (sudo gem install, anything else)
+gem install scbi_blast
 
 == LICENSE:
 
 (The MIT License)
 
-Copyright (c) 2010 Dario Guerrero
+Copyright (c) 2010 Dario Guerrero & Almudena Bocinos
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/lib/scbi_blast/batch_blast.rb

@@ -1,115 +1,131 @@
-#!/usr/bin/env ruby
-
-
+# Copyright (c) 2010 Dario Guerrero & Almudena Bocinos
+# 
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# 'Software'), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# 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.
+
+
+# class to execute Blast without temporary files (it uses pipes)
 class BatchBlast
 
+  # class initialization
   def initialize(database, blast_type = 'blastn', extra_params = '')
 
-  		@blast_type = blast_type
-      @database = database
-      @extra_params = extra_params
-    
-   
+    @blast_type = blast_type
+    @database = database
+    @extra_params = extra_params
+
+
   end
 
+  # returns the blast cmd that will be used to launch blast
   def get_blast_cmd(fmt = :table)
 
-      if fmt==:table 
-      	format = ' -outfmt "7 qseqid sacc pident length mismatch gapopen qstart qend sstart send evalue bitscore score qframe sframe qseq sseq" '    	
-      elsif fmt ==:xml
-      	format = ' -outfmt 5 '    
-      end
+    if fmt==:table
+      format = ' -outfmt "7 qseqid sacc pident length mismatch gapopen qstart qend sstart send evalue bitscore score qframe sframe qseq sseq" '
+    elsif fmt ==:xml
+      format = ' -outfmt 5 '
+    end
+
+    dust=''
 
-      dust=''
+    cmd = @blast_type+' '+dust+@extra_params + format + @database
 
-      #disable dust flag if blastn
-      # if @blast_type.index('blastn')
-      #   dust=' -dust no '
-      # end
-      
-      cmd = @blast_type+' '+dust+@extra_params + format + @database
-      
-      return cmd
+    return cmd
 
   end
 
+  # do a blast to seqs
   def do_blast(seqs, fmt = :table,parse_output=true)
-    
-      if seqs.is_a?(Array)
-        seq_fasta=seqs.join("\n")
-      else
-        seq_fasta=seqs
-      end
 
-      cmd = get_blast_cmd(fmt)
-    
-  		res=''
-
-      # Ojo, que una vez nos ibamos a volver locos buscando porque esto no devolvia todos los hits que se  encontraban al ejecutar el blast a mano, y era porque en el blast a mano le estabamos pasando la secuencia completa mientras que en el MID le estabamos pasando sólo los 20 primeros nt.
-      IO.popen(cmd,'w+') {|blast|
-         blast.sync = true
-         blast.write(seq_fasta)
-         blast.close_write
-         res = blast.readlines
-         blast.close_read
-      }
-    
-      if !$?.exitstatus.nil? && $?.exitstatus>0
-        raise "Error doing blast #{cmd} to fasta: #{seq_fasta}"
-      end
-    
-      # check if all sequences where processed
-    
-      if parse_output
-        if fmt == :table 
-      		res = BlastTableResult.new(res)
-        elsif fmt == :xml
-      		res = BlastSimplexmlResult.new(res)
+    if seqs.is_a?(Array)
+      seq_fasta=seqs.join("\n")
+    else
+      seq_fasta=seqs
+    end
+
+    cmd = get_blast_cmd(fmt)
+
+    res=''
+
+    # Ojo, que una vez nos ibamos a volver locos buscando porque esto no devolvia todos los hits que se  encontraban al ejecutar el blast a mano, y era porque en el blast a mano le estabamos pasando la secuencia completa mientras que en el MID le estabamos pasando solo los 20 primeros nt.
+    IO.popen(cmd,'w+') {|blast|
+      blast.sync = true
+      blast.write(seq_fasta)
+      blast.close_write
+      res = blast.readlines
+      blast.close_read
+    }
+
+    if !$?.exitstatus.nil? && $?.exitstatus>0
+      raise "Error doing blast #{cmd} to fasta: #{seq_fasta}"
+    end
+
+    # check if all sequences where processed
+    if parse_output
+      if fmt == :table
+        res = BlastTableResult.new(res)
+      elsif fmt == :xml
+        res = BlastSimplexmlResult.new(res)
         # elsif fmt ==:xml2
         # res = BlastXmlResult.new(res)
-        end
-        
-        # puts "#{seq_fasta.count('>')}, #{res.querys.count}"
-        
-        if seq_fasta.count('>')!=res.querys.count
-          not_processed = seqs.select{|e| e.index('>')}
-          
-          res.querys.each do |query|
-            if not_processed.include?('>'+query.query_id)
-              not_processed.delete('>'+query.query_id)
-            end
+      end
+
+      # puts "#{seq_fasta.count('>')}, #{res.querys.count}"
+
+      if seq_fasta.count('>')!=res.querys.count
+        not_processed = seqs.select{|e| e.index('>')}
+
+        res.querys.each do |query|
+          if not_processed.include?('>'+query.query_id)
+            not_processed.delete('>'+query.query_id)
           end
-          
-          raise "These sequences #{seq_fasta.count('>')},#{res.querys.count} where not processed by #{cmd}:\n #{not_processed} \n Full_data:\n seqs=#{seqs};\n"
         end
-        
+
+        raise "These sequences #{seq_fasta.count('>')},#{res.querys.count} where not processed by #{cmd}:\n #{not_processed} \n Full_data:\n seqs=#{seqs};\n"
       end
-      
-      return res
-      
+
+    end
+
+    return res
+
   end
-  
+
+  # do blast to an array of Sequence objects
   def do_blast_seqs(seqs, fmt = :table,parse_output=true)
 
-  
-      cmd = get_blast_cmd(fmt)
-   
-      fastas=[]
-      
-      seqs.each do |seq|
-        fastas.push '>'+seq.seq_name
-        fastas.push seq.seq_fasta
-      end
-    
-      return do_blast(fastas,fmt,parse_output)
+
+    cmd = get_blast_cmd(fmt)
+
+    fastas=[]
+
+    seqs.each do |seq|
+      fastas.push '>'+seq.seq_name
+      fastas.push seq.seq_fasta
+    end
+
+    return do_blast(fastas,fmt,parse_output)
 
   end
-  
+
 
   def close
-	
+
   end
 
 end
-
-

data/lib/scbi_blast/blast_hit.rb

@@ -1,115 +1,128 @@
+# Copyright (c) 2010 Dario Guerrero & Almudena Bocinos
+# 
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# 'Software'), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# 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.
+
+
+# Class for a Blast Hit (a concordance between a query and a subject)
 class BlastHit
-   
+
+  # initializes a new hit
   def initialize(q_beg,q_end,s_beg,s_end)
-  
-     @q_beg = q_beg.to_i-1  #to storage in array [0 .. ]
-     @q_end = q_end.to_i-1  #to storage in array [0 .. ]     
-     @s_beg = s_beg.to_i-1
-     @s_end = s_end.to_i-1
-     
-     @reversed = false
-     
-     # TODO -Reversed should be taken from q_frame and s_frame instead of s_end. In proteins comes from q_frame. In nt from s_frames.
-     
-     if @s_beg > @s_end
-       @s_beg = s_end.to_i-1
-       @s_end = s_beg.to_i-1
-       @reversed = true       
-     end
-
-          
-     
-      #              2. S_ID - Subject ID.
-      #              3. IDENT - Identity (%).
-      #              4. ALIGN_LEN - Alignment length.
-      #              5. MISMATCHES - Number of mismatches.
-      #              6. GAPS - Number of gaps.
-      #              7. Q_BEG - Query begin.
-      #              8. Q_END - Query end.
-      #              9. S_BEG - Subject begin.
-      #             10. S_END - Subject end.
-      #             11. E_VAL - Expect value.
-      #             12. BIT_SCORE - Bit score.
-      
-  end
-   
-  def subject_id=(v)   
-   @subject_id = v
+
+    @q_beg = q_beg.to_i-1  #blast indexes are 1 based
+    @q_end = q_end.to_i-1
+    @s_beg = s_beg.to_i-1
+    @s_end = s_end.to_i-1
+
+    @reversed = false
+
+    # TODO -Reversed should be taken from q_frame and s_frame instead of s_end. In proteins comes from q_frame. In nt from s_frames.
+
+    # check if reversed
+    if @s_beg > @s_end
+      @s_beg = s_end.to_i-1
+      @s_end = s_beg.to_i-1
+      @reversed = true
+    end
+
+  end
+
+  # some accessors
+  def subject_id=(v)
+    @subject_id = v
   end
 
   def ident=(v)
-   @ident = v.to_f
+    @ident = v.to_f
   end
 
   def align_len=(v)
-   @align_len = v.to_i
+    @align_len = v.to_i
   end
 
   def mismatches=(v)
-   @mismatches = v.to_i
+    @mismatches = v.to_i
   end
 
   def gaps=(v)
-   @gaps = v.to_i
+    @gaps = v.to_i
   end
 
-  def e_val=(v)     
-   @e_val = v.to_f
+  def e_val=(v)
+    @e_val = v.to_f
   end
 
   def bit_score=(v)
-   @bit_score = v.to_f
+    @bit_score = v.to_f
   end
 
   def score=(v)
- 
-   @score = v.to_f
+
+    @score = v.to_f
   end
 
   def acc=(v)
-   @acc = v
+    @acc = v
   end
 
   def definition=(v)
-   @definition = v
+    @definition = v
   end
 
   def q_frame=(v)
-   @q_frame = v.to_i
+    @q_frame = v.to_i
   end
 
   def s_frame=(v)
-   @s_frame = v.to_i
+    @s_frame = v.to_i
   end
 
   def s_seq=(v)
-   @s_seq = v
+    @s_seq = v
   end
 
   def q_seq=(v)
-   @q_seq = v
+    @q_seq = v
   end
 
   def full_subject_length=(v)
-   @full_subject_length = v
+    @full_subject_length = v
   end
 
+  # puts all hit info on a string
   def inspect
-   res =  "Hit: #{@subject_id.ljust(10)} #{@ident.to_s.rjust(4)} #{@align_len.to_s.rjust(2)} #{@mismatches.to_s.rjust(2)} #{@gaps.to_s.rjust(2)} #{@q_beg.to_s.rjust(5)} #{@q_end.to_s.rjust(5)} #{@s_beg.to_s.rjust(5)} #{@s_end.to_s.rjust(5)} #{@e_val.to_s.rjust(5)}  #{@bit_score.to_s.rjust(5)} #{@reversed.to_s.rjust(5)}"
-   res += " #{@score.to_s.rjust(5)} #{@acc.ljust(10)} #{@definition.ljust(10)} #{@q_frame.to_s.rjust(2)} #{@s_frame.to_s.rjust(2)} #{@full_subject_length.to_s.rjust(5)} #{@q_seq}.#{@s_seq}."
- 
-   return res
+    res =  "Hit: #{@subject_id.ljust(10)} #{@ident.to_s.rjust(4)} #{@align_len.to_s.rjust(2)} #{@mismatches.to_s.rjust(2)} #{@gaps.to_s.rjust(2)} #{@q_beg.to_s.rjust(5)} #{@q_end.to_s.rjust(5)} #{@s_beg.to_s.rjust(5)} #{@s_end.to_s.rjust(5)} #{@e_val.to_s.rjust(5)}  #{@bit_score.to_s.rjust(5)} #{@reversed.to_s.rjust(5)}"
+    res += " #{@score.to_s.rjust(5)} #{@acc.ljust(10)} #{@definition.ljust(10)} #{@q_frame.to_s.rjust(2)} #{@s_frame.to_s.rjust(2)} #{@full_subject_length.to_s.rjust(5)} #{@q_seq}.#{@s_seq}."
+
+    return res
   end
 
   def get_subject
     return @subject_id
   end
 
+  # readers and accessor for properties
   attr_accessor :q_beg, :q_end, :s_beg, :s_end
-
   attr_reader :subject_id, :align_len, :gaps, :mismatches
   attr_accessor :reversed
   attr_reader :score, :acc, :definition, :q_frame, :s_frame, :full_subject_length, :ident, :e_val, :bit_score
   attr_reader :q_seq, :s_seq
-     
+
 end

data/lib/scbi_blast/blast_query.rb

@@ -1,37 +1,64 @@
- class BlastQuery
-   
-   attr_accessor :hits
-   attr_accessor :query_id, :query_def, :full_query_length
-   
-   
+# Copyright (c) 2010 Dario Guerrero & Almudena Bocinos
+# 
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# 'Software'), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# 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.
+
+
+# Object to encapsulate a Blast Query
+class BlastQuery
+
+  attr_accessor :hits
+  attr_accessor :query_id, :query_def, :full_query_length
+
+  # initializes a new Query object
   def initialize(query_id)
     @query_id = query_id
     @query_def = query_id
     @full_query_length = 0
     @hits = []
-   # inspect
+    # inspect
   end
   
+  # add a hit to query
   def add_hit(h)
     @hits.push h
   end
-  
+
+  # inspect query values with all hits
   def inspect
-    res = "\n * Query  #{@query_id} :" 
+    res = "\n * Query  #{@query_id} :"
     res += "subject_id ident align_len mismatches gaps q_beg q_end s_beg s_end e_val bit_score reversed\n\n"
     @hits.each{ |h| res+= h.inspect+"\n" }
-    
+
     return res
-  end     
-  
+  end
+
+  # get num of hits
   def size
     return @hits.size
-  end  
-  
+  end
+
+  # sort hits by command
   def sort(comand)
     return @hits.sort(comand)
   end
-  
- end
 
- 
+end
+
+

data/lib/scbi_blast/blast_simplexml_result.rb

@@ -1,23 +1,35 @@
+# Copyright (c) 2010 Dario Guerrero & Almudena Bocinos
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# 'Software'), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# 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.
+
 require "blast_query.rb"
 require "blast_hit.rb"
 
 require 'zlib'
 require 'xmlsimple'
-#xml=File.open('orf.1.xml').read
-#data = XmlSimple.xml_in(xml)
-#
-#
-#data['best_orf'][0]['start'][0]
-#data['best_orf'][0]['content']
-
-######################################
-# Author:: Almudena Bocinos Rioboo
-# Extracts results from blast table's file and uses it to create instances of "BlastQuery" and "BlastHit"
-
-######################################
 
+# Extracts results from a blast results in XML
+# format and uses it to create instances of "BlastQuery" and "BlastHit"
 class BlastSimplexmlResult
 
+  # Parser initialization
   def initialize(input)
 
     @querys = []
@@ -105,7 +117,7 @@ class BlastSimplexmlResult
 
               hit.q_seq = hsp['Hsp_qseq'][0]
               hit.s_seq = hsp['Hsp_hseq'][0]
-						  
+
 
               hit.subject_id= subject_id
               hit.full_subject_length=full_subject_length
@@ -134,6 +146,7 @@ class BlastSimplexmlResult
     return res
   end
 
+  # finds a query by name
   def find_query(querys,name_q)
     #  newq = querys.find{|q| ( q.find{|h| (h.subject_id)})}
     new_q=nil
@@ -145,11 +158,12 @@ class BlastSimplexmlResult
     return new_q
   end
 
+  # check if there are querys
   def empty?
-
     return @querys.empty?
   end
 
+  # get num of querys
   def size
     @querys.size
   end