biomart 0.1.5 → 0.2.0

data/History.txt

@@ -1,3 +1,10 @@
+=== 0.2.0 2010-06-10
+
+* 2 major enhancements:
+  * Added the ability to perform federated queries across two datasets.
+  * Added the option to discard rows of data if a specified list of
+    fields are not present.
+
 === 0.1.5 2010-02-04
 
 * 1 major bugfix:

data/Manifest.txt

@@ -12,7 +12,7 @@ lib/biomart/server.rb
 script/console
 script/destroy
 script/generate
-tasks/metrics.task
-tasks/shoulda.task
+tasks/metrics.rake
+tasks/shoulda.rake
 test/test_biomart.rb
 test/test_helper.rb

data/README.rdoc

@@ -79,7 +79,57 @@ just get on with things...
   # etc. etc.
   
 See Biomart module and Class docs for more detail.
+
+== Federated Searches
+
+To perform a federated search across two datasets...
+
+  htgt = Biomart::Server.new( "http://www.sanger.ac.uk/htgt/biomart" )
+
+  res = htgt.datasets["htgt_targ"].search(
+    :filters => {
+      "status"     => [
+        "Mice - Genotype confirmed",
+        "Mice - Germline transmission",
+        "Mice - Microinjection in progress",
+        "ES Cells - Targeting Confirmed"
+      ]
+    },
+    :attributes => [
+      "marker_symbol",
+      "mgi_accession_id",
+      "status"
+    ],
+    :federate => [
+      {
+        :dataset => htgt.datasets["mmusculus_gene_ensembl"],
+        :filters => {
+          "chromosome_name" => "1",
+          "start"           => "1",
+          "end"             => "10000000"
+        },
+        :attributes => []
+      }
+    ]
+  )
   
+The above will perform a federated query for all genes with available 
+mice knockout es cells in the first 10Mb of chromosome 1 from the IKMC 
+projects (not really important, but it's an example of a complex query).
+
+The basic search arguments are the same as if we were searching across 
+a single dataset, with the addition of the :federate option, which is 
+an array of hashes for each dataset (and additional filters/attributes) 
+that we want to federate our search with.
+
+Note: at present you can only federate across two datasets, this is 
+limitation in the current stable release of biomart (0.7).  If you try 
+federate across more than two datasets, a Biomart::ArgumentError will 
+be raised.  This limitation shall be removed from this API when it is 
+possible to federate across more than two datasets in biomart itself.
+
+Count queries are only allowed on single datasets.
+
 == Using a Proxy
 
 If you need to channel all of your requests via a proxy, specify your 

data/Rakefile

@@ -1,5 +1,8 @@
 require "rubygems"
+
+gem "flog", "= 2.2.0"
 gem "hoe", ">= 2.1.0"
+
 require "hoe"
 require "fileutils"
 require "./lib/biomart"
@@ -15,14 +18,14 @@ $hoe = Hoe.spec "biomart" do
   self.rubyforge_name   = self.name
   self.url              = "http://github.com/dazoakley/biomart"
   self.summary          = "A ruby API for interacting with Biomart services."
-  self.description      = "A ruby API for interacting with Biomart services."
+  self.description      = "A ruby API for interacting with Biomart XML based webservices."
   self.extra_deps       = [["builder",">= 0"]]
-  self.extra_dev_deps   = [["thoughtbot-shoulda",">=0"]]
+  self.extra_dev_deps   = [["shoulda",">= 2.10"]]
   self.extra_rdoc_files = ["README.rdoc"]
 end
 
 require "newgem/tasks"
-Dir["tasks/*.task"].each { |t| load t }
+Dir["tasks/*.rake"].each { |t| load t }
 
 # TODO - want other tests/tasks run by default? Add them to the list
 # remove_task :default

data/biomart.gemspec

@@ -2,12 +2,12 @@
 
 Gem::Specification.new do |s|
   s.name = %q{biomart}
-  s.version = "0.1.5"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Darren Oakley"]
-  s.date = %q{2010-02-04}
-  s.description = %q{A ruby API for interacting with Biomart services.}
+  s.date = %q{2010-06-10}
+  s.description = %q{A ruby API for interacting with Biomart XML based webservices.}
   s.email = ["daz.oakley@gmail.com"]
   s.extra_rdoc_files = ["History.txt", "Manifest.txt", "README.rdoc"]
   s.files = ["History.txt", "Manifest.txt", "README.rdoc", "Rakefile", "biomart.gemspec", "lib/biomart.rb", "lib/biomart/attribute.rb", "lib/biomart/database.rb", "lib/biomart/dataset.rb", "lib/biomart/filter.rb", "lib/biomart/server.rb", "script/console", "script/destroy", "script/generate", "tasks/metrics.task", "tasks/shoulda.task", "test/test_biomart.rb", "test/test_helper.rb"]
@@ -15,7 +15,7 @@ Gem::Specification.new do |s|
   s.rdoc_options = ["--main", "README.rdoc"]
   s.require_paths = ["lib"]
   s.rubyforge_project = %q{biomart}
-  s.rubygems_version = %q{1.3.5}
+  s.rubygems_version = %q{1.3.7}
   s.summary = %q{A ruby API for interacting with Biomart services.}
   s.test_files = ["test/test_biomart.rb", "test/test_helper.rb"]
 
@@ -23,14 +23,18 @@ Gem::Specification.new do |s|
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<builder>, [">= 0"])
-      s.add_development_dependency(%q<thoughtbot-shoulda>, [">= 0"])
-      s.add_development_dependency(%q<hoe>, [">= 2.3.3"])
+      s.add_development_dependency(%q<shoulda>, [">= 2.10"])
+      s.add_development_dependency(%q<hoe>, [">= 2.6.1"])
     else
       s.add_dependency(%q<builder>, [">= 0"])
+      s.add_dependency(%q<shoulda>, [">= 2.10"])
+      s.add_dependency(%q<hoe>, [">= 2.6.1"])
     end
   else
     s.add_dependency(%q<builder>, [">= 0"])
+    s.add_dependency(%q<shoulda>, [">= 2.10"])
+    s.add_dependency(%q<hoe>, [">= 2.6.1"])
   end
 end

data/lib/biomart.rb

@@ -1,21 +1,14 @@
 require "uri"
 require "net/http"
+require "cgi"
 require "rexml/document"
 require "csv"
 
 require "rubygems"
 require "builder"
 
-#begin
-#  require "curb"
-#  use_curb = true
-#rescue LoadError
-#  use_curb = false
-#end
-#CURB_AVAILABLE = use_curb
-
 module Biomart
-  VERSION = "0.1.5"
+  VERSION = "0.2.0"
   
   # This is the base Biomart error/exception class. Rescue it if 
   # you want to catch any exceptions that this code might raise.
@@ -46,76 +39,49 @@ module Biomart
   # dataset.
   class DatasetError   < BiomartError; end
   
+  # Error class representing errors in the arguments being passed 
+  # to the api.
+  class ArgumentError < BiomartError; end
+  
   # Centralised request function for handling all of the HTTP requests 
   # to the biomart servers.
   def request( params={} )
-    net_http_request(params)
+    if params[:url] =~ / /
+      params[:url].gsub!(" ","+")
+    end
+    
+    uri          = URI.parse( params[:url] )
+    client       = net_http_client()
+    req          = nil
+    response     = nil
+    
+    case params[:method]
+    when 'post'
+      req           = Net::HTTP::Post.new(uri.path)
+      req.form_data = { "query" => params[:query] }
+    else
+      req           = Net::HTTP::Get.new(uri.request_uri)
+    end
+    
+    client.start(uri.host, uri.port) do |http|
+      if Biomart.timeout or params[:timeout]
+        http.read_timeout = params[:timeout] ? params[:timeout] : Biomart.timeout
+        http.open_timeout = params[:timeout] ? params[:timeout] : Biomart.timeout
+      end
+      response = http.request(req)
+    end
     
-    #if CURB_AVAILABLE and ( Biomart.use_net_http != true )
-    #  curb_request(params)
-    #else
-    #  net_http_request(params)
-    #end
+    check_response( response.body, response.code )
+    
+    return response.body
   end
   
   class << self
-    attr_accessor :proxy, :timeout, :use_net_http
+    attr_accessor :proxy, :timeout
   end
   
   private
     
-    # Utility function to perform the request method using the curb 
-    # gem (a wrapper around libcurl) - supposed to be faster than 
-    # Net::HTTP.
-    def curb_request( params={} )
-      client = Curl::Easy.new( params[:url] )
-      
-      if Biomart.timeout or params[:timeout]
-        client.connect_timeout = params[:timeout] ? params[:timeout] : Biomart.timeout
-      end
-      
-      if proxy_url() then client.proxy_url = proxy_url() end
-      
-      case params[:method]
-      when 'post'
-        client.http_post( Curl::PostField.content( "query", params[:query], "text/xml" ) )
-      else
-        client.http_get
-      end
-      
-      check_response( client.body_str, client.response_code )
-      
-      return client.body_str
-    end
-    
-    # Utility function to perform the request method using Net::HTTP.
-    def net_http_request( params={} )
-      uri          = URI.parse( params[:url] )
-      client       = net_http_client()
-      req          = nil
-      response     = nil
-
-      case params[:method]
-      when 'post'
-        req           = Net::HTTP::Post.new(uri.path)
-        req.form_data = { "query" => params[:query] }
-      else
-        req           = Net::HTTP::Get.new(uri.request_uri)
-      end
-
-      client.start(uri.host, uri.port) do |http|
-        if Biomart.timeout or params[:timeout]
-          http.read_timeout = params[:timeout] ? params[:timeout] : Biomart.timeout
-          http.open_timeout = params[:timeout] ? params[:timeout] : Biomart.timeout
-        end
-        response = http.request(req)
-      end
-
-      check_response( response.body, response.code )
-
-      return response.body
-    end
-    
     # Utility function to create a Net::HTTP object.
     def net_http_client
       client = Net::HTTP

data/lib/biomart/attribute.rb

@@ -2,13 +2,26 @@ module Biomart
   # Class representation for a biomart attribute. 
   # Will belong to a Biomart::Dataset.
   class Attribute
-    attr_reader :name, :display_name, :default
+    attr_reader :name, :display_name
     
     def initialize(args)
       @name         = args["internalName"]
       @display_name = args["displayName"]
       @default      = args["default"] ? true : false
+      @hidden       = args["hideDisplay"] ? true : false
     end
     
+    # Convenience method to see if this attribute is hidden from 
+    # the standard MartView interface.  Returns true/false.
+    def hidden?
+      @hidden
+    end
+    
+    # Convenience method to see if this attribute would be 
+    # enabled by default in the standard MartView interface.
+    # Returns true/false.
+    def default?
+      @default
+    end
   end
 end

data/lib/biomart/database.rb

@@ -36,6 +36,12 @@ module Biomart
       return @datasets
     end
     
+    # Returns true / false if this database is visbile in the 
+    # default MartView interface.
+    def visible?
+      @visible
+    end
+    
     private
     
       # Utility method to do the webservice call to the biomart server 

data/lib/biomart/dataset.rb

@@ -62,10 +62,20 @@ module Biomart
     # the result of the count query.
     #
     # optional arguments:
-    #
-    # :filters::         hash of key-value pairs (filter => search term)
-    # :timeout::         set a timeout length for the request (secs)
+    # 
+    #   {
+    #     :timeout => integer,     # set a timeout length for the request (secs)
+    #     :filters => {}           # hash of key-value pairs (filter => search term)
+    #   }
     def count( args={} )
+      if args[:federate]
+        raise Biomart::ArgumentError, "You cannot federate a count query."
+      end
+      
+      if args[:required_attributes]
+        raise Biomart::ArgumentError, "The :required_attributes option is not allowed on count queries."
+      end
+      
       result = request(
         :method  => 'post',
         :url     => @url,
@@ -82,30 +92,51 @@ module Biomart
     # Function to perform a Biomart search.
     # 
     # optional arguments:
+    # 
+    #   {
+    #     :process_results     => true/false,   # convert search results to object
+    #     :timeout             => integer,      # set a timeout length for the request (secs)
+    #     :filters             => {},           # hash of key-value pairs (filter => search term)
+    #     :attributes          => [],           # array of attributes to retrieve
+    #     :required_attributes => [],           # array of attributes that are required
+    #     :federate => [
+    #       {
+    #         :dataset    => Biomart::Dataset, # A dataset object to federate with
+    #         :filters    => {},               # hash of key-value pairs (filter => search term)
+    #         :attributes => []                # array of attributes to retrieve
+    #       }
+    #     ]
+    #   }
+    #
+    # Note, if you do not pass any filters or attributes arguments, the defaults 
+    # for the dataset shall be used.
     #
-    # :filters::         hash of key-value pairs (filter => search term)
-    # :attributes::      array of attributes to retrieve
-    # :process_results:: true/false - convert search results to object
-    # :timeout::         set a timeout length for the request (secs)
+    # Also, using the :required_attributes option - this performs AND logic and will require 
+    # data to be returned in all of the listed attributes in order for it to be returned.
     #
     # By default will return a hash with the following:
     # 
-    # :headers::        array of headers
-    # :data::           array of arrays containing search results
+    #   {
+    #     :headers => [],   # array of headers
+    #     :data    => []    # array of arrays containing search results
+    #   }
     #
     # But with the :process_results option will return an array of hashes, 
     # where each hash represents a row of results (keyed by the attribute name).
     def search( args={} )
+      if args[:required_attributes] and !args[:required_attributes].is_a?(Array)
+        raise Biomart::ArgumentError, "The :required_attributes option must be passed as an array."
+      end
+      
       response = request(
         :method  => 'post',
         :url     => @url,
         :timeout => args[:timeout],
-        :query   => generate_xml(
-          :filters    => args[:filters],
-          :attributes => args[:attributes]
-        )
+        :query   => generate_xml( process_xml_args(args) )
       )
+      
       result = process_tsv( args, response )
+      result = filter_data_rows( args, result ) if args[:required_attributes]
       result = conv_results_to_a_of_h( result ) if args[:process_results]
       return result
     end
@@ -118,38 +149,22 @@ module Biomart
       xml.instruct!
       xml.declare!( :DOCTYPE, :Query )
       xml.Query( :virtualSchemaName => "default", :formatter => "TSV", :header => "0", :uniqueRows => "1", :count => args[:count], :datasetConfigVersion => "0.6" ) {
-        xml.Dataset( :name => @name, :interface => "default" ) {
-          
-          if args[:filters]
-            args[:filters].each do |name,value|
-              if value.is_a? Array
-                value = value.join(",")
-              end
-              xml.Filter( :name => name, :value => value )
-            end
-          else
-            self.filters.each do |name,filter|
-              if filter.default
-                xml.Filter( :name => name, :value => filter.default_value )
-              end
-            end
-          end
-          
-          unless args[:count]
-            if args[:attributes]
-              args[:attributes].each do |name|
-                xml.Attribute( :name => name )
-              end
-            else
-              self.attributes.each do |name,attribute|
-                if attribute.default
-                  xml.Attribute( :name => name )
-                end
-              end
+        dataset_xml( xml, self, { :filters => args[:filters], :attributes => args[:attributes] } )
+        
+        if args[:federate]
+          args[:federate].each do |joined_dataset|
+            unless joined_dataset[:dataset].is_a?(Biomart::Dataset)
+              raise Biomart::ArgumentError, "You must pass a Biomart::Dataset object to the :federate[:dataset] option."
             end
+            
+            dataset_xml(
+              xml,
+              joined_dataset[:dataset],
+              { :filters => joined_dataset[:filters], :attributes => joined_dataset[:attributes] }
+            )
           end
-          
-        }
+        end
+        
       }
       
       return biomart_xml
@@ -190,21 +205,77 @@ module Biomart
         end
       end
       
+      # Utility function to process and test the arguments passed for 
+      # the xml query.
+      def process_xml_args( args={} )
+        xml_args = {
+          :filters    => args[:filters],
+          :attributes => args[:attributes]
+        }
+
+        if args[:federate]
+          unless args[:federate].is_a?(Array)
+            raise Biomart::ArgumentError, "The :federate option must be passed as an array."
+          end
+
+          unless args[:federate].size == 1
+            raise Biomart::ArgumentError, "Sorry, we can only federate two datasets at present.  This limitation shall be lifted in version 0.8 of biomart."
+          end
+
+          xml_args[:federate] = args[:federate]
+        end
+
+        return xml_args
+      end
+      
+      # Helper function to produce the portion of the biomart xml for 
+      # a dataset query.
+      def dataset_xml( xml, dataset, args )
+        xml.Dataset( :name => dataset.name, :interface => "default" ) {
+
+          if args[:filters]
+            args[:filters].each do |name,value|
+              if value.is_a? Array
+                value = value.join(",")
+              end
+              xml.Filter( :name => name, :value => value )
+            end
+          else
+            dataset.filters.each do |name,filter|
+              if filter.default?
+                xml.Filter( :name => name, :value => filter.default_value )
+              end
+            end
+          end
+
+          unless args[:count]
+            if args[:attributes]
+              args[:attributes].each do |name|
+                xml.Attribute( :name => name )
+              end
+            else
+              dataset.attributes.each do |name,attribute|
+                if attribute.default?
+                  xml.Attribute( :name => name )
+                end
+              end
+            end
+          end
+
+        }
+      end
+      
       # Utility function to transform the tab-separated data retrieved 
       # from the Biomart search query into a ruby object.
       def process_tsv( args, tsv )
         headers     = []
         parsed_data = []
+        
+        append_header_attributes_for_tsv( headers, self, args[:attributes] )
 
-        if args[:attributes]
-          args[:attributes].each do |attribute|
-            headers.push(attribute)
-          end
-        else
-          self.attributes.each do |name,attribute|
-            if attribute.default
-              headers.push(name)
-            end
+        if args[:federate]
+          args[:federate].each do |joined_dataset|
+            append_header_attributes_for_tsv( headers, joined_dataset[:dataset], joined_dataset[:attributes] )
           end
         end
 
@@ -231,6 +302,22 @@ module Biomart
         }
       end
       
+      # Helper function to append the attribute names to the 'headers' array 
+      # for processing the returned results.
+      def append_header_attributes_for_tsv( headers, dataset, attributes )
+        if attributes
+          attributes.each do |attribute|
+            headers.push(attribute)
+          end
+        else
+          dataset.attributes.each do |name,attribute|
+            if attribute.default?
+              headers.push(name)
+            end
+          end
+        end
+      end
+      
       # Utility function to process TSV formatted data that raises errors. (Biomart 
       # has a habit of serving out this...) First attempts to use the CSV modules 
       # 'parse_line' function to read in the data, if that fails, tries to use split 
@@ -301,6 +388,46 @@ module Biomart
 
         return result_objects
       end
-    
+      
+      # Utility function to remove data rows from a search result that do not include 
+      # the :required_attributes.
+      def filter_data_rows( args, result )
+        # Get the list of attributes searched for...
+        attributes = args[:attributes] ? args[:attributes] : []
+        if attributes.empty?
+          self.attributes.each do |name,attribute|
+            if attribute.default?
+              attributes.push(name)
+            end
+          end
+        end
+
+        # Work out which attribute positions we need to test...
+        positions_to_test = []
+        attributes.each_index do |index|
+          if args[:required_attributes].include?(attributes[index])
+            positions_to_test.push(index)
+          end
+        end
+
+        # Now go through the results and filter out the unwanted data...
+        filtered_data = []
+        result[:data].each do |data_row|
+          save_row_count = 0
+
+          positions_to_test.each do |position|
+            save_row_count = save_row_count + 1 unless data_row[position].nil?
+          end
+
+          if save_row_count == positions_to_test.size
+            filtered_data.push(data_row)
+          end
+        end
+
+        return {
+          :headers => result[:headers],
+          :data    => filtered_data
+        }
+      end
   end
 end

data/lib/biomart/filter.rb

@@ -2,14 +2,36 @@ module Biomart
   # Class representation for a biomart filter. 
   # Will belong to a Biomart::Dataset.
   class Filter
-    attr_reader :name, :display_name, :default, :default_value
+    attr_reader :name, :display_name, :default_value, :qualifier, :type
     
     def initialize(args)
-      @name          = args["internalName"]
-      @display_name  = args["displayName"]
-      @default       = args["defaultOn"] ? true : false
-      @default_value = args["defaultValue"]
+      @name            = args["internalName"]
+      @display_name    = args["displayName"]
+      @default         = args["defaultOn"] ? true : false
+      @default_value   = args["defaultValue"]
+      @hidden          = args["hideDisplay"] ? true : false
+      @qualifier       = args["qualifier"]
+      @type            = args["type"]
+      @multiple_values = args["multipleValues"] ? true : false
     end
     
+    # Convenience method to see if this filter is hidden from 
+    # the standard MartView interface.  Returns true/false.
+    def hidden?
+      @hidden
+    end
+    
+    # Convenience method to see if this filter would be 
+    # enabled by default in the standard MartView interface.
+    # Returns true/false.
+    def default?
+      @default
+    end
+    
+    # Convenience method to see if this filter allows multiple 
+    # values to be passed to it.
+    def multiple_values?
+      @multiple_values
+    end
   end
 end

data/lib/biomart/server.rb

@@ -73,9 +73,7 @@ module Biomart
         url = @url + '?type=registry'
         document = REXML::Document.new( request( :url => url ) )
         REXML::XPath.each( document, "//MartURLLocation" ) do |d|
-          if d.attributes["visible"] === "1"
-            @databases[ d.attributes["name"] ] = Database.new( @url, d.attributes )
-          end
+          @databases[ d.attributes["name"] ] = Database.new( @url, d.attributes )
         end
       end
       

data/test/test_biomart.rb

@@ -26,9 +26,11 @@ class BiomartTest < Test::Unit::TestCase
     end
     
     should "have basic metadata" do
+      true_false  = [true,false]
       assert( @htgt_database.display_name, "Biomart::Database does not have a 'display name'." )
       assert( @htgt_database.name, "Biomart::Database does not have a 'name'." )
       assert( @htgt_database.visible != nil, "Biomart::Database does not have a 'visible' flag." )
+      assert( true_false.include?( @htgt_database.visible? ), "Biomart::Database.visible? is not returning true/false." )
     end
     
     should "have datasets" do
@@ -43,7 +45,9 @@ class BiomartTest < Test::Unit::TestCase
       @htgt_targ = @htgt.datasets["htgt_targ"]
       @htgt_trap = @htgt.datasets["htgt_trap"]
       @kermits   = @htgt.datasets["kermits"]
+      @ensembl   = @htgt.datasets["mmusculus_gene_ensembl"]
       @emma      = Biomart::Dataset.new( "http://www.emmanet.org/biomart", { :name => "strains" } )
+      @dcc       = Biomart::Dataset.new( "http://www.i-dcc.org/biomart", { :name => "dcc" } )
     end
     
     should "have basic metadata" do
@@ -64,20 +68,34 @@ class BiomartTest < Test::Unit::TestCase
       assert( @kermits.attributes["ensembl_gene_id"].is_a?( Biomart::Attribute ), "Biomart::Dataset is not creating Biomart::Attribute objects." )
     end
     
-    should "perform count/search queries" do
-      perform_count_queries("net/http")
-      perform_search_queries("net/http")
-      
-      #if CURB_AVAILABLE
-      #  perform_count_queries("curb")
-      #  perform_search_queries("curb")
-      #  Biomart.use_net_http = true
-      #  perform_count_queries("net/http")
-      #  perform_search_queries("net/http")
-      #else
-      #  perform_count_queries("net/http")
-      #  perform_search_queries("net/http")
-      #end
+    should "perform count queries" do
+      htgt_count = @htgt_targ.count()
+      assert( htgt_count.is_a?( Integer ), "Biomart::Dataset.count is not returning integers." )
+      assert( htgt_count > 0, "Biomart::Dataset.count is returning zero - this is wrong!" )
+
+      htgt_count_single_filter = @htgt_targ.count( :filters => { "is_eucomm" => "1" } )
+      assert( htgt_count_single_filter.is_a?( Integer ), "Biomart::Dataset.count (with single filter) is not returning integers." )
+      assert( htgt_count_single_filter > 0, "Biomart::Dataset.count (with single filter) is returning zero - this is wrong!" )
+
+      htgt_count_single_filter_group_value = @htgt_targ.count( :filters => { "marker_symbol" => ["Cbx1","Cbx7","Art4"] } )
+      assert( htgt_count_single_filter_group_value.is_a?( Integer ), "Biomart::Dataset.count (with single filter, group value) is not returning integers." )
+      assert( htgt_count_single_filter_group_value > 0, "Biomart::Dataset.count (with single filter, group value) is returning zero - this is wrong!" )
+    end
+    
+    should "perform search queries" do
+      search = @htgt_trap.search()
+      assert( search.is_a?( Hash ), "Biomart::Dataset.search (no options) is not returning a hash." )
+      assert( search[:data].is_a?( Array ), "Biomart::Dataset.search[:data] (no options) is not returning an array." )
+
+      search1 = @htgt_targ.search( :filters => { "marker_symbol" => "Cbx1" }, :process_results => true )
+      assert( search1.is_a?( Array ), "Biomart::Dataset.search (filters defined with processing) is not returning an array." )
+      assert( search1.first.is_a?( Hash ), "Biomart::Dataset.search (filters defined with processing) is not returning an array of hashes." )
+      assert( search1.first["marker_symbol"] == "Cbx1", "Biomart::Dataset.search (filters defined with processing) is not returning the correct info." )
+
+      search2 = @htgt_targ.search( :filters => { "marker_symbol" => "Cbx1" }, :attributes => ["marker_symbol","ensembl_gene_id"], :process_results => true )
+      assert( search2.is_a?( Array ), "Biomart::Dataset.search (filters and attributes defined with processing) is not returning an array." )
+      assert( search2.first.is_a?( Hash ), "Biomart::Dataset.search (filters and attributes defined with processing) is not returning an array of hashes." )
+      assert( search2.first["marker_symbol"] == "Cbx1", "Biomart::Dataset.search (filters and attributes defined with processing) is not returning the correct info." )
     end
     
     should "perform search queries whilst altering the timeout property" do
@@ -124,36 +142,151 @@ class BiomartTest < Test::Unit::TestCase
       assert( search2[:data].size > 0, "Biomart::Dataset.search[:data] for poorly formatted TSV data is empty. (EMMA Query)" )
     end
     
+    should "perform federated search queries" do
+      search_opts = {
+        :filters => {
+          "status" => [
+            "Mice - Genotype confirmed", "Mice - Germline transmission",
+            "Mice - Microinjection in progress", "ES Cells - Targeting Confirmed"
+          ]
+        },
+        :attributes => [ "marker_symbol", "mgi_accession_id", "status" ],
+        :federate => [
+          {
+            :dataset => @ensembl,
+            :filters => { "chromosome_name" => "1", "start" => "1", "end" => "10000000" },
+            :attributes => []
+          }
+        ]
+      }
+      
+      results = @htgt_targ.search( search_opts )
+      
+      assert( results.is_a?(Hash), "Biomart::Dataset.search is not returning a hash. [federated search]" )
+      assert( results[:data].is_a?(Array), "Biomart::Dataset.search[:data] is not returning an array. [federated search]" )
+      assert( results[:data][0].size === 3, "Biomart::Dataset.search[:data] is not returning 3 attributes. [federated search]" )
+      assert( results[:headers].size === 3, "Biomart::Dataset.search[:headers] is not returning 3 elements. [federated search]" )
+
+      assert_raise( Biomart::ArgumentError ) { @htgt_targ.count( search_opts ) }
+      
+      assert_raise Biomart::ArgumentError do
+        search_opts[:federate] = [
+          {
+            :dataset => "mmusculus_gene_ensembl",
+            :filters => { "chromosome_name" => "1", "start" => "1", "end" => "10000000" },
+            :attributes => []
+          }
+        ]
+        results = @htgt_targ.search( search_opts )
+      end
+      
+      assert_raise Biomart::ArgumentError do
+        search_opts[:federate] = {
+          :dataset => "mmusculus_gene_ensembl",
+          :filters => { "chromosome_name" => "1", "start" => "1", "end" => "10000000" },
+          :attributes => []
+        }
+        results = @htgt_targ.search( search_opts )
+      end
+      
+      assert_raise Biomart::ArgumentError do
+        search_opts[:federate] = [
+          {
+            :dataset => @ensembl,
+            :filters => { "chromosome_name" => "1", "start" => "1", "end" => "10000000" },
+            :attributes => []
+          },
+          {
+            :dataset => @ensembl,
+            :filters => { "chromosome_name" => "1", "start" => "1", "end" => "10000000" },
+            :attributes => []
+          }
+        ]
+        results = @htgt_targ.search( search_opts )
+      end
+    end
+    
+    should "perform search queries with the :required_attributes option" do
+      search_opts = {
+        :filters => {
+          "chromosome_name" => "1",
+          "start"           => "1",
+          "end"             => "10000000"
+        },
+        :attributes => [
+          "ensembl_gene_id", "ensembl_transcript_id",
+          "mouse_paralog_ensembl_gene", "mouse_paralog_chromosome"
+        ],
+        :required_attributes => ["mouse_paralog_ensembl_gene"]
+      }
+      
+      results = @ensembl.search( search_opts )
+      
+      assert( results.is_a?(Hash), "Biomart::Dataset.search is not returning a hash. [required_attributes search]" )
+      assert( results[:data].is_a?(Array), "Biomart::Dataset.search[:data] is not returning an array. [required_attributes search]" )
+      results[:data].each do |data_row|
+        assert_equal( false, data_row[2].nil?, "The required_attributes search has not filtered out nil values." )
+      end
+      
+      assert_raise( Biomart::ArgumentError ) { @ensembl.count( search_opts ) }
+      assert_raise Biomart::ArgumentError do
+        search_opts[:required_attributes] = "mouse_paralog_ensembl_gene"
+        @ensembl.search( search_opts )
+      end
+      
+      results = @dcc.search(
+        :filters => {
+          "marker_symbol" => [
+            "Lrrc32", "Dub3", "Hs3st4", "Hs3st4", "Hs3st4", "Hs3st4",
+            "Hs3st4", "Hs3st4", "Hs3st4", "Tcrg-C", "Gm5195", "Gm5198",
+            "Gm5199", "Gm5625", "Rpl13-ps2", "Gm5664", "Gm5928", "Gm6035",
+            "Gm6049"
+          ]
+        },
+        :required_attributes => ["ikmc_project","ikmc_project_id"],
+        :process_results => true
+      )
+      
+      results.each do |data_row|
+        assert_equal( false, data_row["ikmc_project"].nil?, "The required_attributes search has not filtered out nil values." )
+        assert_equal( false, data_row["ikmc_project_id"].nil?, "The required_attributes search has not filtered out nil values." )
+      end
+    end
   end
   
-  def perform_count_queries( library )
-    htgt_count = @htgt_targ.count()
-    assert( htgt_count.is_a?( Integer ), "Biomart::Dataset.count is not returning integers. [using #{library} for HTTP communication]" )
-    assert( htgt_count > 0, "Biomart::Dataset.count is returning zero - this is wrong! [using #{library} for HTTP communication]" )
-    
-    htgt_count_single_filter = @htgt_targ.count( :filters => { "is_eucomm" => "1" } )
-    assert( htgt_count_single_filter.is_a?( Integer ), "Biomart::Dataset.count (with single filter) is not returning integers. [using #{library} for HTTP communication]" )
-    assert( htgt_count_single_filter > 0, "Biomart::Dataset.count (with single filter) is returning zero - this is wrong! [using #{library} for HTTP communication]" )
-    
-    htgt_count_single_filter_group_value = @htgt_targ.count( :filters => { "marker_symbol" => ["Cbx1","Cbx7","Art4"] } )
-    assert( htgt_count_single_filter_group_value.is_a?( Integer ), "Biomart::Dataset.count (with single filter, group value) is not returning integers. [using #{library} for HTTP communication]" )
-    assert( htgt_count_single_filter_group_value > 0, "Biomart::Dataset.count (with single filter, group value) is returning zero - this is wrong! [using #{library} for HTTP communication]" )
+  context "A Biomart::Attribute instance" do
+    setup do
+      @kermits = @htgt.datasets["kermits"]
+    end
+    
+    should "have basic metadata" do
+      true_false  = [true,false]
+      ens_gene_id = @kermits.attributes["ensembl_gene_id"]
+      
+      assert( !ens_gene_id.name.nil?, "Biomart::Attribute.name is nil." )
+      assert( !ens_gene_id.display_name.nil?, "Biomart::Attribute.display_name is nil." )
+      
+      assert( true_false.include?( ens_gene_id.hidden? ), "Biomart::Attribute.hidden? is not returning true/false." )
+      assert( true_false.include?( ens_gene_id.default? ), "Biomart::Attribute.default? is not returning true/false." )
+    end
   end
   
-  def perform_search_queries( library )
-    search = @htgt_trap.search()
-    assert( search.is_a?( Hash ), "Biomart::Dataset.search (no options) is not returning a hash. [using #{library} for HTTP communication]" )
-    assert( search[:data].is_a?( Array ), "Biomart::Dataset.search[:data] (no options) is not returning an array. [using #{library} for HTTP communication]" )
-    
-    search1 = @htgt_targ.search( :filters => { "marker_symbol" => "Cbx1" }, :process_results => true )
-    assert( search1.is_a?( Array ), "Biomart::Dataset.search (filters defined with processing) is not returning an array. [using #{library} for HTTP communication]" )
-    assert( search1.first.is_a?( Hash ), "Biomart::Dataset.search (filters defined with processing) is not returning an array of hashes. [using #{library} for HTTP communication]" )
-    assert( search1.first["marker_symbol"] == "Cbx1", "Biomart::Dataset.search (filters defined with processing) is not returning the correct info. [using #{library} for HTTP communication]" )
-    
-    search2 = @htgt_targ.search( :filters => { "marker_symbol" => "Cbx1" }, :attributes => ["marker_symbol","ensembl_gene_id"], :process_results => true )
-    assert( search2.is_a?( Array ), "Biomart::Dataset.search (filters and attributes defined with processing) is not returning an array. [using #{library} for HTTP communication]" )
-    assert( search2.first.is_a?( Hash ), "Biomart::Dataset.search (filters and attributes defined with processing) is not returning an array of hashes. [using #{library} for HTTP communication]" )
-    assert( search2.first["marker_symbol"] == "Cbx1", "Biomart::Dataset.search (filters and attributes defined with processing) is not returning the correct info. [using #{library} for HTTP communication]" )
+  context "A Biomart::Filter instance" do
+    setup do
+      @kermits = @htgt.datasets["kermits"]
+    end
+    
+    should "have basic metadata" do
+      true_false  = [true,false]
+      ens_gene_id = @kermits.filters["ensembl_gene_id"]
+      
+      assert( !ens_gene_id.name.nil?, "Biomart::Filter.name is nil." )
+      assert( !ens_gene_id.display_name.nil?, "Biomart::Filter.display_name is nil." )
+      
+      assert( true_false.include?( ens_gene_id.hidden? ), "Biomart::Filter.hidden? is not returning true/false." )
+      assert( true_false.include?( ens_gene_id.default? ), "Biomart::Filter.default? is not returning true/false." )
+      assert( true_false.include?( ens_gene_id.multiple_values? ), "Biomart::Filter.multiple_values? is not returning true/false." )
+    end
   end
   
   context "The Biomart module" do
@@ -161,7 +294,7 @@ class BiomartTest < Test::Unit::TestCase
       @not_biomart  = Biomart::Server.new( "http://www.sanger.ac.uk" )
       @htgt_targ    = @htgt.datasets["htgt_targ"]
       @bad_dataset  = Biomart::Dataset.new( "http://www.sanger.ac.uk/htgt/biomart", { :name => "wibble" } )
-      @good_biomart = Biomart::Server.new( "http://www.sanger.ac.uk/htgt/biomart" )
+      @good_biomart = Biomart::Server.new( "http://www.i-dcc.org/biomart" )
     end
     
     should "allow you to ping a server" do
@@ -171,33 +304,13 @@ class BiomartTest < Test::Unit::TestCase
     end
     
     should "handle user/configuration errors (i.e. incorrect URLs etc)" do
-      begin
-        @not_biomart.list_databases
-      rescue Biomart::HTTPError => e
-        http_error = e
-      end
-      
-      assert( http_error.is_a?( Biomart::HTTPError ), "Biomart.request is not processing HTTP errors correctly." )
+      assert_raise( Biomart::HTTPError ) { @not_biomart.list_databases }
     end
     
     should "handle biomart server errors gracefully" do
-      begin
-        @htgt_targ.count( :filters => { "wibbleblibbleblip" => "1" } )
-      rescue Biomart::FilterError => e
-        filter_error = e
-      end
-      
-      begin
-        @htgt_targ.search( :attributes => ["wibbleblibbleblip"] )
-      rescue Biomart::AttributeError => e
-        attribute_error = e
-      end
-      
-      begin
-        @bad_dataset.count()
-      rescue Biomart::DatasetError => e
-        dataset_error = e
-      end
+      assert_raise( Biomart::FilterError )    { @htgt_targ.count( :filters => { "wibbleblibbleblip" => "1" } ) }
+      assert_raise( Biomart::AttributeError ) { @htgt_targ.search( :attributes => ["wibbleblibbleblip"] ) }
+      assert_raise( Biomart::DatasetError )   { @bad_dataset.count() }
       
       begin
         @bad_dataset.count()
@@ -205,10 +318,7 @@ class BiomartTest < Test::Unit::TestCase
         general_error = e
       end
       
-      assert( filter_error.is_a?( Biomart::FilterError ), "Biomart.request is not handling Biomart filter errors correctly." )
-      assert( attribute_error.is_a?( Biomart::AttributeError ), "Biomart.request is not handling Biomart attribute errors correctly." )
-      assert( dataset_error.is_a?( Biomart::DatasetError ), "Biomart.request is not handling Biomart dataset errors correctly." )
-      assert( general_error.is_a?( Biomart::BiomartError ), "Biomart.request is not handling general Biomart errors correctly." )
+      assert( general_error.is_a?(Biomart::BiomartError), "Biomart.request is not handling general Biomart errors correctly." )
     end
   end
 end

metadata

@@ -1,7 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: biomart
 version: !ruby/object:Gem::Version 
-  version: 0.1.5
+  hash: 23
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Darren Oakley
@@ -9,40 +15,55 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-04 00:00:00 +00:00
+date: 2010-06-10 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: builder
-  type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
-    version: 
+  type: :runtime
+  version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: thoughtbot-shoulda
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  name: shoulda
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: "0"
-    version: 
+        hash: 23
+        segments: 
+        - 2
+        - 10
+        version: "2.10"
+  type: :development
+  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
   name: hoe
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 2.3.3
-    version: 
-description: A ruby API for interacting with Biomart services.
+        hash: 21
+        segments: 
+        - 2
+        - 6
+        - 1
+        version: 2.6.1
+  type: :development
+  version_requirements: *id003
+description: A ruby API for interacting with Biomart XML based webservices.
 email: 
 - daz.oakley@gmail.com
 executables: []
@@ -68,8 +89,8 @@ files:
 - script/console
 - script/destroy
 - script/generate
-- tasks/metrics.task
-- tasks/shoulda.task
+- tasks/metrics.rake
+- tasks/shoulda.rake
 - test/test_biomart.rb
 - test/test_helper.rb
 has_rdoc: true
@@ -83,21 +104,27 @@ rdoc_options:
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
 rubyforge_project: biomart
-rubygems_version: 1.3.5
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: A ruby API for interacting with Biomart services.