ols 0.1.0 → 0.2.0

data/History.txt

@@ -1,3 +1,7 @@
+=== 0.2.0 2011-11-07
+
+* Addition of a basic cache layer. Users can now cache regularly used ontologies on disk.
+
 === 0.1.0 2011-11-04
 
 * Total rewrite (as a result please note API changes)...

data/README.rdoc

@@ -22,24 +22,24 @@ Then, to lookup an ontology term:
   
 This will create a simple tree object for the EMAP term EMAP:3018
   
-  ont.term_id       # => "EMAP:3018"
-  ont.term_name     # => "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
-  ont.to_s          # => "EMAP:3018 - TS18,nose"
+  ont.is_root?            # => false
+  ont.is_leaf?            # => false
+  ont.to_s                # => "EMAP:3018 - TS18,nose"
 
 The graph for the term is built up (parents) and down (children) as it is requested:
 
-  ont.parents       # => Array of all parent terms objects
-  ont.children      # => Array of all direct child term objects
+  ont.parents             # => Array of all parent terms objects
+  ont.children            # => Array of all direct child term objects
 
 Alternatively, if you want to force load the graph (around this term):
 
-  ont.focus_graph!  # => Will load all parents and children into the graph
-  ont.size          # => 19
+  ont.focus_graph!        # => Will load all parents and children into the graph
+  ont.size                # => 19
 
 Find out more about your graph:
 
@@ -76,6 +76,43 @@ Visualise your graph (useful for exploring):
   #                         |---> EMAP:3021
   #
 
+More documentation can be found on the OLS module and OLS::Term rdoc pages.
+
+== Advanced Usage
+
+More to come...
+
+== Caching
+
+If you regularly hit up one or more ontology with lots of queries it might be in
+your interest to store a local on-disk copy of the entire ontology graph.  This
+will protect you against network problems and will stop you hitting OLS with many
+repeated service calls.
+
+The OLS gem has a basic caching layer built into it that allows you to store the
+entire graph for your most used ontologies on disk.  To setup/invoke the cache, do
+the following:
+
+  OLS.setup_cache({ :directory => '/tmp/ols_cache' })
+
+This will create a cache directory (/tmp/ols_cache) if it does not exist, or read in
+configuration files etc if it is an already existing OLS cache directory. If you do not
+pass in a configuration hash it will use the current working directory by default.
+
+Now, to add an ontology to the cache, you do the following:
+
+  OLS.add_ontology_to_cache("EMAP")
+
+This will add the entire EMAP ontology graph to the cache (this will take a while) - now
+all calls for EMAP terms will go via the cache, all other queries will still call the OLS web
+services.  (There is no dynamic cache build-up over time).
+
+To remove an ontology graph from the cache:
+
+  OLS.remove_ontology_from_cache("EMAP")
+
+Different cache back-ends and other features will be built into future releases.
+
 == Meta
 
 Written by Darren Oakley (daz dot oakley at gmail dot com)

data/lib/ols.rb

@@ -82,17 +82,23 @@ module OLS
     # @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)
+      term = nil
+
+      term = @cache.find_by_id(term_id) if using_cache?
+
+      if term.nil?
+        term_name = request(:get_term_by_id) { soap.body = { :termId => term_id } }
+        raise TermNotFoundError if term_name.eql?(term_id)
+        term = OLS::Term.new(term_id,term_name)
+      end
+
+      term
     end
 
     # Set whether to log HTTP requests - pass in +true+ or +false+
     attr_writer :log
 
     # Returns whether to log HTTP/SOAP requests. Defaults to +false+
-    #
-    # @return [Boolean] To log or not to log, that is the question...
     def log?
       @log ? true : false
     end
@@ -121,6 +127,56 @@ module OLS
       @proxy ||= ( ENV['http_proxy'] || ENV['HTTP_PROXY'] )
     end
 
+    # Are we using a local cache? Defaults to +false+.
+    # @see #setup_cache
+    # @since 0.2.0
+    def using_cache?
+      @cache ? true : false
+    end
+
+    # Configure the OLS gem to use a local cache. Useful if you have some serious ontology
+    # activity going on, or you want to insulate yourself from server outages and the like.
+    #
+    # *NOTE:* We only support a file-based (on-disk) cache at the moment. By default it will
+    # look in/use the current working directory, or you can pass a configuration hash as follows:
+    #
+    #   OLS.setup_cache({ :directory => '/path/to/cache_directory' })
+    #
+    # Support for other cache backends will come in future builds.
+    #
+    # @since 0.2.0
+    def setup_cache(options={})
+      @cache = OLS::Cache.new(options)
+    end
+
+    # Returns a list of the cached ontologies.
+    #
+    # @return [Array] A list of the cached ontologies
+    # @since 0.2.0
+    def cached_ontologies
+      @cache.cached_ontologies
+    end
+
+    # Add an ontology to the cache.
+    #
+    # @param [String] ontology The ontology to add
+    # @raise [ArgumentError] Raised if the ontology is not part of OLS
+    # @since 0.2.0
+    def add_ontology_to_cache(ontology)
+      @cache.add_ontology_to_cache(ontology)
+    end
+
+    alias :refresh_ontology_in_cache :add_ontology_to_cache
+
+    # Remove an ontology from the cache.
+    #
+    # @param [String] ontology The ontology to remove
+    # @raise [ArgumentError] Raised if the ontology is not part of OLS
+    # @since 0.2.0
+    def remove_ontology_from_cache(ontology)
+      @cache.remove_ontology_from_cache(ontology)
+    end
+
     private
 
     # Helper function to initialize the (Savon) SOAP client
@@ -148,3 +204,4 @@ 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')
+require File.join(directory, 'ols', 'cache')

data/lib/ols/cache.rb

@@ -0,0 +1,120 @@
+# encoding: utf-8
+
+module OLS
+
+  # Utility class responsible for handling caching in the OLS gem.  You should *NOT* 
+  # really interact with instances of this class directly, use the methods on the OLS 
+  # module and the resulting OLS::Term objects.
+  #
+  # @author Darren Oakley (https://github.com/dazoakley)
+  class Cache
+    # Creates a new OLS::Cache object and scans the cache directory for cached terms.
+    def initialize(args={})
+      options = { :directory => Dir.getwd }.merge(args)
+      @cache_directory = options[:directory]
+
+      prepare_cache
+    end
+
+    # Pull an OLS::Term object out of the cache.  Returns +nil+ if the term is not found.
+    #
+    # @param [String] term_id The ontology term_id to look up
+    # @return [OLS::Term] The found OLS::Term object or +nil+
+    def find_by_id(term_id)
+      found_term = nil
+      filename = @term_id_to_files[term_id].to_s
+
+      unless filename.nil? || filename.empty?
+        Dir.chdir(@cache_directory) do
+          root_term = Marshal.load( File.open(filename) )
+          found_term = root_term.send(:find_in_graph,term_id)
+        end
+      end
+
+      found_term
+    end
+
+    # Returns a list of the cached ontologies.
+    #
+    # @return [Array] A list of the cached ontologies
+    def cached_ontologies
+      @cached_ontologies.keys
+    end
+
+    # Add an ontology to the cache.
+    #
+    # @param [String] ontology The ontology to add
+    # @raise [ArgumentError] Raised if the ontology is not part of OLS
+    def add_ontology_to_cache(ontology)
+      raise ArgumentError, "'#{ontology}' is not a valid OLS ontology" unless OLS.ontologies.include?(ontology)
+
+      new_filenames = []
+
+      Dir.chdir(@cache_directory) do
+        OLS.root_terms(ontology).each do |term|
+          term_filename = "#{term.term_id.gsub(':','')}.marshal"
+          term.focus_graph!
+          File.open("#{term_filename}",'w') { |f| f << Marshal.dump(term) }
+          @cached_ontologies[ontology] ||= { :filenames => [], :date => Date.today }
+          @cached_ontologies[ontology][:filenames].push(term_filename) unless @cached_ontologies[ontology][:filenames].include? term_filename
+          new_filenames.push(term_filename)
+        end
+      end
+
+      @cached_ontologies[ontology][:filenames].delete_if { |file| !new_filenames.include?(file) }
+
+      write_cached_ontologies_to_disk
+      prepare_cache
+    end
+
+    alias :refresh_ontology_in_cache :add_ontology_to_cache
+
+    # Remove an ontology from the cache.
+    #
+    # @param [String] ontology The ontology to remove
+    # @raise [ArgumentError] Raised if the ontology is not part of OLS
+    def remove_ontology_from_cache(ontology)
+      raise ArgumentError, "'#{ontology}' is not part of the cache" unless OLS.ontologies.include?(ontology)
+
+      Dir.chdir(@cache_directory) do
+        @cached_ontologies[ontology][:filenames].each do |file|
+          File.delete(file)
+        end
+      end
+
+      @cached_ontologies.delete(ontology)
+
+      write_cached_ontologies_to_disk
+      prepare_cache
+    end
+
+    private
+
+    # writes the @cached_ontologies variable to disk
+    def write_cached_ontologies_to_disk
+      Dir.chdir(@cache_directory) do
+        File.open('cached_ontologies.yaml','w') { |f| f << @cached_ontologies.to_yaml }
+      end
+    end
+
+    # Utility function to prepare the cache.
+    def prepare_cache
+      @cached_ontologies = {}
+      @term_id_to_files = {}
+
+      Dir.mkdir(@cache_directory) unless Dir.exists?(@cache_directory)
+      Dir.chdir(@cache_directory) do
+        @cached_ontologies = YAML.load( File.open('cached_ontologies.yaml') ) if File.exists?('cached_ontologies.yaml')
+
+        @cached_ontologies.each do |ontology,details|
+          details[:filenames].each do |filename|
+            root_term = Marshal.load( File.open(filename) )
+            next unless root_term.is_a? OLS::Term
+            @term_id_to_files[ root_term.term_id ] = filename.to_sym
+            root_term.all_child_ids.each { |term_id| @term_id_to_files[term_id] = filename.to_sym }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ols/graph.rb

@@ -3,7 +3,8 @@
 module OLS
 
   # Utility class for representing an ontology graph. You should *NOT* really interact with
-  # instances of this class directly, use OLS.find_by_id etc.
+  # instances of this class directly, use the methods on the OLS module and the resulting 
+  # OLS::Term objects.
   #
   # @author Darren Oakley (https://github.com/dazoakley)
   class Graph

data/lib/ols/term.rb

@@ -13,6 +13,9 @@ module OLS
     # @param [String] term_id The ontology term id
     # @param [String] term_name The ontology term name
     def initialize(term_id,term_name,graph=nil)
+      raise ArgumentError, "term_id cannot be empty/nil" if term_id.nil? || term_id =~ /^\s$/
+      raise ArgumentError, "term_name cannot be empty/nil" if term_name.nil? || term_name =~ /^\s$/
+
       @term_id   = term_id
       @term_name = term_name
 

data/lib/ols/version.rb

@@ -2,5 +2,5 @@
 
 module OLS
   # OLS::VERSION - The OLS gem version
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/test/fixtures/cached_ontologies.yaml

@@ -0,0 +1,9 @@
+---
+EMAP:
+  :filenames:
+  - EMAP0.marshal
+  :date: 2011-11-07
+MP:
+  :filenames:
+  - MP0000001.marshal
+  :date: 2011-11-07

data/test/test_ols_cache.rb

@@ -0,0 +1,106 @@
+require 'test_helper'
+
+class OLSTermTest < Test::Unit::TestCase
+  context 'An OLS::Cache object' do
+    setup do
+      @cache_directory = "#{File.expand_path(File.dirname(__FILE__))}/fixtures"
+      OLS.setup_cache({ :directory => @cache_directory })
+
+      if OLS.cached_ontologies.include?('TRANS')
+        Dir.chdir(@cache_directory) do
+          Dir.glob('TRANS*').each do |file|
+            File.delete(file)
+          end
+          File.open('cached_ontologies.yaml','w') do |file|
+            file << { 'EMAP' => ['EMAP0.marshal'], 'MP' => ['MP0000001.marshal'] }.to_yaml
+          end
+        end
+        OLS.setup_cache({ :directory => @cache_directory })
+      end
+    end
+
+    teardown do
+      OLS.instance_variable_set(:@cache,nil)
+    end
+
+    should 'read in a fixture/cache directory of marshalled objects upon initialisation' do
+      cache = OLS.instance_variable_get(:@cache)
+      assert cache.is_a? OLS::Cache
+      assert OLS.using_cache?
+      assert cache.instance_variable_get(:@term_id_to_files).size > 10000
+    end
+
+    should 'be able to access ontology data without connecting to the OLS service' do
+      OLS.stubs(:request).returns(nil)
+
+      assert_respond_to OLS.instance_variable_get(:@cache), :find_by_id
+
+      emap_term = OLS.find_by_id('EMAP:3018')
+
+      assert emap_term.is_a? OLS::Term
+      assert_equal 'EMAP:3018', emap_term.term_id
+      assert_equal 'EMAP:0', emap_term.root.term_id
+      assert_equal 13731, emap_term.size
+
+      # Also check that we can re-request the terms easily without object bumping into each other...
+      emap_term2 = OLS.find_by_id('EMAP:3018')
+      emap_term.focus_graph!
+
+      assert_equal 19, emap_term.size
+      assert_equal 13731, emap_term2.size
+
+      OLS.unstub(:request)
+    end
+
+    should 'not get in the way when we request something that is not in the cache' do
+      VCR.use_cassette('test_ols_cache') do
+        assert_equal nil, OLS.instance_variable_get(:@cache).instance_variable_get(:@term_id_to_files)['GO:0008150']
+
+        biological_process = OLS.find_by_id('GO:0008150')
+
+        assert biological_process.is_a? OLS::Term
+        assert biological_process.is_root?
+        assert_equal false, biological_process.is_leaf?
+        assert_equal 28, biological_process.children.size
+      end
+    end
+
+    should 'setup/manage cached objects for the user' do
+      Dir.chdir(@cache_directory) do
+        files = Dir.glob('*')
+        assert files.include?('cached_ontologies.yaml')
+        assert_equal false, files.include?('TRANS0000000.marshal')
+      end
+
+      VCR.use_cassette('test_ols_cache') do
+        # list cached ontologies
+        assert OLS.cached_ontologies.is_a? Array
+        assert OLS.cached_ontologies.include? 'EMAP'
+        assert OLS.cached_ontologies.include? 'MP'
+
+        # add a new ontology to the cache
+        assert OLS.ontologies.keys.include? 'TRANS'
+        OLS.add_ontology_to_cache('TRANS')
+        assert OLS.cached_ontologies.include? 'TRANS'
+
+        Dir.chdir(@cache_directory) do
+          files = Dir.glob('*')
+          assert files.include?('TRANS0000000.marshal')
+        end
+      end
+
+      trans = OLS.find_by_id('TRANS:0000000')
+      assert_equal 25, trans.size
+
+      VCR.use_cassette('test_ols_cache') do
+        # remove an ontology from the cache
+        OLS.remove_ontology_from_cache('TRANS')
+        assert_equal false, OLS.cached_ontologies.include?('TRANS')
+        Dir.chdir(@cache_directory) do
+          files = Dir.glob('*')
+          assert_equal false, files.include?('TRANS0000000.marshal')
+        end
+      end
+    end
+  end
+end

data/test/test_ols_term.rb

@@ -397,9 +397,7 @@ class OLSTermTest < Test::Unit::TestCase
         OLS.stubs(:request).returns(nil)
 
         # check the stubbing is okay...
-        foo = OLS.find_by_id('EMAP:3003')
-        foo.focus_graph!
-        assert_equal 1, foo.size
+        assert_raise(ArgumentError) { foo = OLS.find_by_id('EMAP:3003') }
 
         # now get on with testing marshal...
         data = Marshal.dump(@emap_term)
@@ -423,9 +421,7 @@ class OLSTermTest < Test::Unit::TestCase
         require 'yaml'
 
         # check the stubbing is okay...
-        foo = OLS.find_by_id('EMAP:3003')
-        foo.focus_graph!
-        assert_equal 1, foo.size
+        assert_raise(ArgumentError) { foo = OLS.find_by_id('EMAP:3003') }
 
         # now get on with testing yaml...
         data = @emap_term.to_yaml

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ols
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-11-04 00:00:00.000000000 Z
+date: 2011-11-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: savon
-  requirement: &2152733760 !ruby/object:Gem::Requirement
+  requirement: &2152592920 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2152733760
+  version_requirements: *2152592920
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &2152733260 !ruby/object:Gem::Requirement
+  requirement: &2152592420 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152733260
+  version_requirements: *2152592420
 - !ruby/object:Gem::Dependency
   name: shoulda
-  requirement: &2152732720 !ruby/object:Gem::Requirement
+  requirement: &2152591680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152732720
+  version_requirements: *2152591680
 - !ruby/object:Gem::Dependency
   name: vcr
-  requirement: &2152731500 !ruby/object:Gem::Requirement
+  requirement: &2152590620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152731500
+  version_requirements: *2152590620
 - !ruby/object:Gem::Dependency
   name: webmock
-  requirement: &2152730520 !ruby/object:Gem::Requirement
+  requirement: &2152589180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152730520
+  version_requirements: *2152589180
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &2152728460 !ruby/object:Gem::Requirement
+  requirement: &2152587220 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152728460
+  version_requirements: *2152587220
 - !ruby/object:Gem::Dependency
   name: simplecov-rcov
-  requirement: &2152727120 !ruby/object:Gem::Requirement
+  requirement: &2152585760 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,10 +87,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152727120
+  version_requirements: *2152585760
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &2152725360 !ruby/object:Gem::Requirement
+  requirement: &2152584200 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -98,7 +98,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152725360
+  version_requirements: *2152584200
 description: ! "\n    OLS provides a simple interface to the EBI's Ontology Lookup
   Service (http://www.ebi.ac.uk/ontology-lookup/).\n    It provides an easy lookup
   of ontology terms and automagically builds up ontology trees for you.\n  "
@@ -114,13 +114,18 @@ files:
 - README.rdoc
 - Rakefile
 - lib/ols.rb
+- lib/ols/cache.rb
 - lib/ols/graph.rb
 - lib/ols/term.rb
 - lib/ols/version.rb
 - ols.gemspec
 - script/console
+- test/fixtures/EMAP0.marshal
+- test/fixtures/MP0000001.marshal
+- test/fixtures/cached_ontologies.yaml
 - test/test_helper.rb
 - test/test_ols.rb
+- test/test_ols_cache.rb
 - test/test_ols_graph.rb
 - test/test_ols_term.rb
 homepage: https://github.com/dazoakley/ols
@@ -148,8 +153,12 @@ signing_key:
 specification_version: 3
 summary: A simple wrapper around the EBI's Ontology Lookup Service (OLS)
 test_files:
+- test/fixtures/EMAP0.marshal
+- test/fixtures/MP0000001.marshal
+- test/fixtures/cached_ontologies.yaml
 - test/test_helper.rb
 - test/test_ols.rb
+- test/test_ols_cache.rb
 - test/test_ols_graph.rb
 - test/test_ols_term.rb
 has_rdoc: