bio 1.2.1 → 1.3.0

data/lib/bio/location.rb

@@ -2,10 +2,11 @@
 # = bio/location.rb - Locations/Location class (GenBank location format)
 #
 # Copyright::	Copyright (C) 2001, 2005 Toshiaki Katayama <k@bioruby.org>
-# Copyright::   Copyright (C) 2006 Jan Aerts <jan.aerts@bbsrc.ac.uk>
+#                             2006       Jan Aerts <jan.aerts@bbsrc.ac.uk>
+#                             2008       Naohisa Goto <ng@bioruby.org>
 # License::	The Ruby License
 #
-# $Id: location.rb,v 0.28 2007/04/05 23:35:39 trevor Exp $
+# $Id:$
 #
 
 module Bio
@@ -69,7 +70,8 @@ class Location
     when /^[<>]?(\d+)\^[<>]?(\d+)$/			# (C, I) n^m
       s = $1.to_i
       e = $2.to_i
-      if e - s != 1
+      carat = true
+      if e - s != 1 or e != 1 # assert n^n+1 or n^1
 #       raise "Error: invalid range : #{location}"
         $stderr.puts "[Warning] invalid range : #{location}" if $DEBUG
       end
@@ -90,11 +92,38 @@ class Location
     @lt         = lt            # true if the position contains '<'
     @gt         = gt            # true if the position contains '>'
     @xref_id    = xref_id       # link to the external entry as GenBank ID
+    @carat      = carat         # true if the location indicates the site
+                                # between two adjoining nucleotides
   end
 
-  attr_accessor :from, :to, :strand, :sequence, :lt, :gt, :xref_id
+  # (Integer) start position of the location
+  attr_accessor :from
+  # (Integer) end position of the location
+  attr_accessor :to
 
-  # Complements the sequence (i.e. alternates the strand).
+  # (Integer) strand direction of the location
+  # (forward => 1 or complement => -1)
+  attr_accessor :strand
+
+  # (String) literal sequence of the location
+  attr_accessor :sequence
+
+  # (true, false or nil) true if the position contains '<'
+  attr_accessor :lt
+
+  # (true, false or nil) true if the position contains '>'
+  attr_accessor :gt
+
+  # (String) link to the external entry as GenBank ID
+  attr_accessor :xref_id
+
+  # (true, false or nil) true if the location indicates the site
+  # between two adjoining nucleotides
+  attr_accessor :carat
+
+  # Complements the sequence location (i.e. alternates the strand).
+  # Note that it is destructive method (i.e. modifies itself),
+  # but it does not modify the "sequence" attribute.
   # ---
   # *Returns*:: the Bio::Location object
   def complement
@@ -293,6 +322,7 @@ class Locations
   # * (required) _str_: GenBank style position string
   # *Returns*:: Bio::Locations object
   def initialize(position)
+    @operator = nil
     if position.is_a? Array
       @locations = position
     else
@@ -301,9 +331,13 @@ class Locations
     end
   end
 
-  # An Array of Bio::Location objects
+  # (Array) An Array of Bio::Location objects
   attr_accessor :locations
 
+  # (Symbol or nil) Operator.
+  # nil (means :join), :order, or :group (obsolete).
+  attr_accessor :operator
+
   # Evaluate equality of Bio::Locations object.
   def equals?(other)
     if ! other.kind_of?(Bio::Locations)
@@ -427,13 +461,71 @@ class Locations
   end
 
 
+  # String representation.
+  #
+  # Note: In some cases, it fails to detect whether
+  # "complement(join(...))" or "join(complement(..))", and whether
+  # "complement(order(...))" or "order(complement(..))".
+  # 
+  # ---
+  # *Returns*:: String
+  def to_s
+    return '' if @locations.empty?
+    complement_join = false
+    locs = @locations
+    if locs.size >= 2 and locs.inject(true) do |flag, loc|
+        # check if each location is complement
+        (flag && (loc.strand == -1) && !loc.xref_id)
+      end and locs.inject(locs[0].from) do |pos, loc|
+        if pos then
+          (pos >= loc.from) ? loc.from : false
+        else
+          false
+        end
+      end then
+      locs = locs.reverse
+      complement_join = true
+    end
+    locs = locs.collect do |loc|
+      lt = loc.lt ? '<' : ''
+      gt = loc.gt ? '>' : ''
+      str = if loc.from == loc.to then
+              "#{lt}#{gt}#{loc.from.to_i}"
+            elsif loc.carat then
+              "#{lt}#{loc.from.to_i}^#{gt}#{loc.to.to_i}"
+            else
+              "#{lt}#{loc.from.to_i}..#{gt}#{loc.to.to_i}"
+            end
+      if loc.xref_id and !loc.xref_id.empty? then
+        str = "#{loc.xref_id}:#{str}"
+      end
+      if loc.strand == -1 and !complement_join then
+        str = "complement(#{str})"
+      end
+      if loc.sequence then
+        str = "replace(#{str},\"#{loc.sequence}\")"
+      end
+      str
+    end
+    if locs.size >= 2 then
+      op = (self.operator || 'join').to_s
+      result = "#{op}(#{locs.join(',')})"
+    else
+      result = locs[0]
+    end
+    if complement_join then
+      result = "complement(#{result})"
+    end
+    result
+  end
+
   private
 
 
   # Preprocessing to clean up the position notation.
   def gbl_cleanup(position)
     # sometimes position contains white spaces...
-    position.gsub!(/\s+/, '')
+    position = position.gsub(/\s+/, '')
 
     # select one base					# (D) n.m
     #               ..         n          m           :
@@ -456,8 +548,8 @@ class Locations
       end
     end
 
-    # substitute order(), group() by join()		# (F) group(), order()
-    position.gsub!(/(order|group)/, 'join')
+    ## substitute order(), group() by join()		# (F) group(), order()
+    #position.gsub!(/(order|group)/, 'join')
 
     return position
   end
@@ -469,8 +561,11 @@ class Locations
 
     case position
 
-    when /^join\((.*)\)$/				# (F) join()
-      position = $1
+    when /^(join|order|group)\((.*)\)$/				# (F) join()
+      if $1 != "join" then
+        @operator = $1.intern
+      end
+      position = $2
 
       join_list = []		# sub positions to join
       bracket   = []		# position with bracket

data/lib/bio/pathway.rb

@@ -6,7 +6,7 @@
 #               Shuichi Kawashima <shuichi@hgc.jp>
 # License::     The Ruby License
 #
-#  $Id: pathway.rb,v 1.36 2007/04/05 23:35:39 trevor Exp $
+#  $Id:$
 #
 
 require 'matrix'
@@ -184,6 +184,15 @@ class Pathway
   # object.  If the first argument was assigned, the matrix will be
   # filled with the given value.  The second argument indicates the
   # value of the diagonal constituents of the matrix besides the above.
+  #
+  # The result of this method depends on the order of Hash#each
+  # (and each_key, etc.), which may be variable with Ruby version
+  # and Ruby interpreter variations (JRuby, etc.).
+  # For a workaround to remove such dependency, you can use @index 
+  # to set order of Hash keys. Note that this behavior might be
+  # changed in the future. Be careful that @index is overwritten by
+  # this method.
+  # 
   def to_matrix(default_value = nil, diagonal_value = nil)
 
     #--
@@ -206,9 +215,31 @@ class Pathway
       end
     end
 
-    # assign index number for each node
-    @graph.keys.each_with_index do |k, i|
-      @index[k] = i
+    # assign index number
+    if @index.empty? then
+      # assign index number for each node
+      @graph.keys.each_with_index do |k, i|
+        @index[k] = i
+      end
+    else
+      # begin workaround removing depencency to order of Hash#each
+      # assign index number from the preset @index
+      indices = @index.to_a
+      indices.sort! { |i0, i1| i0[1] <=> i1[1] }
+      indices.collect! { |i0| i0[0] }
+      @index.clear
+      v = 0
+      indices.each do |k, i|
+        if @graph[k] and !@index[k] then
+          @index[k] = v; v += 1
+        end
+      end
+      @graph.each_key do |k|
+        unless @index[k] then
+          @index[k] = v; v += 1
+        end
+      end
+      # end workaround removing depencency to order of Hash#each
     end
 
     if @relations.empty?		# only used after clear_relations!
@@ -236,6 +267,10 @@ class Pathway
   # The dump_matrix method accepts the same arguments as to_matrix.
   # Useful when you want to check the internal state of the matrix
   # (for debug purpose etc.) easily.
+  #
+  # This method internally calls to_matrix method.
+  # Read documents of to_matrix for important informations.
+  #
   def dump_matrix(*arg)
     matrix = self.to_matrix(*arg)
     sorted = @index.sort {|a,b| a[1] <=> b[1]}
@@ -245,13 +280,43 @@ class Pathway
 
   # Pretty printer of the adjacency list.
   # 
-  # The dump_matrix method accepts the same arguments as to_matrix.
   # Useful when you want to check the internal state of the adjacency
   # list (for debug purpose etc.) easily.
+  #
+  # The result of this method depends on the order of Hash#each
+  # (and each_key, etc.), which may be variable with Ruby version
+  # and Ruby interpreter variations (JRuby, etc.).
+  # For a workaround to remove such dependency, you can use @index 
+  # to set order of Hash keys. Note that this behavior might be
+  # changed in the future. 
+  # 
   def dump_list
+    # begin workaround removing depencency to order of Hash#each
+    if @index.empty? then
+      pref = nil
+      enum = @graph
+    else
+      pref = {}.merge(@index)
+      i = pref.values.max
+      @graph.each_key do |node|
+        pref[node] ||= (i += 1)
+      end
+      graph_to_a = @graph.to_a
+      graph_to_a.sort! { |x, y| pref[x[0]] <=> pref[y[0]] }
+      enum = graph_to_a
+    end
+    # end workaround removing depencency to order of Hash#each
+
     list = ""
-    @graph.each do |from, hash|
+    enum.each do |from, hash|
       list << "#{from} => "
+      # begin workaround removing depencency to order of Hash#each
+      if pref then
+        ary = hash.to_a
+        ary.sort! { |x,y| pref[x[0]] <=> pref[y[0]] }
+        hash = ary
+      end
+      # end workaround removing depencency to order of Hash#each
       a = []
       hash.each do |to, relation|
         a.push("#{to} (#{relation})")
@@ -285,6 +350,7 @@ class Pathway
     sub_graph = Pathway.new([], @undirected)
     @graph.each do |from, hash|
       next unless @label[from]
+      sub_graph.graph[from] ||= {}
       hash.each do |to, relation|
         next unless @label[to]
         sub_graph.append(Relation.new(from, to, relation))
@@ -310,14 +376,23 @@ class Pathway
   #
   # Calculates the value of cliquishness around the 'node'.  This value
   # indicates completeness of the edge density among the surrounded nodes.
+  #
+  # Note: cliquishness (clustering coefficient) for a directed graph
+  # is also calculated.
+  # Reference: http://en.wikipedia.org/wiki/Clustering_coefficient
+  # 
+  # Note: Cliquishness (clustering coefficient) for a node that has
+  # only one neighbor node is undefined. Currently, it returns NaN,
+  # but the behavior may be changed in the future.
+  #
   def cliquishness(node)
     neighbors = @graph[node].keys
     sg = subgraph(neighbors)
     if sg.graph.size != 0
-      edges = sg.edges / 2.0
-      nodes = sg.nodes
-      complete = (nodes * (nodes - 1)) / 2.0
-      return edges/complete
+      edges = sg.edges
+      nodes = neighbors.size
+      complete = (nodes * (nodes - 1))
+      return edges.quo(complete)
     else
       return 0.0
     end
@@ -396,6 +471,13 @@ class Pathway
   # of the search.
   # 
   # The weight of the edges are not considered in this method.
+  #
+  # Note: The result of this method depends on the order of Hash#each
+  # (and each_key, etc.), which may be variable with Ruby version
+  # and Ruby interpreter variations (JRuby, etc.).
+  # For a workaround to remove such dependency, you can use @index 
+  # to set order of Hash keys. Note that this bahavior might be
+  # changed in the future.
   def depth_first_search
     visited = {}
     timestamp = {}
@@ -405,10 +487,28 @@ class Pathway
     forward_edges = {}
     count = 0
 
+    # begin workaround removing depencency to order of Hash#each
+    if @index.empty? then
+      preference_of_nodes = nil
+    else
+      preference_of_nodes = {}.merge(@index)
+      i = preference_of_nodes.values.max
+      @graph.each_key do |node0|
+        preference_of_nodes[node0] ||= (i += 1)
+      end
+    end
+    # end workaround removing depencency to order of Hash#each
+
     dfs_visit = Proc.new { |from|
       visited[from] = true
       timestamp[from] = [count += 1]
-      @graph[from].each_key do |to|
+      ary = @graph[from].keys
+      # begin workaround removing depencency to order of Hash#each
+      if preference_of_nodes then
+        ary = ary.sort_by { |node0| preference_of_nodes[node0] }
+      end
+      # end workaround removing depencency to order of Hash#each
+      ary.each do |to|
         if visited[to]
           if timestamp[to].size > 1
             if timestamp[from].first < timestamp[to].first
@@ -435,7 +535,13 @@ class Pathway
       timestamp[from].push(count += 1)
     }
 
-    @graph.each_key do |node|
+    ary = @graph.keys
+    # begin workaround removing depencency to order of Hash#each
+    if preference_of_nodes then
+      ary = ary.sort_by { |node0| preference_of_nodes[node0] }
+    end
+    # end workaround removing depencency to order of Hash#each
+    ary.each do |node|
       unless visited[node]
         dfs_visit.call(node)
       end
@@ -543,8 +649,8 @@ class Pathway
         end
       end
     end
-    index.sort{|x, y| y<=>x}.each do |i|
-      rel[i, 1] = []
+    index.sort{|x, y| y<=>x}.each do |idx|
+      rel[idx, 1] = []
     end
     mst = []
     seen = Hash.new()

data/lib/bio/reference.rb

@@ -1,14 +1,17 @@
 #
 # = bio/reference.rb - Journal reference classes
 #
-# Copyright::   Copyright (C) 2001, 2006
+# Copyright::   Copyright (C) 2001, 2006, 2008
 #               Toshiaki Katayama <k@bioruby.org>,
-#               Ryan Raaum <ryan@raaum.org>
+#               Ryan Raaum <ryan@raaum.org>,
+#               Jan Aerts <jandot@bioruby.org>
 # License::     The Ruby License
 #
-# $Id: reference.rb,v 1.24 2007/04/05 23:35:39 trevor Exp $
+# $Id:$
 #
 
+require 'enumerator'
+
 module Bio
 
   # = DESCRIPTION
@@ -66,6 +69,9 @@ module Bio
 
     # medline identifier (typically Fixnum)
     attr_reader :medline
+
+    # DOI identifier (typically String, e.g. "10.1126/science.1110418")
+    attr_reader :doi
     
     # Abstract text in String.
     attr_reader :abstract
@@ -78,6 +84,15 @@ module Bio
 
     # Affiliations in an Array.
     attr_reader :affiliations
+    
+    # Sequence number in EMBL/GenBank records
+    attr_reader :embl_gb_record_number
+    
+    # Position in a sequence that this reference refers to
+    attr_reader :sequence_position
+
+    # Comments for the reference (typically Array of String, or nil)
+    attr_reader :comments
 
     # Create a new Bio::Reference object from a Hash of values. 
     # Data is extracted from the values for keys:
@@ -116,23 +131,23 @@ module Bio
     # * (required) _hash_: Hash
     # *Returns*:: Bio::Reference object
     def initialize(hash)
-      hash.default = ''
-      @authors  = hash['authors'] # [ "Hoge, J.P.", "Fuga, F.B." ]
-      @title    = hash['title']   # "Title of the study."
-      @journal  = hash['journal'] # "Theor. J. Hoge"
-      @volume   = hash['volume']  # 12
-      @issue    = hash['issue']   # 3
-      @pages    = hash['pages']   # 123-145
-      @year     = hash['year']    # 2001
-      @pubmed   = hash['pubmed']  # 12345678
-      @medline  = hash['medline'] # 98765432
-      @abstract = hash['abstract']
+      @authors  = hash['authors'] || [] # [ "Hoge, J.P.", "Fuga, F.B." ]
+      @title    = hash['title']   || '' # "Title of the study."
+      @journal  = hash['journal'] || '' # "Theor. J. Hoge"
+      @volume   = hash['volume']  || '' # 12
+      @issue    = hash['issue']   || '' # 3
+      @pages    = hash['pages']   || '' # 123-145
+      @year     = hash['year']    || '' # 2001
+      @pubmed   = hash['pubmed']  || '' # 12345678
+      @medline  = hash['medline'] || '' # 98765432
+      @doi      = hash['doi']
+      @abstract = hash['abstract'] || '' 
       @url      = hash['url']
-      @mesh     = hash['mesh']
-      @affiliations = hash['affiliations']
-      @authors = [] if @authors.empty?
-      @mesh    = [] if @mesh.empty?
-      @affiliations = [] if @affiliations.empty?
+      @mesh     = hash['mesh'] || []
+      @embl_gb_record_number = hash['embl_gb_record_number'] || nil
+      @sequence_position = hash['sequence_position'] || nil
+      @comments  = hash['comments']
+      @affiliations = hash['affiliations'] || []
     end
 
     # Formats the reference in a given style.
@@ -166,20 +181,22 @@ module Bio
     # ---
     # *Arguments*:
     # * (optional) _style_: String with style identifier
-    # * (optional) _option_: Option for styles accepting one
+    # * (optional) _options_: Options for styles accepting one
     # *Returns*:: String
-    def format(style = nil, option = nil)
+    def format(style = nil, *options)
       case style
+      when 'embl'
+        return embl
       when 'endnote'
         return endnote
       when 'bibitem'
-        return bibitem(option)
+        return bibitem(*options)
       when 'bibtex'
-        return bibtex(option)
+        return bibtex(*options)
       when 'rd'
-        return rd(option)
+        return rd(*options)
       when /^nature$/i
-        return nature(option)
+        return nature(*options)
       when /^science$/i
         return science
       when /^genome\s*_*biol/i
@@ -231,12 +248,8 @@ module Bio
       lines << "%N #{@issue}" unless @issue.to_s.empty?
       lines << "%P #{@pages}" unless @pages.empty?
       lines << "%M #{@pubmed}" unless @pubmed.to_s.empty?
-      if @pubmed
-        cgi = "http://www.ncbi.nlm.nih.gov/entrez/query.fcgi"
-        opts = "cmd=Retrieve&db=PubMed&dopt=Citation&list_uids"
-        @url = "#{cgi}?#{opts}=#{@pubmed}"
-      end
-      lines << "%U #{@url}" unless @url.empty?
+      u = @url.empty? ? pubmed_url : @url
+      lines << "%U #{u}" unless u.empty?
       lines << "%X #{@abstract}" unless @abstract.empty?
       @mesh.each do |term|
         lines << "%K #{term}"
@@ -245,6 +258,24 @@ module Bio
       return lines.join("\n")
     end
 
+    # Returns reference formatted in the EMBL style.
+    #
+    #   # ref is a Bio::Reference object
+    #   puts ref.embl
+    #
+    #     RP   1-1859
+    #     RX   PUBMED; 1907511.
+    #     RA   Oxtoby E., Dunn M.A., Pancoro A., Hughes M.A.;
+    #     RT   "Nucleotide and derived amino acid sequence of the cyanogenic
+    #     RT   beta-glucosidase (linamarase) from white clover (Trifolium repens L.)";
+    #     RL   Plant Mol. Biol. 17(2):209-219(1991).
+    def embl
+      r = self
+      Bio::Sequence::Format::NucFormatter::Embl.new('').instance_eval {
+        reference_format_embl(r)
+      }
+    end
+
     # Returns reference formatted in the bibitem style
     #
     #   # ref is a Bio::Reference object
@@ -255,11 +286,13 @@ module Bio
     #     Title of the study.,
     #     {\em Theor. J. Hoge}, 12(3):123--145, 2001.
     # ---
+    # *Arguments*:
+    # * (optional) _item_: label string (default: <tt>"PMID:#{pubmed}"</tt>).
     # *Returns*:: String
     def bibitem(item = nil)
       item  = "PMID:#{@pubmed}" unless item
       pages = @pages.sub('-', '--')
-      return <<-"END".collect {|line| line.strip}.join("\n")
+      return <<-"END".enum_for(:each_line).collect {|line| line.strip}.join("\n")
         \\bibitem{#{item}}
         #{@authors.join(', ')}
         #{@title},
@@ -298,22 +331,48 @@ module Bio
     # ---
     # *Arguments*:
     # * (optional) _section_: BiBTeX section as String
+    # * (optional) _label_: Label string cited by LaTeX documents.
+    #                       Default is <tt>"PMID:#{pubmed}"</tt>.
+    # * (optional) _keywords_: Hash of additional keywords,
+    #                          e.g. { 'abstract' => 'This is abstract.' }.
+    #                          You can also override default keywords.
+    #                          To disable default keywords, specify false as
+    #                          value, e.g. { 'url' => false, 'year' => false }.
     # *Returns*:: String
-    def bibtex(section = nil)
+    def bibtex(section = nil, label = nil, keywords = {})
       section = "article" unless section
       authors = authors_join(' and ', ' and ')
-      pages   = @pages.sub('-', '--')
-      return <<-"END".gsub(/\t/, '')
-        @#{section}{PMID:#{@pubmed},
-          author  = {#{authors}},
-          title   = {#{@title}},
-          journal = {#{@journal}},
-          year    = {#{@year}},
-          volume  = {#{@volume}},
-          number  = {#{@issue}},
-          pages   = {#{pages}},
-        }
-      END
+      thepages = pages.to_s.empty? ? nil : pages.sub(/\-/, '--')
+      unless label then
+        label = "PMID:#{pubmed}"
+      end
+      theurl = if !(url.to_s.empty?) then
+                 url
+               elsif pmurl = pubmed_url and !(pmurl.to_s.empty?) then
+                 pmurl
+               else
+                 nil
+               end
+      hash = {
+        'author'  => authors.empty?    ? nil : authors,
+        'title'   => title.to_s.empty? ? nil : title,
+        'number'  => issue.to_s.empty? ? nil : issue,
+        'pages'   => thepages,
+        'url'     => theurl
+      }
+      keys = %w( author title journal year volume number pages url )
+      keys.each do |k|
+        hash[k] = self.__send__(k.intern) unless hash.has_key?(k)
+      end
+      hash.merge!(keywords) { |k, v1, v2| v2.nil? ? v1 : v2 }
+      bib = [ "@#{section}{#{label}," ]
+      keys.concat((hash.keys - keys).sort)
+      keys.each do |kw|
+        ref = hash[kw]
+        bib.push "  #{kw.ljust(12)} = {#{ref}}," if ref
+      end
+      bib.push "}\n"
+      return bib.join("\n")
     end
 
     # Returns reference formatted in a general/generic style.
@@ -499,6 +558,17 @@ module Bio
       "#{authors} (#{@year}) #{@title} #{@journal} #{@volume}, #{@pages}"
     end
 
+    # Returns a valid URL for pubmed records
+    #
+    # *Returns*:: String
+    def pubmed_url
+      unless @pubmed.to_s.empty?
+        cgi = "http://www.ncbi.nlm.nih.gov/entrez/query.fcgi"
+        opts = "cmd=Retrieve&db=PubMed&dopt=Citation&list_uids"
+        return "#{cgi}?#{opts}=#{@pubmed}"
+      end
+      ''
+    end
 
     private
 
@@ -528,61 +598,5 @@ module Bio
 
   end
 
-  # = DESCRIPTION
-  #
-  # A container class for Bio::Reference objects.
-  #
-  # = USAGE
-  #
-  #   refs = Bio::References.new
-  #   refs.append(Bio::Reference.new(hash))
-  #   refs.each do |reference|
-  #     ...
-  #   end
-  #
-  class References
-
-    # Array of Bio::Reference objects
-    attr_accessor :references
-
-    # Create a new Bio::References object
-    # 
-    #   refs = Bio::References.new
-    # ---
-    # *Arguments*:
-    # * (optional) __: Array of Bio::Reference objects
-    # *Returns*:: Bio::References object
-    def initialize(ary = [])
-      @references = ary
-    end
-
-
-    # Add a Bio::Reference object to the container.
-    #
-    #   refs.append(reference)
-    # ---
-    # *Arguments*:
-    # * (required) _reference_: Bio::Reference object
-    # *Returns*:: current Bio::References object
-    def append(reference)
-      @references.push(reference) if reference.is_a? Reference
-      return self
-    end
-
-    # Iterate through Bio::Reference objects.
-    #
-    #   refs.each do |reference|
-    #     ...
-    #   end
-    # ---
-    # *Block*:: yields each Bio::Reference object
-    def each
-      @references.each do |reference|
-        yield reference
-      end
-    end
-
-  end
-
 end