biomart 0.2.1 → 0.2.2

data/.gitignore

@@ -1,4 +1,6 @@
+.yardoc/*
 coverage*
+pkg/*
 simplecov*
+tmp/*.json
 tmp/metric_fu*
-tmp/*.json

data/History.txt

@@ -1,3 +1,8 @@
+=== 0.2.1 2011-02-18
+
+* 1 major bugfix:
+  * More forceful filter checking in 0.2.1 was causing queries on 'pointerFilters' to error out unnecessarily.
+
 === 0.2.1 2011-02-16
 
 * 1 minor bugfix:

data/lib/biomart.rb

@@ -43,7 +43,27 @@ module Biomart
   
   # Centralised request function for handling all of the HTTP requests 
   # to the biomart servers.
-  def request( params={} )
+  # 
+  # @param [Hash] params Parameters to be passed to the request
+  # @return [String] The response body
+  #
+  # @example
+  #   request({
+  #     :url     => 'http://www.example.com',   # the url
+  #     :method  => 'get',                      # get/post
+  #     :query   => 'a string',                 # when using post, send this as 'query' (i.e. the biomart query xml)
+  #     :timeout => 60                          # override the default timeout
+  #   })
+  #
+  # @raise Biomart::ArgumentError Raised if a params hash is not passed (or it is empty)
+  # @raise Biomart::HTTPError Raised if a HTTP error was encountered
+  # @raise Biomart::FilterError Raised when a filter is not found
+  # @raise Biomart::AttributeError Raised when an attribute is not found
+  # @raise Biomart::DatasetError Raised when a dataset is not found
+  # @raise Biomart::BiomartError Raised for any other unhandled error
+  def request( params )
+    raise ArgumentError if !params.is_a?(Hash) || params.empty?
+    
     if params[:url] =~ / /
       params[:url].gsub!(" ","+")
     end

data/lib/biomart/attribute.rb

@@ -12,14 +12,17 @@ module Biomart
     end
     
     # Convenience method to see if this attribute is hidden from 
-    # the standard MartView interface.  Returns true/false.
+    # the standard MartView interface.
+    #
+    # @return [Boolean] 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.
+    #
+    # @return [Boolean] true/false
     def default?
       @default
     end

data/lib/biomart/database.rb

@@ -20,6 +20,8 @@ module Biomart
     
     # Returns an array of the dataset names (biomart 'name') 
     # for this dataset.
+    # 
+    # @return [Array] An array of dataset names
     def list_datasets
       if @datasets.empty?
         fetch_datasets
@@ -29,6 +31,8 @@ module Biomart
     
     # Returns a hash (keyed by the biomart 'name' for the dataset) 
     # of all of the Biomart::Dataset objects belonging to this server.
+    # 
+    # @return [Hash] A hash of Biomart::Dataset objects keyed by 'name'
     def datasets
       if @datasets.empty?
         fetch_datasets
@@ -38,6 +42,8 @@ module Biomart
     
     # Returns true / false if this database is visbile in the 
     # default MartView interface.
+    # 
+    # @return [Boolean] true/false
     def visible?
       @visible
     end

data/lib/biomart/dataset.rb

@@ -37,6 +37,8 @@ module Biomart
     
     # Returns a hash (keyed by the biomart 'internal_name' for the filter) 
     # of all of the Biomart::Filter objects belonging to this dataset.
+    # 
+    # @return [Hash] A hash of Biomart::Filter objects keyed by 'internal_name'
     def filters
       if @filters.empty?
         fetch_configuration()
@@ -46,6 +48,8 @@ module Biomart
     
     # Returns an array of the filter names (biomart 'internal_name') 
     # for this dataset.
+    # 
+    # @return [Array] An array of filters (their 'internal_name's)
     def list_filters
       if @filters.empty?
         fetch_configuration()
@@ -55,6 +59,8 @@ module Biomart
     
     # Returns a hash (keyed by the biomart 'internal_name' for the attribute) 
     # of all of the Biomart::Attribute objects belonging to this dataset.
+    # 
+    # @return [Hash] A hash of Biomart::Attribute objects keyed by 'internal_name'
     def attributes
       if @attributes.empty?
         fetch_configuration()
@@ -64,6 +70,8 @@ module Biomart
     
     # Returns an array of the attribute names (biomart 'internal_name') 
     # for this dataset.
+    # 
+    # @return [Array] An array of attributes (their 'internal_name's)
     def list_attributes
       if @attributes.empty?
         fetch_configuration()
@@ -73,13 +81,16 @@ module Biomart
     
     # Function to perform a Biomart count.  Returns an integer value for 
     # the result of the count query.
-    #
-    # optional arguments:
+    # 
+    # arguments:
     # 
     #   {
-    #     :timeout => integer,     # set a timeout length for the request (secs)
-    #     :filters => {}           # hash of key-value pairs (filter => search term)
+    #     :timeout => integer,     # set a timeout length for the request (secs) - optional
+    #     :filters => {}           # hash of key-value pairs (filter => search term) - optional
     #   }
+    # 
+    # @param [Hash] args The arguments hash
+    # @raise Biomart::ArgumentError Raised when un-supported arguments are passed
     def count( args={} )
       if args[:federate]
         raise Biomart::ArgumentError, "You cannot federate a count query."
@@ -136,6 +147,10 @@ module Biomart
     #
     # 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).
+    # 
+    # @param [Hash] args The arguments hash
+    # @return [Hash/Array] Will return a hash by default (of unprocessed data), or will return an array of hashes
+    # @raise Biomart::ArgumentError Raised if incorrect arguments are passed
     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."
@@ -154,7 +169,10 @@ module Biomart
       return result
     end
     
-    # Utility function to build the Biomart query XML
+    # Utility function to build the Biomart query XML - used by #count and #search.
+    #
+    # @see #count
+    # @see #search
     def generate_xml( args={} )
       biomart_xml = ""
       xml = Builder::XmlMarkup.new( :target => biomart_xml, :indent => 2 )
@@ -184,7 +202,8 @@ module Biomart
     end
     
     # Simple heartbeat function to test that a Biomart server is online.
-    # Returns true/false.
+    #
+    # @return [Boolean] true/false
     def alive?
       server = Biomart::Server.new( @url )
       return server.alive?
@@ -198,17 +217,17 @@ module Biomart
         url = @url + "?type=configuration&dataset=#{@name}"
         document = REXML::Document.new( request( :url => url ) )
 
-        # Top-Level filters...
-        REXML::XPath.each( document, '//FilterDescription' ) do |f|
-          unless f.attributes["displayType"].eql? "container"
-            @filters[ f.attributes["internalName"] ] = Filter.new( f.attributes )
-          end
-        end
-        
-        # Filters nested inside containers...
-        REXML::XPath.each( document, '//FilterDescription/Option' ) do |f|
-          if f.attributes["displayType"] != nil
-            @filters[ f.attributes["internalName"] ] = Filter.new( f.attributes )
+        # Filters...
+        ['//FilterDescription','//FilterDescription/Option'].each do |filter_xpath|
+          REXML::XPath.each( document, filter_xpath ) do |f|
+            if f.attributes["displayType"] != nil
+              next if f.attributes["displayType"] == "container"
+              @filters[ f.attributes["internalName"] ] = Filter.new( f.attributes )
+            else f.attributes["pointerFilter"] != nil
+              pointer_filter = Filter.new( f.attributes )
+              @filters[ pointer_filter.name ]           = pointer_filter
+              @filters[ pointer_filter.pointer_filter ] = pointer_filter
+            end
           end
         end
         

data/lib/biomart/filter.rb

@@ -2,7 +2,7 @@ module Biomart
   # Class representation for a biomart filter. 
   # Will belong to a Biomart::Dataset.
   class Filter
-    attr_reader :name, :display_name, :default_value, :qualifier, :type
+    attr_reader :name, :display_name, :default_value, :qualifier, :type, :pointer_dataset, :pointer_filter
     
     def initialize(args)
       @name            = args["internalName"]
@@ -14,24 +14,33 @@ module Biomart
       @type            = args["type"]
       @multiple_values = args["multipleValues"] ? true : false
       
+      @pointer_dataset   = args["pointerDataset"]
+      @pointer_filter    = args["pointerFilter"]
+      @pointer_interface = args["pointerInterface"]
+      
       @type.downcase! unless @type.nil?
     end
     
     # Convenience method to see if this filter is hidden from 
-    # the standard MartView interface.  Returns true/false.
+    # the standard MartView interface.
+    #
+    # @return [Boolean] 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.
+    #
+    # @return [Boolean] true/false
     def default?
       @default
     end
     
     # Convenience method to see if this filter allows multiple 
     # values to be passed to it.
+    #
+    # @return [Boolean] true/false
     def multiple_values?
       @multiple_values
     end

data/lib/biomart/server.rb

@@ -18,6 +18,8 @@ module Biomart
     
     # Returns an array of the database names (biomart 'name') 
     # for this dataset.
+    #
+    # @return [Array] An array of database names
     def list_databases
       if @databases.empty?
         fetch_databases
@@ -27,6 +29,8 @@ module Biomart
     
     # Returns a hash (keyed by the biomart 'name' for the database) 
     # of all of the Biomart::Database objects belonging to this server.
+    #
+    # @return [Hash] A hash of Biomart::Database objects keyed by the database name
     def databases
       if @databases.empty?
         fetch_databases

data/lib/biomart/version.rb

@@ -1,3 +1,3 @@
 module Biomart
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

data/test/test_biomart.rb

@@ -49,6 +49,7 @@ class BiomartTest < Test::Unit::TestCase
       @ensembl_var = Biomart::Dataset.new( "http://www.ensembl.org/biomart", { :name => "hsapiens_snp" } )
       @emma        = Biomart::Dataset.new( "http://www.emmanet.org/biomart", { :name => "strains" } )
       @dcc         = Biomart::Dataset.new( "http://www.knockoutmouse.org/biomart", { :name => "dcc" } )
+      @mgi         = Biomart::Dataset.new( "http://biomart.informatics.jax.org/biomart", { :name => "markers" } )
     end
     
     should "have basic metadata" do
@@ -60,6 +61,7 @@ class BiomartTest < Test::Unit::TestCase
     should "have filters" do
       assert( @htgt_targ.list_filters.is_a?( Array ), "Biomart::Dataset.list_filters is not returning an array." )
       assert( @htgt_targ.list_filters.include?( "ensembl_gene_id" ), "Biomart::Dataset filter parsing is off - ensembl_gene_id is not in htgt_targ!" )
+      assert( @mgi.list_filters.include?( "ancestor_term_1023_filter" ), "Biomart::Dataset filter parsing is off - ancestor_term_1023_filter is not in mgi markers!" )
       assert( @kermits.filters["ensembl_gene_id"].is_a?( Biomart::Filter ), "Biomart::Dataset is not creating Biomart::Filter objects." )
     end
     

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 2
-  - 1
-  version: 0.2.1
+  - 2
+  version: 0.2.2
 platform: ruby
 authors: 
 - Darren Oakley
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-16 00:00:00 +00:00
+date: 2011-02-18 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency