RubyGems - ols - Versions diffs - 0.0.1 → 0.1.0 - Mend

ols 0.0.1 → 0.1.0

Files changed (15) hide show

data/.gitignore CHANGED

@@ -1,5 +1,12 @@
 *.gem
 .bundle
+.yardoc/*
+.rbx/*
 Gemfile.lock
+doc/*
 pkg/*
-coverage/*
+coverage/*
+test/vcr_cassettes*
+*.dot
+*.png
+*.jpg

data/Gemfile CHANGED

@@ -2,3 +2,7 @@ source "http://rubygems.org"
 # Specify your gem's dependencies in ols.gemspec
 gemspec
+platforms :jruby do
+  gem 'jruby-openssl'
+end

data/History.txt CHANGED

@@ -1,3 +1,9 @@
+=== 0.1.0 2011-11-04
+* Total rewrite (as a result please note API changes)...
+  * Switch to using the OLS SOAP service instead of local MySQL instance
+  * Remove the use of RubyTree as ontologies are Directed Acyclic Graphs (DAGs), not trees
 === 0.0.1 2011-04-15
 * Initial release:

data/README.rdoc CHANGED

@@ -2,19 +2,14 @@
 http://github.com/dazoakley/ols
-OLS provides a simple interface to the EBI's Ontology Lookup Service (http://www.ebi.ac.uk/ontology-lookup/).
-It provides an easy lookup of ontology terms and automagically builds up ontology trees using RubyTree
-(http://rubytree.rubyforge.org/) as a base library.
-<b>PLEASE NOTE</b>: The current version of this gem requires a local install of the OLS database running on MySQL.
-Please see http://www.ebi.ac.uk/ontology-lookup/databaseExport.do  I will update the code in the future
-to run off the soap service.
+OLS provides a simple interface to the EBI's Ontology Lookup Service (http://www.ebi.ac.uk/ontology-lookup/).
+It provides an easy lookup of ontology terms and automagically builds up ontology graphs.
 == Install
   gem install ols
-== Usage
+== Basic Usage
 Include the module in your code:
@@ -23,67 +18,63 @@ Include the module in your code:
 Then, to lookup an ontology term:
-  ont = OLS::OntologyTerm.new('EMAP:3018')
+  ont = OLS.find_by_id('EMAP:3018')
 This will create a simple tree object for the EMAP term EMAP:3018
-  ont.name          # => "EMAP:3018"
-  ont.term          # => "EMAP:3018"
-  ont.content       # => "TS18,nose"
+  ont.term_id       # => "EMAP:3018"
   ont.term_name     # => "TS18,nose"
 Find out about your ontology term
   ont.is_root?      # => false
   ont.is_leaf?      # => false
-<b>NOTE</b>: OntologyTerm's are lazily loaded, so upon initial build the OntologyTerm is just a single node in a
-tree - no parents, no children.  See here (note the "Total Nodes Loaded" count):
-  ont.to_s          # => "Term: EMAP:3018 Term Name: TS18,nose Root Term?: false Leaf Node?: false  Total Nodes Loaded: 1"
-The tree for the term is built up (parents) and down (children) as it is requested:
-  ont.parentage     # => Array of all parent terms (these will be loaded into the tree now)
-  ont.children      # => Array of all direct child terms (these will also be loaded into the tree now)
-  ont.to_s          # => "Term: EMAP:3018 Term Name: TS18,nose Root Term?: false Leaf Node?: false  Total Nodes Loaded: 4"
-Alternatively, if you want to force load the tree:
-  ont.buld_tree     # => Will load both parents and children into the tree
-Find out more about your tree:
-  ont.root                # => Gives you the root node - in this case: "EMAP:0"
-  ont.all_child_terms     # => An array of all child ontology terms
-  ont.all_child_name      # => An array of all child ontology term names
-For more information on general usage, take a look in the test suite.  Also, OLS::OntologyTerm is a child object of
-Tree::TreeNode (from the rubytree gem - http://rubytree.rubyforge.org/) and as such inherits all of its methods.
+  ont.to_s          # => "EMAP:3018 - TS18,nose"
-== Database Connection Details
+The graph for the term is built up (parents) and down (children) as it is requested:
-The default database connection details are:
+  ont.parents       # => Array of all parent terms objects
+  ont.children      # => Array of all direct child term objects
-  {
-    :database => 'ols',
-    :host     => '127.0.0.1',
-    :port     => 3306,
-    :user     => 'ols',
-    :password => 'ols'
-  }
+Alternatively, if you want to force load the graph (around this term):
-If your local copy of the OLS database requires different details, simply do the following once in your code
-(substituting in your connection details) before any calls to OLS::OntologyTerm are made:
+  ont.focus_graph!  # => Will load all parents and children into the graph
+  ont.size          # => 19
-  OLS.db_connection_details = {
-    :database => 'my_ols',
-    :host     => 'ols.example.com',
-    :port     => 3307,
-    :user     => 'user1',
-    :password => 'pass1'
-  }
+Find out more about your graph:
+  ont.root                # => Gives you the root node - in this case: "EMAP:0"
+  ont.all_parent_ids      # => An array of all parent ontology terms
+  ont.all_parent_names    # => An array of all parent ontology term names
+  ont.all_child_ids       # => An array of all child ontology terms
+  ont.all_child_names     # => An array of all child ontology term names
+Visualise your graph (useful for exploring):
+  ont.root.print_graph
+  # Gives the following:
+  #
+  # * EMAP:0
+  #     |---+ EMAP:2636
+  #         |---+ EMAP:2822
+  #             |---+ EMAP:2987
+  #                 |---+ EMAP:3018
+  #                     |---+ EMAP:3022
+  #                         |---+ EMAP:3023
+  #                             |---+ EMAP:3024
+  #                                 |---> EMAP:3025
+  #                                 |---> EMAP:3026
+  #                             |---+ EMAP:3027
+  #                                 |---> EMAP:3029
+  #                                 |---> EMAP:3028
+  #                             |---+ EMAP:3030
+  #                                 |---> EMAP:3031
+  #                                 |---> EMAP:3032
+  #                     |---> EMAP:3019
+  #                     |---+ EMAP:3020
+  #                         |---> EMAP:3021
+  #
 == Meta
@@ -110,7 +101,7 @@ 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.
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
 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

data/lib/ols.rb CHANGED

@@ -1,422 +1,150 @@
+# encoding: utf-8
-require 'rubygems'
-require 'tree'
-require 'sequel'
-require 'mysql2'
-require 'json'
+require 'savon'
 # Simple wrapper for interacting with the OLS (Ontology Lookup Service - http://www.ebi.ac.uk/ontology-lookup/)
-# database (created and managed by the EBI).  Handles interaction with the service and automagically turns
-# the retieved ontology terms into usable tree stuctures.
-#
-# @author Darren Oakley
+# database (created and managed by the EBI).
+#
+# @author Darren Oakley (https://github.com/dazoakley)
 module OLS
-  class << self
-    attr_accessor :db_connection_details
-    def ols_db
-      @ols_db = connect_to_db() if @ols_db.nil?
-      @ols_db
-    end
-    private
-      def get_db_connection_details
-        defaults = {
-          :database => 'ols',
-          :host     => '127.0.0.1',
-          :port     => 3306,
-          :user     => 'ols',
-          :password => 'ols'
-        }
-        if !OLS.db_connection_details.nil? and OLS.db_connection_details.is_a? Hash
-          defaults.merge!(OLS.db_connection_details)
-        end
-        defaults
-      end
-      def connect_to_db
-        params = { :adapter => 'mysql2', :encoding => 'utf8' }.merge(get_db_connection_details)
-        Sequel.connect(params)
-      end
-  end
   # Error class for when we can't find a given ontology term.
-  class OntologyTermNotFoundError < StandardError; end
-  # Class representing an ontology term as part of a tree structure. Uses the Tree::TreeNode (rubytree)
-  # gem as a base class.
-  class OntologyTerm < Tree::TreeNode
-    attr_accessor :already_fetched_parents, :already_fetched_children
-    attr_accessor :root_term, :leaf_node
-    attr_writer   :all_child_terms, :all_child_names
-    protected     :root_term, :leaf_node
-    # @param [String] name The ontology term (id) i.e. GO:00032
-    # @param [String] content The ontology term name/description - optional this will be looked up in the OLS database
-    def initialize( name, content=nil )
-      super
-      @already_fetched_parents  = false
-      @already_fetched_children = false
-      @root_term                = false
-      @leaf_node                = false
-      @all_child_terms          = nil
-      @all_child_names          = nil
-      get_term_details if @content.nil? or @content.empty?
-    end
-    # Override to ensure compatibility with Tree::TreeNode.
-    #
-    # @return [String] The ontology term (id) i.e. GO00032
-    def term
-      self.name
-    end
+  class TermNotFoundError < StandardError; end
-    # Override to ensure compatibility with Tree::TreeNode.
-    #
-    # @return [String] The ontology term name/description
-    def term_name
-      self.content
-    end
-    # Returns +true+ if the receiver is a root node.  Note that
-    # orphaned children will also be reported as root nodes.
-    #
-    # @return [Boolean] +true+ if this is a root node.
-    def is_root?
-      @root_term
-    end
-    # Returns +true+ if the receiver node is a 'leaf' - i.e., one without
-    # any children.
-    #
-    # @return [Boolean] +true+ if this is a leaf node.
-    def is_leaf?
-      @leaf_node
-    end
-    # Returns string representation of the receiver node.
-    # This method is primarily meant for debugging purposes.
-    #
-    # @return [String] A string representation of the node.
-    def to_s
-      "Term: #{@name}" +
-        " Term Name: " + (@content || "<Empty>") +
-        " Root Term?: #{is_root?}" +
-        " Leaf Node?: #{is_leaf?} " +
-        " Total Nodes Loaded: #{size()}"
-    end
-    # Returns an array of parent OntologyTerm objects.
-    #
-    # @return [Array] An array of parent OntologyTerm objects
-    def parentage
-      get_parents
-      super
-    end
-    # Returns the children of this term as a tree. Will include the current term
-    # as the 'root' of the tree.
+  class << self
+    # Returns the raw (Savon) SOAP client for the OLS webservice
     #
-    # @return [OntologyTerm] The children of this term as a tree. Will include the current term as the 'root' of the tree.
-    def child_tree
-      build_tree
-      child_tree = self.clone
-      child_tree.remove_from_parent!
-      child_tree
+    # @return [Object] The raw (Savon) SOAP client for the OLS webservice
+    def client
+      @client = setup_soap_client if @client.nil?
+      @client
     end
-    # Returns an array of the direct children (OntologyTerm objects) of this term.
-    #
-    # @return [Array] An array of the direct children (OntologyTerm objects) of this term.
-    def children
-      get_children
-      super
+    # Generic request method to allow simple access to all the
+    # OLS webservice end-points (provided by Savon)
+    #
+    # @param [String/Symbol] method The SOAP method to call
+    # @param [Block] &block An optional code-block to pass to the SOAP call
+    # @return [Hash] The OLS method call return
+    def request(method,&block)
+      response = nil
+      if block
+        response = self.client.request(method,&block)
+      else
+        response = self.client.request method
+      end
+      response.body[:"#{method}_response"][:"#{method}_return"]
     end
-    # Returns a flat array containing all the possible child terms
-    # for this given ontology term.
-    #
-    # @return [Array] An array of all possible child terms (Strings) for this given ontology term
-    def all_child_terms
-      get_all_child_lists
-      return @all_child_terms
-    end
-    # Returns a flat array containing all the possible child term
-    # names for this given ontology term.
+    # Fetch the version string for the current build of OLS
     #
-    # @return [Array] A flat array containing all the possible child term names (Strings) for this given ontology term
-    def all_child_names
-      get_all_child_lists
-      return @all_child_names
-    end
-    # Function to force the OntologyTerm object to flesh out it's structure
-    # from the OLS database.  By default OntologyTerm objects are lazy and will
-    # only retieve child data one level below themselves, so this is used to
-    # recursivley flesh out a full tree.
-    def build_tree
-      get_parents
-      get_children( self, true )
+    # @return [String] Then version string for the current OLS build
+    def version
+      request :get_version
     end
-    # Creates a JSON representation of this node including all it's children.   This requires the JSON gem to be
-    # available, or else the operation fails with a warning message.
-    #
-    # @return The JSON representation of this subtree.
-    #
-    # @see {OntologyTerm#json_create}
-    def to_json(*a)
-      json_hash = {
-        "name"            => name,
-        "content"         => content,
-        "root_term"       => @root_term,
-        "leaf_node"       => @leaf_node,
-        "all_child_terms" => @all_child_terms,
-        "all_child_names" => @all_child_names,
-        JSON.create_id    => self.class.name
-      }
-      if has_children?
-        json_hash["children"] = children
-      end
-      return JSON.generate( json_hash, :max_nesting => false )
-    end
-    # Class level function to build an OntologyTerm object from a serialized JSON hash
-    #
-    # @example
-    #   emap = JSON.parse( File.read("emap.json"), :max_nesting => false )
-    #
-    # @param [Hash] json_hash The parsed JSON hash to de-serialize
-    # @return [OntologyTerm] The de-serialized object
-    def self.json_create(json_hash)
-      node = new(json_hash["name"], json_hash["content"])
-      node.already_fetched_children = true if json_hash["children"]
-      node.root_term       = true if json_hash["root_term"]
-      node.leaf_node       = true if json_hash["leaf_node"]
-      node.all_child_terms = json_hash["all_child_terms"]
-      node.all_child_names = json_hash["all_child_names"]
-      json_hash["children"].each do |child|
-        child.already_fetched_parents  = true
-        child.already_fetched_children = true if child.has_children?
-        node << child
-      end if json_hash["children"]
-      return node
-    end
-    # Method to set the parent node for the receiver node.
-    # This method should *NOT* be invoked by client code.
-    #
-    # @param [OntologyTerm] parent The parent node.
-    # @return [OntologyTerm] The parent node.
-    def parent=(parent)         # :nodoc:
-      @parent = parent
-    end
-    # Recursive function to query the OLS database and collect all of
-    # the parent objects and insert them into @parents in the correct
-    # order.
-    def get_parents( node=self )
-      unless @already_fetched_parents
-        sql = <<-SQL
-          select
-            subject_term.identifier  as child_identifier,
-            subject_term.term_name   as child_term,
-            predicate_term.term_name as relation,
-            object_term.identifier   as parent_identifier,
-            object_term.term_name    as parent_term,
-            object_term.is_root_term as parent_is_root
-          from
-            term_relationship tr
-            join term as subject_term 	on tr.subject_term_pk   = subject_term.term_pk
-            join term as predicate_term on tr.predicate_term_pk = predicate_term.term_pk
-            join term as object_term    on tr.object_term_pk    = object_term.term_pk
-          where
-                predicate_term.term_name in ('part_of','is_a','develops_from')
-            and subject_term.identifier = ?
-        SQL
-        OLS.ols_db[ sql, node.term ].each do |row|
-          parent           = OntologyTerm.new( row[:parent_identifier], row[:parent_term] )
-          parent.root_term = true if row[:parent_is_root].to_i == 1
-          parent << node
-          get_parents( parent )
+    # Fetch a hash of all ontologies in the OLS service, keyed by their short-name
+    #
+    # @return [Hash] names of ontologies: short-name (keys), full-names (values)
+    def ontologies
+      @ontologies ||= {}
+      if @ontologies.empty?
+        response = request :get_ontology_names
+        response[:item].each do |ont|
+          @ontologies[ont[:key]] = ont[:value]
         end
-        @already_fetched_parents = true
       end
+      @ontologies
     end
-    # Recursive function to query the OLS database and collect all of
-    # the child objects and build up a tree of OntologyTerm's.
-    def get_children( node=self, recursively=false )
-      unless @already_fetched_children or node.has_children?
-        sql = <<-SQL
-          select
-            subject_term.identifier  as child_identifier,
-            subject_term.term_name   as child_term,
-            subject_term.is_leaf     as child_is_leaf,
-            predicate_term.term_name as relation,
-            object_term.identifier   as parent_identifier,
-            object_term.term_name    as parent_term
-          from
-            term_relationship tr
-            join term as subject_term   on tr.subject_term_pk   = subject_term.term_pk
-            join term as predicate_term on tr.predicate_term_pk = predicate_term.term_pk
-            join term as object_term    on tr.object_term_pk    = object_term.term_pk
-          where
-                predicate_term.term_name in ('part_of','is_a','develops_from')
-            and object_term.identifier = ?
-        SQL
-        OLS.ols_db[sql,node.term].each do |row|
-          child = OntologyTerm.new( row[:child_identifier], row[:child_term] )
-          child.leaf_node = true if row[:child_is_leaf].to_i == 1
-          child.get_children( child, true ) if recursively and !child.is_leaf?
-          node << child
+    # Fetch all the root terms for a given ontology
+    #
+    # @param [String/Symbol] ontology The short-name of the ontology
+    # @return [Array] An array of OLS::Term objects for all root terms the requested ontology
+    def root_terms(ontology)
+      root_terms = []
+      response = request(:get_root_terms) { soap.body = { :ontologyName => ontology } }
+      if response[:item].is_a? Array
+        response[:item].each do |term|
+          root_terms.push( OLS::Term.new(term[:key],term[:value]) )
         end
-        @already_fetched_children = true
+      else
+        term = response[:item]
+        root_terms.push( OLS::Term.new(term[:key],term[:value]) )
       end
+      root_terms
     end
-    # Returns a copy of the receiver node, with its parent and children links removed.
-    # The original node remains attached to its tree.
+    # Fetch an ontology term (OLS::Term) by its id
     #
-    # @return [OntologyTerm] A copy of the receiver node.
-    def detached_copy
-      copy = OLS::OntologyTerm.new(@name, @content ? @content.clone : nil)
-      copy.root_term = @root_term
-      copy.leaf_node = @leaf_node
-      return copy
+    # @param [String/Symbol] term_id An ontology id to look for - i.e. 'GO:0023034'
+    # @return [OLS::Term] An OLS::Term object for the requested ontology id
+    # @raise OLS::TermNotFoundError Raised if the requested ontology id cannot be found
+    def find_by_id(term_id)
+      term_name = request(:get_term_by_id) { soap.body = { :termId => term_id } }
+      raise TermNotFoundError if term_name.eql?(term_id)
+      OLS::Term.new(term_id,term_name)
     end
-    # Function that merges one OntologyTerm tree into another.
+    # Set whether to log HTTP requests - pass in +true+ or +false+
+    attr_writer :log
+    # Returns whether to log HTTP/SOAP requests. Defaults to +false+
     #
-    # @param [OntologyTerm] tree The tree that is to be merged into self
-    # @return [OntologyTerm] The merged tree
-    def merge( tree )
-      unless tree.is_a?(OLS::OntologyTerm)
-        raise TypeError, "You can only merge in another OntologyTerm tree!"
-      end
-      unless self.root.name == tree.root.name
-        raise ArgumentError, "Unable to merge trees as they do not share the same root!"
-      end
-      new_tree = merge_subtrees( self.root, tree.root )
+    # @return [Boolean] To log or not to log, that is the question...
+    def log?
+      @log ? true : false
     end
-    private
-      # Utility function to recursivley merge two subtrees
-      #
-      # @param [OntologyTerm] tree1 The target tree to merge into
-      # @param [OntologyTerm] tree2 The donor tree (that will be merged into target)
-      def merge_subtrees( tree1, tree2 )
-        names1 = tree1.has_children? ? tree1.children.map { |child| child.name } : []
-        names2 = tree2.has_children? ? tree2.children.map { |child| child.name } : []
-        names_to_merge = names2 - names1
-        names_to_merge.each do |name|
-          tree1 << tree2[name].detached_subtree_copy
-        end
+    # Set the logger to use
+    attr_writer :logger
-        tree1.children.each do |child|
-          unless tree2[child.name].nil?
-            merge_subtrees( child, tree2[child.name] )
-          end
-        end
+    # Returns the logger. Defaults to an instance of +Logger+ writing to STDOUT
+    def logger
+      @logger ||= ::Logger.new STDOUT
+    end
-        return tree1
-      end
-      # Helper function to query the OLS database and grab the full
-      # details of the ontology term.
-      def get_term_details
-        # This query ensures we look at the most recent fully loaded ontologies
-        sql = <<-SQL
-          select term.*
-          from term
-          join ontology on ontology.ontology_id = term.ontology_id
-          where term.identifier = ?
-          order by ontology.fully_loaded desc, ontology.load_date asc
-        SQL
+    # Set the log level
+    attr_writer :log_level
-        term_set = OLS.ols_db[ sql, @name ].all()
+    # Return the log level. Defaults to :warn
+    def log_level
+      @log_level ||= :warn
+    end
-        if term_set.size == 0
-          get_term_from_synonym
-        else
-          subject      = term_set.first
-          @content     = subject[:term_name]
-          @term_pk     = subject[:term_pk]
-          @ontology_id = subject[:ontology_id]
-          @root_term   = true if subject[:is_root_term].to_i == 1
-          @leaf_node   = true if subject[:is_leaf].to_i == 1
-        end
-      end
-      # Helper function to try to find an ontology term via a synonym.
-      def get_term_from_synonym
-        sql = <<-SQL
-          select term.*
-          from term
-          join ontology on ontology.ontology_id = term.ontology_id
-          join term_synonym on term.term_pk = term_synonym.term_pk
-          where term_synonym.synonym_value = ?
-          order by ontology.fully_loaded desc, ontology.load_date asc
-        SQL
-        term_set = OLS.ols_db[ sql, @name ].all()
-        if term_set.size == 0
-          raise OLS::OntologyTermNotFoundError, "Unable to find the term '#{@name}' in the OLS database."
-        end
-        subject      = term_set.first
-        @name        = subject[:identifier]
-        @content     = subject[:term_name]
-        @term_pk     = subject[:term_pk]
-        @ontology_id = subject[:ontology_id]
-        @root_term   = true if subject[:is_root_term].to_i == 1
-        @leaf_node   = true if subject[:is_leaf].to_i == 1
-      end
-      # Helper function to produce the flat lists of all the child
-      # terms and names.
-      def get_all_child_lists
-        get_children
+    # Set a HTTP proxy to use
+    attr_writer :proxy
+    # Returns a HTTP proxy url.  Will read the +http_proxy+ environment variable if present
+    def proxy
+      @proxy ||= ( ENV['http_proxy'] || ENV['HTTP_PROXY'] )
+    end
-        if @all_child_terms.nil? and @all_child_names.nil?
-          @all_child_terms = []
-          @all_child_names = []
+    private
-          self.children.each do |child|
-            @all_child_terms.push( child.term )
-            @all_child_terms.push( child.all_child_terms )
-            @all_child_names.push( child.term_name )
-            @all_child_names.push( child.all_child_names )
-          end
+    # Helper function to initialize the (Savon) SOAP client
+    def setup_soap_client
+      Savon.configure do |config|
+        config.log = false unless OLS.log?
+        config.log_level = OLS.log_level
+        config.logger = OLS.logger
+      end
-          @all_child_terms = @all_child_terms.flatten.uniq
-          @all_child_names = @all_child_names.flatten.uniq
-        end
+      HTTPI.log = false unless OLS.log?
+      HTTPI.log_level = OLS.log_level
+      HTTPI.logger = OLS.logger
+      Savon::Client.new do |wsdl, http|
+        wsdl.document = "http://www.ebi.ac.uk/ontology-lookup/OntologyQuery.wsdl"
+        http.proxy = OLS.proxy unless OLS.proxy.nil?
       end
+    end
   end
 end
+directory = File.expand_path(File.dirname(__FILE__))
+require File.join(directory, 'ols', 'version')
+require File.join(directory, 'ols', 'graph')
+require File.join(directory, 'ols', 'term')