solvebio 1.6.1 → 1.7.0

data/lib/solvebio/dataset.rb

@@ -0,0 +1,60 @@
+module SolveBio
+    class Dataset < APIResource
+        include SolveBio::APIOperations::Create
+        include SolveBio::APIOperations::Update
+        include SolveBio::APIOperations::List
+        include SolveBio::APIOperations::Delete
+        include SolveBio::APIOperations::Help
+
+        def depository
+            return Depository.retrieve(self.depository)
+        end
+
+        def depository_version
+            return DepositoryVersion.retrieve(self.depository_version)
+        end
+
+        def fields(name=nil, params={})
+            unless self.fields_url
+                raise Exception,
+                'Please use Dataset.retrieve({ID}) before doing looking ' +
+                    'up fields'
+            end
+
+            if name
+                # construct the field's full_name if a field name is provided
+                return DatasetField.retrieve("#{self.full_name}/#{name}")
+            end
+
+            result = Client.request('get', self.fields_url)
+            results = Util.to_solve_object(result)
+            unless results.respond_to?(:tabulate)
+                results.define_singleton_method(:tabulate) do |results_hash|
+                    ary = results_hash.to_a.map do |fields|
+                        [fields['name'], fields['data_type'], fields['description']]
+                    end
+                    Tabulate.tabulate(ary,
+                                    ['Field', 'Data Type', 'Description'],
+                                    ['left', 'left', 'left'], true)
+                end
+            end
+            results
+        end
+
+        def query(params={})
+            unless self.respond_to?(:data_url)
+                unless self.respond_to?(:id)
+                    raise Exception,
+                    'No Dataset ID was provided. ' +
+                        'Please instantiate the Dataset ' +
+                        'object with an ID or full_name.'
+                end
+                # automatically construct the data_url from the ID
+                self.data_url = url + '/data'
+            end
+
+            params.merge!(:data_url => self.data_url)
+            Query.new(self.id, params)
+        end
+    end
+end

data/lib/solvebio/dataset_field.rb

@@ -0,0 +1,12 @@
+module SolveBio
+    class DatasetField < APIResource
+        include SolveBio::APIOperations::Create
+        include SolveBio::APIOperations::List
+        include SolveBio::APIOperations::Update
+
+        def facets(params={})
+            response = Client.get(self[:facets_url], {:params => params})
+            Util.to_solve_object(response)
+        end
+    end
+end

data/lib/solvebio/depository.rb

@@ -0,0 +1,38 @@
+module SolveBio
+    class Depository < APIResource
+        #  A depository (or data repository) is like a source code
+        #  repository, but for datasets. Depositories have one or more
+        #  versions, which in turn contain one or more datasets. Typically,
+        #  depositories contain a series of datasets that are compatible with
+        #  each other (i.e. they come from the same data source or project).
+        include SolveBio::APIOperations::Create
+        include SolveBio::APIOperations::List
+        include SolveBio::APIOperations::Search
+        include SolveBio::APIOperations::Update
+        include SolveBio::APIOperations::Help
+
+        # Fields that get shown by tabulate
+        TAB_FIELDS = %w(description full_name latest_version name title url)
+
+        def versions(name=nil, params={})
+            # construct the depo version full name
+            return DepositoryVersion.
+                retrieve("#{self['full_name']}/#{name}") if name
+
+            response = Client.request('get', versions_url, {:params => params})
+            results = Util.to_solve_object(response)
+            unless results.respond_to?(:tabulate)
+                results.define_singleton_method(:tabulate) do |results|
+                    ary = results.to_a.map do |fields|
+                        [fields['full_name'], fields['title'], fields['description']]
+                    end
+                    Utils::Tabulate.tabulate(ary,
+                        ['Depository Version', 'Title', 'Description'],
+                        ['left', 'left', 'left'], true)
+                end
+            end
+            results
+        end
+
+    end
+end

data/lib/solvebio/depository_version.rb

@@ -0,0 +1,40 @@
+module SolveBio
+    class DepositoryVersion < APIResource
+        include SolveBio::APIOperations::Create
+        include SolveBio::APIOperations::List
+        include SolveBio::APIOperations::Update
+        include SolveBio::APIOperations::Help
+
+        # Fields that get shown by tabulate
+        TAB_FIELDS = %w(datasets_url depository description full_name
+                       latest url)
+
+        def datasets_url(name=nil)
+            name ||= self['name']
+            "#{self['full_name']}/#{name}"
+        end
+
+        def datasets(name=nil, params={})
+            return Dataset.retrieve(datasets_url(name)) if name
+
+            response = Client.request('get', datasets_url, {:params => params})
+            results = Util.to_solve_object(response)
+            unless results.respond_to?(:tabulate)
+                results.define_singleton_method(:tabulate) do |results|
+                    ary = results.to_a.map do |fields|
+                        [fields['full_name'], fields['title'], fields['description']]
+                    end
+                    Tabulate.tabulate(ary,
+                        ['Field', 'Title', 'Description'],
+                        ['left', 'left', 'left'], true)
+                end
+            end
+
+            results
+        end
+
+        def <=>(other)
+            self[:full_name] <=> other[:full_name]
+        end
+    end
+end

data/lib/solvebio/errors.rb

@@ -0,0 +1,64 @@
+module SolveBio
+    class SolveError < RuntimeError
+        DEFAULT_MESSAGE =
+            'Unexpected error communicating with SolveBio. ' +
+            'If this problem persists, let us know at ' +
+            'contact@solvebio.com.'
+
+        attr_reader :json_body
+        attr_reader :status_code
+        attr_reader :message
+        attr_reader :field_errors
+
+        def initialize(response=nil, message=nil)
+            @json_body = nil
+            @status_code = nil
+            @message = message or DEFAULT_MESSAGE
+            @field_errors = []
+
+            if response
+                @status_code = response.code.to_i
+                begin
+                    @json_body = JSON.parse(response.body)
+                rescue
+                    SolveBio.logger.debug(
+                        "API Response (%d): No content." % @status_code)
+                else
+                    SolveBio.logger.debug(
+                        "API Response (#{@status_code}): #{@json_body}")
+
+                    if [400, 401, 403, 404].member?(@status_code)
+                        @message = 'Bad request.'
+
+                        if @json_body.member?('detail')
+                            @message = @json_body['detail']
+                        end
+
+                        if @json_body.member?('non_field_errors')
+                            @message = @json_body['non_field_errors'].join(', ')
+                        end
+
+                        @json_body.each do |k, v|
+                            unless ['detail', 'non_field_errors'].member?(k)
+                                v = v.join(', ') if v.kind_of?(Array)
+                                @field_errors << ('%s (%s)' % [k, v])
+                            end
+                        end
+
+                        unless @field_errors.empty?
+                            @message += (' The following fields were missing ' +
+                                'or invalid: %s' %
+                                             @field_errors.join(', '))
+                        end
+                    end
+                end
+            end
+
+            self
+        end
+
+        def to_s
+            @message
+        end
+    end
+end

data/lib/solvebio/filter.rb

@@ -0,0 +1,315 @@
+module SolveBio
+    class Filter
+        # SolveBio::Filter objects.
+        #
+        # Makes it easier to create filters cumulatively using ``&`` (and),
+        # ``|`` (or) and ``~`` (not) operations.
+        #
+        # == Example
+        #
+        #     require 'solvebio'
+        #     f =  SolveBio::Filter.new                       #=> <Filter []>
+        #     f &= SolveBio::Filter.new :price => 'Free'      #=> <Filter [[:price, "Free"]]>
+        #     f |= SolveBio::Filter.new :style => 'Mexican'   #=> <Filter [{:or=>[[:price, "Free"], [:style, "Mexican"]]}]>
+        #
+        # The final result is a filter that can be used in a query which match es
+        # "price = 'Free' or style = 'Mexican'".
+        #
+        # By default, each key/value pairs are AND'ed together. However, you can change that
+        # to OR by passing in +:or+ as the last argument.
+        #
+        #     * `<field>='value` matches if the field is term filter (exact term)
+        #     * `<field>__in=[<item1>, ...]` matches any of the terms <item1> and so on
+        #     * `<field>__range=[<start>, <end>]` matches anything from <start> to <end>
+        #
+        # String terms are not analyzed and are always assumed to be exact matches.
+        #
+        # Numeric columns can be selected by range using:
+        #
+        #     * `<field>__gt`: greater than
+        #     * `<field>__gte`: greater than or equal to
+        #     * `<field>__lt`: less than
+        #     * `<field>__lte`: less than or equal to
+        #
+        # Field action examples:
+        #
+        #     dataset.query(:gene__in  => ['BRCA', 'GATA3'],
+        #                   :chr       => '3',
+        #                   :start__gt => 10000,
+        #                   :end__lte  => 20000)
+
+        attr_accessor :filters
+
+        # Creates a new Filter, the first argument is expected to be Hash or an Array.
+        def initialize(filters={}, conn=:and)
+            if filters.kind_of?(Hash)
+                @filters = SolveBio::Filter.
+                    normalize(filters.keys.sort.map{|key| [key,  filters[key]]})
+            elsif filters.kind_of?(Array)
+                @filters = filters
+            elsif filters.kind_of?(SolveBio::Filter)
+                @filters = SolveBio::Filter.deep_copy(filters.filters)
+                return self
+            else
+                raise TypeError, "Invalid filter type #{filters.class}"
+            end
+            @filters = [{conn => @filters}] if filters.size > 1
+            self
+        end
+
+        def inspect
+            return "<SolveBio::Filter #{@filters.inspect}>"
+        end
+
+        def empty?
+            @filters.empty?
+        end
+
+        # Deep copy
+        def clone
+            SolveBio::Filter.deep_copy(self)
+        end
+
+        # OR and AND will create a new Filter, with the filters from both Filter
+        #   objects combined with the connector `conn`.
+        # FIXME: should we allow a default conn parameter?
+        def combine(other, conn=:and)
+            return other.clone if self.empty?
+
+            if other.empty?
+                return self.clone
+            elsif self.filters[0].member?(conn)
+                f = self.clone
+                f.filters[0][conn] += other.filters
+            elsif other.filters[0].member?(conn)
+                f = other.clone
+                f.filters[0][conn] += self.filters
+            else
+                f = initialize(self.clone.filters + other.filters, conn)
+            end
+
+            return f
+        end
+
+        def |(other)
+            return self.combine(other, :or)
+        end
+
+        def &(other)
+            return self.combine(other, :and)
+        end
+
+        def ~()
+            f = self.clone
+
+            # not of null filter is null fiter
+            return f if f.empty?
+
+            # length of self_filters should never be more than 1
+            filters = f.filters.first
+            if filters.kind_of?(Hash) and
+                filters.member?(:not)
+                # The filters are already a single dictionary
+                # containing a 'not'. Swap out the 'not'
+                f.filters = [filters[:not]]
+            else
+                # 'not' blocks can contain only dicts or a single tuple filter
+                # so we get the first element from the filter list
+                f.filters = [{:not => filters}]
+            end
+
+            return f
+        end
+
+        # Checks and normalizes filter array tuples
+        def self.normalize(ary)
+            ary.map do |tuple|
+                unless tuple.kind_of?(Array)
+                    raise(TypeError,
+                          "Invalid filter element #{tuple.class}; want Array")
+                end
+                unless tuple.size == 2
+                    raise(TypeError,
+                          "Filter element size must be 2; is #{tuple.size}")
+                end
+                key, value = tuple
+                if key.to_s =~ /.+__(.+)$/
+                    op = $1
+                    unless %w(gt gte lt lte in range contains prefix regexp).member?(op)
+                        raise(TypeError,
+                              "Invalid field operation #{op} in #{key}")
+                    end
+                    case op
+                    when 'gt', 'gte', 'lt', 'lte'
+                        begin
+                            value = Float(value)
+                        rescue
+                            raise(TypeError,
+                                  "Invalid field value #{value} for #{key}; " +
+                                  "Should be a number")
+                        end
+                        tuple = [key, value]
+                    when 'range'
+                        if value.kind_of?(Range)
+                            value = [value.min, value.max]
+                        end
+
+                        unless value.kind_of?(Array)
+                            raise(TypeError,
+                                  "Invalid field value #{value} for #{key}; " +
+                                  "Should be an array")
+                        end
+                        unless value.size == 2
+                            raise(TypeError,
+                                  "Invalid field value #{value} for #{key}; " +
+                                  "Array should have exactly two values")
+                        end
+                        if value.first > value.last
+                            raise(IndexError,
+                                  "Invalid field value #{value} for #{key}; " +
+                                  "Start value not greater than end value")
+                        end
+                        
+                        begin
+                            Float(value.first)
+                            Float(value.last)
+                        rescue
+                            raise(TypeError,
+                                  "Invalid field values for #{key}; " +
+                                  "Both should be numbers")
+                        end
+
+                        tuple = [key, value]
+                    when 'in'
+                        unless value.kind_of?(Array)
+                            raise(TypeError,
+                                  "Invalid field value #{value} for #{key}; " +
+                                  "Should be an array")
+                        end
+
+                    end
+                end
+                tuple
+            end
+        end
+
+        def self.deep_copy(obj)
+            Marshal.load(Marshal.dump(obj))
+        end
+
+        # Takes a SolveBio::Filter or an Array of filter items and returns
+        # an Array that can be passed off (when converted to JSON) to a
+        # SolveBio client filter parameter. As such, the output format is
+        # highly dependent on the SolveBio API format.
+        #
+        # The filter items can be either a SolveBio::Filter, or Hash of
+        # the right form, or an Array of the right form.
+        def self.process_filters(filters)
+            rv = []
+            if filters.kind_of?(SolveBio::Filter)
+                if filters.filters
+                    rv = process_filters(filters.filters)
+                end
+            else
+                filters.each do |f|
+                    if f.kind_of?(SolveBio::Filter)
+                        if f.filters
+                            rv << process_filters(f.filters)
+                            next
+                        end
+                    elsif f.kind_of?(Hash)
+                        key = f.keys[0]
+                        val = f[key]
+
+                        if val.kind_of?(Hash)
+                            filter_filters = process_filters(val)
+                            if filter_filters.size == 1
+                                filter_filters = filter_filters[0]
+                            end
+                            rv << {key => filter_filters}
+                        else
+                            rv << {key => process_filters(val)}
+                        end
+                    elsif f.kind_of?(Array)
+                        rv << f
+                    else
+                        raise TypeError, "Invalid filter class #{f.class}"
+                    end
+                end
+            end
+            return rv
+        end
+    end
+
+    class GenomicFilter < Filter
+        # Helper class that generates filters on genomic coordinates.
+        #
+        #    Range filtering only works on "genomic" datasets
+        #    (where dataset['is_genomic'] is true).
+
+        # Standardized fields for genomic coordinates in SolveBio
+        FIELD_START = 'genomic_coordinates.start'
+        FIELD_STOP = 'genomic_coordinates.stop'
+        FIELD_CHR = 'genomic_coordinates.chromosome'
+
+        # Handles UCSC-style range queries (chr1:100-200)
+        def self.from_string(string, exact=false)
+            begin
+                chromosome, pos = string.split(':')
+            rescue ValueError
+                raise ValueError,
+                    'Please use UCSC-style format: "chr2:1000-2000"'
+            end
+
+            if pos.member?('-')
+                start, stop = pos.replace(',', '').split('-')
+            else
+                start = stop = pos.replace(',', '')
+            end
+
+            return self.new(chromosome, start, stop, exact)
+        end
+
+        # This class supports single position and range filters.
+        #
+        # By default, the filter will match any record that overlaps with
+        # the position or range specified. Exact matches must be explicitly
+        # specified using the `exact` parameter.
+        def initialize(chromosome, start, stop=nil, exact=false)
+            begin
+                if not start.nil?
+                    start = Integer(start)
+                end
+
+                stop = stop ? Integer(stop) : start
+            rescue ValueError
+                raise ValueError('Start and stop positions must be integers or nil')
+            end
+
+            if exact or start.nil?
+                f = SolveBio::Filter.new({FIELD_START => start, FIELD_STOP  => stop})
+            else
+                f = SolveBio::Filter.new({"#{FIELD_START}__lte" => start,
+                                          "#{FIELD_START}__gte" => stop})
+                if start != stop
+                    f |= SolveBio::Filter.new({"#{FIELD_START}__range" =>
+                                               [start, stop + 1]})
+                    f |= SolveBio::Filter.new({"#{FIELD_STOP}__range" =>
+                                               [start, stop + 1]})
+                end
+            end
+
+            if chromosome.nil?
+                f &= SolveBio::Filter.new({"chromosome" => nil})
+            else
+                f &= SolveBio::Filter.new({"chromosome" => chromosome.sub('chr', '')})
+            end
+
+            @filters = f.filters
+        end
+
+        def inspect
+            return "<GenomicFilter #{@filters}>"
+        end
+    end
+end