bio-ensembl-rest 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e112aedd2a2a78c4f241301731d39e2a3f094942
+  data.tar.gz: 483b616adf1743cac1b35088b59fa4d68e85e915
+SHA512:
+  metadata.gz: 7fa0521d7923a7b9aafe1427258037a27b3794c736f36b9c0bec00d2b68b051b22195abbb3bec34307735a8274fcd9e58bfbb55b02ca2db745f76748f19dd90c
+  data.tar.gz: f91ecf17d9f0a267851e936efa1d4522160d54b56ba892ef1c2ad7f659f8fcdd1e1ed0a1301cc464f519566eedaf1c5894292791acc31144116dc68caf4cb07f

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+
+matrix:
+  allow_failures:
+  - jruby-19mode 
+  - rbx-19mode
+

data/Gemfile

@@ -0,0 +1,16 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+gem "bio", ">= 1.4.3"
+gem "libxml-ruby", ">= 2" if RUBY_PLATFORM != 'java'
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "shoulda", ">= 0"
+  gem "rdoc", "~> 3.12"
+  gem "bundler", "~> 1.3.5"
+  gem "jeweler", "~> 1.8.4"
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2013 Alberto Donizetti
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,51 @@
+Ensembl Rest
+================
+
+A Ruby library for the RESTful Ensembl API.
+
+[![Build Status](https://api.travis-ci.org/ALTree/ensembl-rest.png)](https://travis-ci.org/ALTree/ensembl-rest)
+
+Obtaining
+---------
+
+```sh
+gem install ensembl-rest
+```
+for the repository:
+```sh
+git clone git://github.com/ALTree/bio-ensembl-rest
+```
+
+Usage
+-----
+
+Each of the endpoint group listed in the Ensembl REST [documentation](http://beta.rest.ensembl.org/) has its own ruby module with the same name (except for Ontologies and Taxonomy, wich is split in two modules).
+
+**A full list of modules and methods, with documentation, is available [here](https://github.com/ALTree/bio-ensembl-rest/wiki/modules-and-methods-list)**.
+
+To make a request to an endpoint, use the appropriate method in the relative module. For example, to access the `sequence/region/:species/:region ` endpoint in the Sequence group, use the `sequence_region` method in the `Sequence` module:
+
+```ruby
+require 'bio-ensembl-rest'
+include EnsemblRest
+
+EnsemblRest.connect_db # connect to database
+puts Sequence.sequence_region 'Homo sapiens', 'X:1000000..1000025:1'
+
+# GAAACAGCTACTTGGAAGGCTGAAGC
+```
+
+Documentation
+-----------
+See the [ensembl-rest wiki page](https://github.com/ALTree/bio-ensembl-rest/wiki).
+
+## Known issues
+
+### version-specific issues
+
+* On jruby-1.7, methods in the ComparativeGenomics module fail if called with `response: ruby`,
+due to a C dependency in the 'bio' gem.
+
+* On rubinius, methods in the ComparativeGenomics module fail if called with `response: ruby`,
+due to a C dependency in the 'bio' gem.
+

data/Rakefile

@@ -0,0 +1,45 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  gem.name = "bio-ensembl-rest"
+  gem.version = '0.1.0'
+  gem.homepage = "http://github.com/ALTree/bio-ensembl-rest"
+  gem.license = "MIT"
+  gem.summary = "Ruby Ensembl REST api"
+  gem.description = "A Ruby library for the RESTful Ensembl API."
+  gem.email = "alb.donizetti@gmail.com"
+  gem.authors = ["Alberto Donizetti"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.test_files = FileList['test/test-*.rb']
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "ensembl-rest #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/bio-ensembl-rest.rb

@@ -0,0 +1,19 @@
+# Please require your code below, respecting the naming conventions in the
+# bioruby directory tree.
+#
+# For example, say you have a plugin named bio-plugin, the only uncommented
+# line in this file would be 
+#
+#   require 'bio/bio-plugin/plugin'
+#
+# In this file only require other files. Avoid other source code.
+
+require 'bio' 
+require 'net/http'
+require 'open-uri'
+require 'json'
+
+Dir[File.dirname(__FILE__) + '/bio-ensembl-rest/*.rb'].each do |file| 
+  require file
+end
+

data/lib/bio-ensembl-rest/comparative-genomics.rb

@@ -0,0 +1,117 @@
+module EnsemblRest
+  module ComparativeGenomics
+
+    ##
+    # Retrieves Gene Tree dumps for a given Gene Tree stable identifier
+    def self.genetree_id(id, opts = {})
+      return _genetree_generic id, 'id', opts
+    end
+
+    ##
+    #  Retrieves the Gene Tree that contains the given stable identifier
+    def self.genetree_member_id(id, opts = {})
+      return _genetree_generic id, 'member', opts
+    end
+
+    # generic method used by genetree_id and genetree_member_id
+    def self._genetree_generic(id, type, opts = {}) # :nodoc:
+      opts = EnsemblRest.parse_options opts
+      url = type == 'id' ? "/genetree/id/#{id}" : "/genetree/member/id/#{id}"
+      path = EnsemblRest.build_path url, opts
+
+      if opts['content-type'] == 'ruby'
+        plain_opts = opts.clone
+        plain_opts['content-type'] = 'text/x-phyloxml+xml'
+        return Bio::PhyloXML::Parser.new _genetree_generic id, type, plain_opts
+      end
+
+      return EnsemblRest.fetch_data path, opts, 'compara'
+    end
+
+
+    ##
+    # Retrieves a Gene Tree containing the Gene identified by the given symbol
+    def self.genetree_member_symbol(species, symbol, opts = {})
+      opts = EnsemblRest.parse_options opts
+      path = EnsemblRest.build_path "/genetree/member/symbol/#{species}/#{symbol}", opts
+
+      if opts['content-type'] == 'ruby'
+        plain_opts = opts.clone
+        plain_opts['content-type'] = 'text/x-phyloxml+xml'
+        return Bio::PhyloXML::Parser.new genetree_member_symbol(species, symbol, plain_opts)
+      end
+
+      return EnsemblRest.fetch_data path, opts, 'compara'
+    end
+
+
+    ##
+    # Retrieves homology information by ensembl gene id
+    def self.homology_id(id, opts = {})
+      opts = EnsemblRest.parse_options opts
+      path = EnsemblRest.build_path "/homology/id/#{id}", opts
+
+      if opts['content-type'] == 'ruby'
+        plain_opts = opts.clone
+        plain_opts['content-type'] = 'application/json'
+        data = JSON.parse ComparativeGenomics.homology_id id, plain_opts
+        return build_homology_class data
+      end
+
+      return EnsemblRest.fetch_data path, opts, 'compara'
+    end
+
+
+    ##
+    # Retrieves homology information by symbol
+    def self.homology_symbol(species, symbol, opts = {})
+      opts = EnsemblRest.parse_options opts
+      path = EnsemblRest.build_path "/homology/symbol/#{species}/#{symbol}", opts
+
+      if opts['content-type'] == 'ruby'
+        plain_opts = opts.clone
+        plain_opts['content-type'] = 'application/json'
+        data = JSON.parse ComparativeGenomics.homology_symbol species, symbol, plain_opts
+        return build_homology_class data
+      end
+
+      return EnsemblRest.fetch_data path, opts, 'compara'      
+
+    end
+
+
+    # here we define the Homology class
+    Object.const_set("Homology", Class.new)
+
+    def self.build_homology_class(json_data) # :nodoc:
+      # extract the homologies list (homology = ruby hash obj)
+      homologies_data = json_data['data'][0]['homologies'] # this is a list of hashes
+
+      # retrieve homology keys to make a list of methods
+      homology_methods = []
+      homologies_data.first.each { |k, _| homology_methods << k.to_sym }
+
+      # we define an attr_accessor for each symbol in homology_methods
+      # and a 'bio_methods' attribute with all the newly defined methods
+      homology_methods.each { |k, _| Homology.class_eval "attr_accessor :#{k}" }
+      Homology.class_eval "attr_accessor :bio_methods" 
+
+      # we will return a list of homology objects
+      homologies = []
+
+      # let's build the list
+      homologies_data.each do |hom| # cycle over the homologies we were given
+        h = Homology.new            # we instantiate an Homology obj
+        hom.each do |k, v|          # for each key,value in the homology hash
+          h.send "#{k}=".to_sym, v  # we use the 'key=' method to set 'value'
+        end
+        h.send :bio_methods=, homology_methods  # set the bio_methods param
+        homologies << h             # add the obj to the list to be returned             
+      end
+
+      return homologies
+    end
+
+
+  end
+end

data/lib/bio-ensembl-rest/cross-reference.rb

@@ -0,0 +1,55 @@
+module EnsemblRest
+  module CrossReference
+
+    ##
+    # Perform lookups of Ensembl Identifiers and retrieve their external cross 
+    # references in other databases
+    def self.xrefs_id(id, opts = {})
+      opts = EnsemblRest.parse_options opts
+      path = EnsemblRest.build_path "/xrefs/id/#{id}", opts
+
+      if opts['content-type'] == 'ruby'
+        plain_opts = opts.clone
+        plain_opts['content-type'] = 'application/json'
+        return JSON.parse xrefs_id id, plain_opts
+      end
+
+      return EnsemblRest.fetch_data path, opts, 'crossreference'      
+    end
+
+
+    ##
+    # Performs a lookup based upon the primary accession or display label of 
+    # an external reference and returning the information we hold about the entry
+    def self.xrefs_name(species, name, opts = {})
+      opts = EnsemblRest.parse_options opts
+      path = EnsemblRest.build_path "/xrefs/name/#{species}/#{name}", opts
+
+      if opts['content-type'] == 'ruby'
+        plain_opts = opts.clone
+        plain_opts['content-type'] = 'application/json'
+        return JSON.parse xrefs_name species, name, plain_opts
+      end
+
+      return EnsemblRest.fetch_data path, opts, 'crossreference'      
+    end   
+
+
+    ##
+    # Looks up an external symbol and returns all Ensembl objects linked to it
+    def self.xrefs_symbol(species, symbol, opts = {})
+      opts = EnsemblRest.parse_options opts
+      path = EnsemblRest.build_path "/xrefs/symbol/#{species}/#{symbol}", opts
+
+      if opts['content-type'] == 'ruby'
+        plain_opts = opts.clone
+        plain_opts['content-type'] = 'application/json'
+        return JSON.parse xrefs_symbol species, symbol, plain_opts
+      end
+
+      return EnsemblRest.fetch_data path, opts, 'crossreference'      
+    end  
+
+
+  end
+end

data/lib/bio-ensembl-rest/ensembl-rest-main.rb

@@ -0,0 +1,108 @@
+module EnsemblRest 
+  ## start HTTP database connection ##
+
+  def self.connect_db 
+    $SERVER = URI.parse 'http://beta.rest.ensembl.org'
+    $HTTP_CONNECTION = Net::HTTP.new($SERVER.host, $SERVER.port)
+  end
+
+
+  ## parse options stuff ##
+  def self.parse_options(opts) # :nodoc:
+    parsed_opts = {}
+    opts.each {|k, v| parsed_opts[k.to_s] = v}
+
+    parse_format parsed_opts
+    parse_true_false parsed_opts
+  end
+
+  def self.parse_true_false(opts) # :nodoc:
+    opts.each do |k, v|
+      if v.instance_of?(TrueClass)
+        opts[k] = 1
+      elsif v.instance_of?(FalseClass)
+        opts[k] = 0
+      end
+    end
+  end
+
+  def self.parse_format(opts) # :nodoc:
+    supported_formats = {
+      'text' => 'text/plain',
+      'fasta' => 'text/x-fasta',
+      'gff3' => 'ext/x-gff3',
+      'json' => 'application/json',
+      'msgpack' => 'application/x-msgpack',
+      'nh' => 'text/x-nh',
+      'seqxml' => 'text/x-seqxml+xml', 
+      'sereal' => 'application/x-sereal',
+      'phyloxml' => 'text/x-phyloxml+xml',
+      'xml' => 'text/xml',
+      'yaml' => 'text/x-yaml'
+    }
+    if opts.has_key?('response')
+      req = opts['response']
+      if supported_formats[req]
+        opts['content-type'] = supported_formats[req]
+      else
+        opts['content-type'] = req
+      end
+      opts.delete 'response'
+    end
+    opts
+  end
+
+
+  ## HTTP request stuff ##
+
+  def self.build_path(home, opts) # :nodoc:
+    path = home + '?'
+    opts.each { |k,v| path << "#{k}=#{v};"  if k != 'content-type' }
+    path[-1] = '' if not opts
+    URI::encode path
+  end
+
+  # TODO: add tests to check if this default stuff is ok
+  def self.fetch_data(path, opts, mod) # :nodoc:
+    # what we should set as content-type in the header
+    # to keep ensembl happy when the the user does not
+    # use the format parameter to set the return type
+    default_types = {
+      'sequence' => 'text/plain',
+      'compara' => 'text/xml',
+      'crossreference' => 'application/json',
+      'features' => 'application/json',
+      'information' => 'application/json',
+      'lookup' => 'application/json',
+      'mapping' => 'application/json',
+      'ontologies' => 'application/json',
+      'taxonomy' => 'application/json',
+      'variation' => 'application/json'
+    }
+    request = Net::HTTP::Get.new path
+    request.content_type = opts['content-type'] || default_types[mod]
+    response = $HTTP_CONNECTION.request request
+    return check_response response
+  end
+
+  def self.check_response(response) # :nodoc:
+    case response.code 
+    when '200'
+      return response.body
+    when '400'
+      raise 'Bad request: ' + response.body
+    when '404' 
+      raise 'Not Found'
+    when '415'
+      raise 'Unsupported Media Type'
+    when '429' 
+      raise 'Too many requests'
+    when '503'
+      raise 'Service Unavailable'
+    else
+      raise "Bad response code: #{response.code}"
+    end
+  end
+
+
+end