solvebio 1.5.0

data/lib/client.rb

@@ -0,0 +1,152 @@
+#!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
+require 'openssl'
+require 'net/http'
+require 'json'
+require_relative 'credentials'
+require_relative 'errors'
+
+# import textwrap
+
+# A requests-based HTTP client for SolveBio API resources
+class SolveBio::Client
+
+    attr_reader :headers, :api_host
+    attr_accessor :api_key
+
+    def initialize(api_key=nil, api_host=nil)
+        @api_key = api_key || SolveBio::api_key
+        SolveBio::api_key  ||= api_key
+        @api_host = api_host || SolveBio::API_HOST
+        # Mirroring comments from:
+        # http://ruby-doc.org/stdlib-2.1.2/libdoc/net/http/rdoc/Net/HTTP.html
+        # gzip compression is used in preference to deflate
+        # compression, which is used in preference to no compression.
+        @headers  = {
+            'Content-Type'    => 'application/json',
+            'Accept'          => 'application/json',
+            'Accept-Encoding' => 'gzip;q=1.0,deflate;q=0.6,identity;q=0.3',
+            'User-Agent'      => 'SolveBio Ruby Client %s [%s/%s]' % [
+                SolveBio::VERSION,
+                SolveBio::RUBY_IMPLEMENTATION,
+                SolveBio::RUBY_VERSION
+            ]
+        }
+    end
+
+    def request(method, url, params=nil, raw=false)
+
+        if not @api_host
+            raise SolveBio::Error.new(nil, 'No SolveBio API host is set')
+        elsif not url.start_with?(@api_host)
+            url = URI.join(@api_host, url).to_s
+        end
+
+        uri  = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+
+        # Note: there's also read_timeout and ssl_timeout
+        http.open_timeout = 80 # in seconds
+
+        if uri.scheme == 'https'
+            http.use_ssl = true
+            # FIXME? Risky - see
+            # http://www.rubyinside.com/how-to-cure-nethttps-risky-default-https-behavior-4010.html
+            http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        end
+
+        http.set_debug_output($stderr) if $DEBUG
+        SolveBio::logger.debug('API %s Request: %s' % [method.upcase, url])
+
+        request = nil
+        if ['POST', 'PUT', 'PATCH'].member?(method.upcase)
+            # FIXME? do we need to do something different for
+            # PUT and PATCH?
+            request = Net::HTTP::Post.new(uri.request_uri)
+            request.body = params.to_json
+        else
+            request = Net::HTTP::Get.new(uri.request_uri)
+        end
+        @headers.each { |k, v| request.add_field(k, v) }
+        request.add_field('Authorization', "Token #{@api_key}") if @api_key
+        response = http.request(request)
+
+        # FIXME: There's probably gzip decompression built in to
+        # net/http. Until I figure out how to get that to work, the
+        # below works.
+        case response
+        when Net::HTTPSuccess then
+            begin
+                if response['Content-Encoding'].eql?( 'gzip' ) then
+                    puts "Performing gzip decompression for response body." if $DEBUG
+                    sio = StringIO.new( response.body )
+                    gz = Zlib::GzipReader.new( sio )
+                    response.body = gz.read()
+                end
+            rescue Exception
+                puts "Error occurred (#{$!.message})" if $DEBUG
+                # handle errors
+                raise $!.message
+            end
+        end
+
+        status_code = response.code.to_i
+        if status_code < 200 or status_code >= 300
+            handle_api_error(response)
+        end
+
+        if raw
+            return response.body
+        else
+            return JSON.parse(response.body)
+        end
+    end
+
+    def handle_request_error(e)
+        # FIXME: go over this. It is still a rough translation
+        # from the python.
+        err = e.inspect
+        if e.kind_of?(requests.exceptions.RequestException)
+            msg = SolveBio::Error::Default_message
+        else
+            msg = 'Unexpected error communicating with SolveBio. ' +
+                "It looks like there's probably a configuration " +
+                'issue locally. If this problem persists, let us ' +
+                'know at contact@solvebio.com.'
+        end
+        msg = msg + "\n\n(Network error: #{err}"
+        raise SolveBio::Error.new(nil, msg)
+    end
+
+    def handle_api_error(response)
+        if [400, 401, 403, 404].member?(response.code.to_i)
+            raise SolveBio::Error.new(response)
+        else
+            SolveBio::logger.info("API Error: #{response.msg}")
+            raise SolveBio::Error.new(response)
+        end
+    end
+
+    def self.client
+        @@client ||= SolveBio::Client.new()
+    end
+
+    def self.request(*args)
+        client.request(*args)
+    end
+
+end
+
+if __FILE__ == $0
+    puts SolveBio::Client.client.headers
+    puts SolveBio::Client.client.api_host
+    client = SolveBio::Client.new(nil, 'http://google.com')
+    response = client.request('http', 'http://google.com') rescue 'no good'
+    puts response.inspect
+    puts '-' * 30
+    response = client.request('http', 'http://www.google.com') rescue 'nope'
+    puts response.inspect
+    puts '-' * 30
+    response = client.request('http', 'https://www.google.com') rescue 'nope'
+    puts response.inspect
+end

data/lib/credentials.rb

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
+# Deals with reading netrc credentials
+require_relative 'main'
+require 'netrc'
+require 'uri'
+
+#
+#    Raised if the credentials are not found.
+#
+class CredentialsError < RuntimeError
+end
+
+module SolveBio::Credentials
+
+    module_function
+
+    # SolveBio API host -- just the hostname
+    def api_host
+        URI(SolveBio::API_HOST).host
+    end
+
+    def netrc_path
+        path =
+            if ENV['NETRC_PATH']
+                File.join(ENV['NETRC_PATH'], ".netrc")
+            else
+                Netrc.default_path
+            end
+        if not File.exist?(path)
+            raise IOError, "netrc file #{path} not found"
+        end
+        path
+    end
+
+    #
+    #    Returns the tuple user / password given a path for the .netrc file.
+    #    Raises CredentialsError if no valid netrc file is found.
+    #
+    def get_credentials
+        n = Netrc.read(netrc_path)
+        return n[api_host]
+    rescue Netrc::Error => e
+        raise CredentialsError, "Could not read .netrc file: #{e}"
+    end
+    module_function :get_credentials
+
+    def delete_credentials
+        n = Netrc.read(netrc_path)
+        n.delete(api_host)
+        n.save
+    end
+
+    def save_credentials(email, api_key)
+        n = Netrc.read(netrc_path)
+        # Overwrites any existing credentials
+        n[api_host] = email, api_key
+        n.save
+    end
+end
+
+# Demo code
+if __FILE__ == $0
+    include SolveBio::Credentials
+    puts "authentication: #{netrc_path}"
+    puts "creds", get_credentials
+end

data/lib/errors.rb

@@ -0,0 +1,81 @@
+#!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
+require_relative 'main'
+
+class SolveBio::Error < 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
+            @message     = response.message
+            begin
+                @json_body = JSON.parse(response.body)
+            rescue
+                @message = '404 Not Found.' if @status_code == 404
+                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 = '%s' % @json_body['detail']
+                    end
+
+                    if @json_body.member?('non_field_errors')
+                        @message = '%s.' % \
+                            @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
+
+# Demo code
+if __FILE__ == $0
+    puts SolveBio::Error.new
+    puts SolveBio::Error.new(nil, 'Hi there').inspect
+    puts SolveBio::Error.new(nil, 'Hi there').to_s
+    puts SolveBio::Error.new(nil, ['Hello, ', 'again.']).inspect
+
+    require 'net/http'
+    response = Net::HTTPUnauthorized.new('HTTP 1.1', '404', 'No creds')
+    puts SolveBio::Error.new(response).to_s
+
+end

data/lib/filter.rb

@@ -0,0 +1,312 @@
+# -*- coding: utf-8 -*-
+require_relative 'main'
+
+# 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>
+#     * `<field>__between=[<start>, <end>]` matches anything between <start> to <end> not include either <start> or <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)
+
+class SolveBio::Filter
+
+    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 = SolveBio::Filter.normalize(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 between).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', 'between'
+                    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
+
+                    # FIXME: Should we check that value contains only numbers?
+                    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 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 = []
+        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
+        return rv
+    end
+
+
+end
+
+# Helper class that generates Range Filters from UCSC-style ranges.
+class SolveBio::RangeFilter < SolveBio::Filter
+    SUPPORTED_BUILDS = ['hg18', 'hg19', 'hg38']
+
+    #    Handles UCSC-style range queries (hg19:chr1:100-200)
+    def self.from_string(string, overlap=false)
+        begin
+            build, chromosome, pos = string.split(':')
+        rescue ValueError
+            raise ValueError,
+                'Please use UCSC-style format: "hg19:chr2:1000-2000"'
+        end
+
+        if pos.member?('-')
+            start, last = pos.replace(',', '').split('-')
+        else
+            start = last = pos.replace(',', '')
+        end
+
+        return self.new(build, chromosome, start, last, overlap=overlap)
+    end
+
+    #  Shortcut to do range queries on supported datasets.
+    def initialize(build, chromosome, start, last, overlap=false)
+        if !SUPPORTED_BUILDS.member?(build.downcase)
+            msg = "Build #{build} not supported for range filters. " +
+                "Supported builds are: #{SUPPORTED_BUILDS.join(', ')}"
+            raise Exception, msg
+        end
+
+        f = SolveBio::Filter.new({"#{build}_start__range" => [start, last]})
+
+        if overlap
+            f |=  SolveBio::Filter.
+                new({"#{build}_end__range" => [start, last]})
+        else
+            f &= SolveBio::Filter.
+                new({"#{build}_end__range" => [start, last]})
+        end
+
+        f &= SolveBio::Filter.
+            new({"#{build}_chromosome" => chromosome.sub('chr', '')})
+        @filters = f.filters
+    end
+
+    def inspect
+        return "<RangeFilter #{@filters}>"
+    end
+end
+
+
+# Demo/test code
+if __FILE__ == $0
+    filters =
+        SolveBio::Filter.new(:omim_id => 144650) |
+        SolveBio::Filter.new(:omim_id => 144600) |
+        SolveBio::Filter.new(:omim_id => 145300)
+    puts filters.inspect
+    puts SolveBio::Filter.process_filters([[:omim_id, nil]]).inspect
+    f = SolveBio::Filter.new
+    puts "%s, empty?: %s" % [f.inspect, f.empty?]
+    f_not = ~f
+    puts "%s, empty?: %s" % [f_not.inspect, f_not.empty?]
+    f2 = SolveBio::Filter.new({:style => 'Mexican', :price => 'Free'})
+    puts "%s, empty? %s" % [f2.inspect, f2.empty?]
+    f2_not = ~f2
+    puts "%s, empty? %s" % [f2_not.inspect, f2_not.empty?]
+    # FIXME: using a hash means we can't repeat chr1. Is this intended?
+    f2_or = SolveBio::Filter.new({:chr1 => '3', :chr2 => '4'}, :or)
+    puts "%s, empty %s" % [f2_or.inspect, f2_or.empty?]
+    f2_or = SolveBio::Filter.new({:chr1 => '3'}) | SolveBio::Filter.new({:chr2 => '4'})
+    puts "%s, empty %s" % [f2_or.inspect, f2_or.empty?]
+    puts((f2_or & f2).inspect)
+end