eutils 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/.document ADDED
@@ -0,0 +1,5 @@
1
+ README.rdoc
2
+ lib/**/*.rb
3
+ bin/*
4
+ features/**/*.feature
5
+ LICENSE
data/.gitignore ADDED
@@ -0,0 +1,21 @@
1
+ ## MAC OS
2
+ .DS_Store
3
+
4
+ ## TEXTMATE
5
+ *.tmproj
6
+ tmtags
7
+
8
+ ## EMACS
9
+ *~
10
+ \#*
11
+ .\#*
12
+
13
+ ## VIM
14
+ *.swp
15
+
16
+ ## PROJECT::GENERAL
17
+ coverage
18
+ rdoc
19
+ pkg
20
+
21
+ ## PROJECT::SPECIFIC
data/MIT-LICENSE ADDED
@@ -0,0 +1,20 @@
1
+ Copyright (c) 2009 Joon Lee
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining
4
+ a copy of this software and associated documentation files (the
5
+ "Software"), to deal in the Software without restriction, including
6
+ without limitation the rights to use, copy, modify, merge, publish,
7
+ distribute, sublicense, and/or sell copies of the Software, and to
8
+ permit persons to whom the Software is furnished to do so, subject to
9
+ the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be
12
+ included in all copies or substantial portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
data/README.rdoc ADDED
@@ -0,0 +1,17 @@
1
+ = eutils
2
+
3
+ Description goes here.
4
+
5
+ == Note on Patches/Pull Requests
6
+
7
+ * Fork the project.
8
+ * Make your feature addition or bug fix.
9
+ * Add tests for it. This is important so I don't break it in a
10
+ future version unintentionally.
11
+ * Commit, do not mess with rakefile, version, or history.
12
+ (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
13
+ * Send me a pull request. Bonus points for topic branches.
14
+
15
+ == Copyright
16
+
17
+ Copyright (c) 2010 Joon Lee. See LICENSE for details.
data/Rakefile ADDED
@@ -0,0 +1,54 @@
1
+ require 'rubygems'
2
+ require 'rake'
3
+
4
+ begin
5
+ require 'jeweler'
6
+ Jeweler::Tasks.new do |gem|
7
+ gem.name = "eutils"
8
+ gem.summary = %Q{Lightweight Ruby API for NCBI Eutils}
9
+ gem.description = %Q{This gem only provides API for NCBI Eutils. If you need full access to other NCBI databases, try BioRuby (bio gem) instead.}
10
+ gem.email = "seouri@gmail.com"
11
+ gem.homepage = "http://github.com/seouri/eutils"
12
+ gem.authors = ["Joon Lee"]
13
+ gem.add_development_dependency "shoulda", ">= 0"
14
+ gem.add_dependency "nokogiri"
15
+ # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
16
+ end
17
+ Jeweler::GemcutterTasks.new
18
+ rescue LoadError
19
+ puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
20
+ end
21
+
22
+ require 'rake/testtask'
23
+ Rake::TestTask.new(:test) do |test|
24
+ test.libs << 'lib' << 'test'
25
+ test.pattern = 'test/**/test_*.rb'
26
+ test.verbose = true
27
+ end
28
+
29
+ begin
30
+ require 'rcov/rcovtask'
31
+ Rcov::RcovTask.new do |test|
32
+ test.libs << 'test'
33
+ test.pattern = 'test/**/test_*.rb'
34
+ test.verbose = true
35
+ end
36
+ rescue LoadError
37
+ task :rcov do
38
+ abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
39
+ end
40
+ end
41
+
42
+ task :test => :check_dependencies
43
+
44
+ task :default => :test
45
+
46
+ require 'rake/rdoctask'
47
+ Rake::RDocTask.new do |rdoc|
48
+ version = File.exist?('VERSION') ? File.read('VERSION') : ""
49
+
50
+ rdoc.rdoc_dir = 'rdoc'
51
+ rdoc.title = "eutils #{version}"
52
+ rdoc.rdoc_files.include('README*')
53
+ rdoc.rdoc_files.include('lib/**/*.rb')
54
+ end
data/VERSION ADDED
@@ -0,0 +1 @@
1
+ 0.1.0
data/eutils.gemspec ADDED
@@ -0,0 +1,56 @@
1
+ # Generated by jeweler
2
+ # DO NOT EDIT THIS FILE DIRECTLY
3
+ # Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
4
+ # -*- encoding: utf-8 -*-
5
+
6
+ Gem::Specification.new do |s|
7
+ s.name = %q{eutils}
8
+ s.version = "0.1.0"
9
+
10
+ s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
11
+ s.authors = ["Joon Lee"]
12
+ s.date = %q{2010-08-25}
13
+ s.description = %q{This gem only provides API for NCBI Eutils. If you need full access to other NCBI databases, try BioRuby (bio gem) instead.}
14
+ s.email = %q{seouri@gmail.com}
15
+ s.extra_rdoc_files = [
16
+ "README.rdoc"
17
+ ]
18
+ s.files = [
19
+ ".document",
20
+ ".gitignore",
21
+ "MIT-LICENSE",
22
+ "README.rdoc",
23
+ "Rakefile",
24
+ "VERSION",
25
+ "eutils.gemspec",
26
+ "lib/eutils.rb",
27
+ "test/helper.rb",
28
+ "test/test_eutils.rb"
29
+ ]
30
+ s.homepage = %q{http://github.com/seouri/eutils}
31
+ s.rdoc_options = ["--charset=UTF-8"]
32
+ s.require_paths = ["lib"]
33
+ s.rubygems_version = %q{1.3.6}
34
+ s.summary = %q{Lightweight Ruby API for NCBI Eutils}
35
+ s.test_files = [
36
+ "test/helper.rb",
37
+ "test/test_eutils.rb"
38
+ ]
39
+
40
+ if s.respond_to? :specification_version then
41
+ current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
42
+ s.specification_version = 3
43
+
44
+ if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
45
+ s.add_development_dependency(%q<shoulda>, [">= 0"])
46
+ s.add_runtime_dependency(%q<nokogiri>, [">= 0"])
47
+ else
48
+ s.add_dependency(%q<shoulda>, [">= 0"])
49
+ s.add_dependency(%q<nokogiri>, [">= 0"])
50
+ end
51
+ else
52
+ s.add_dependency(%q<shoulda>, [">= 0"])
53
+ s.add_dependency(%q<nokogiri>, [">= 0"])
54
+ end
55
+ end
56
+
data/lib/eutils.rb ADDED
@@ -0,0 +1,172 @@
1
+ require 'cgi'
2
+ require 'net/http'
3
+ require 'uri'
4
+ require 'active_support/core_ext/hash/conversions'
5
+ # Synopsis
6
+ # eutils = Eutils.new("medvane", "joon@medvane.org")
7
+ # eutils.einfo
8
+ class Eutils
9
+ # Global constants
10
+ # * host: http://http://eutils.ncbi.nlm.nih.gov
11
+ # * EUTILS_INTERVAL
12
+ EUTILS_HOST = "http://eutils.ncbi.nlm.nih.gov/entrez/eutils/"
13
+ EUTILS_INTERVAL = 1.0 / 3.0
14
+ @@last_access = nil
15
+ @@last_access_mutex = nil
16
+ attr_accessor :tool, :email
17
+ ActiveSupport::XmlMini.backend = "LibXMLSAX" # or "NokogiriSAX"
18
+
19
+ def initialize(tool = nil, email = nil)
20
+ @tool, @email = tool, email
21
+ end
22
+
23
+ # EInfo: Provides field index term counts, last update, and available links for each database.
24
+ # See also: http://eutils.ncbi.nlm.nih.gov/corehtml/query/static/einfo_help.html
25
+ def einfo(db = nil)
26
+ db.strip! if db.class == String
27
+ server = EUTILS_HOST + "einfo.fcgi"
28
+ params = {"db" => db}
29
+ response = post_eutils(server, params)
30
+ if db.nil? || db.empty?
31
+ return response.scan(/<DbName>(\w+)<\/DbName>/).flatten
32
+ else
33
+ return Hash.from_xml(response)
34
+ end
35
+ end
36
+
37
+ # ESearch: Searches and retrieves primary IDs (for use in EFetch, ELink, and ESummary) and term translations and optionally retains results for future use in the user's environment.
38
+ # See also: http://eutils.ncbi.nlm.nih.gov/corehtml/query/static/esearch_help.html
39
+ # eutils.esearch("autism")
40
+ def esearch(term, db = "pubmed", params = {})
41
+ term.strip! if term.class == String
42
+ params["term"] = term
43
+ params["db"] = db
44
+ params["usehistory"] ||= "y"
45
+ server = EUTILS_HOST + "esearch.fcgi"
46
+ response = post_eutils(server, params)
47
+ return Hash.from_xml(response)
48
+ end
49
+
50
+ # EPost: Posts a file containing a list of primary IDs for future use in the user's environment to use with subsequent search strategies.
51
+ # See also: http://eutils.ncbi.nlm.nih.gov/corehtml/query/static/epost_help.html
52
+ # returns: webenv, querykey. Both nil for invalid epost.
53
+ def epost(ids, db = "pubmed", params = {})
54
+ params["id"] = ids.join(",")
55
+ params["db"] = db
56
+ server = EUTILS_HOST + "epost.fcgi"
57
+ response = post_eutils(server, params)
58
+ querykey = response.scan(/<QueryKey>(\d+)<\/QueryKey>/).flatten.first.to_i
59
+ querykey = nil if querykey == 0
60
+ webenv = response.scan(/<WebEnv>(\S+)<\/WebEnv>/).flatten.first
61
+ return webenv, querykey
62
+ end
63
+
64
+ # ESummary: Retrieves document summaries from a list of primary IDs or from the user's environment.
65
+ # See also: http://eutils.ncbi.nlm.nih.gov/corehtml/query/static/esummary_help.html
66
+ def esummary(ids, db = "pubmed", params = {})
67
+ params["id"] = ids.join(",")
68
+ params["db"] = db
69
+ server = EUTILS_HOST + "esummary.fcgi"
70
+ response = post_eutils(server, params)
71
+ return Hash.from_xml(response)
72
+ end
73
+
74
+ # EFetch: Retrieves records in the requested format from a list of one or more primary IDs or from the user's environment.
75
+ # See also: http://eutils.ncbi.nlm.nih.gov/corehtml/query/static/efetch_help.html
76
+ def efetch(db, webenv, query_key, params = {})
77
+ params["db"] = db
78
+ params["WebEnv"] = webenv
79
+ params["query_key"] = query_key
80
+ params["retmode"] ||= "xml"
81
+ params["retstart"] ||= 0
82
+ params["retmax"] ||= 10
83
+ server = EUTILS_HOST + "efetch.fcgi"
84
+ response = post_eutils(server, params)
85
+ if params["retmode"] == "xml"
86
+ return Hash.from_xml(response)
87
+ else
88
+ return response
89
+ end
90
+ end
91
+
92
+ # ELink: Checks for the existence of an external or Related Articles link from a list of one or more primary IDs. Retrieves primary IDs and relevancy scores for links to Entrez databases or Related Articles; creates a hyperlink to the primary LinkOut provider for a specific ID and database, or lists LinkOut URLs and Attributes for multiple IDs.
93
+ # See also: http://eutils.ncbi.nlm.nih.gov/corehtml/query/static/elink_help.html
94
+ def elink
95
+
96
+ end
97
+
98
+ # EGQuery: Provides Entrez database counts in XML for a single search using Global Query.
99
+ # See also: http://eutils.ncbi.nlm.nih.gov/corehtml/query/static/egquery_help.html
100
+ def egquery(term)
101
+ term.strip! if term.class == String
102
+ server = EUTILS_HOST + "egquery.fcgi"
103
+ params = {"term" => term}
104
+ response = post_eutils(server, params)
105
+ return Hash.from_xml(response)
106
+ end
107
+
108
+ # ESpell: Retrieves spelling suggestions.
109
+ # See also: http://eutils.ncbi.nlm.nih.gov/corehtml/query/static/espell_help.html
110
+ def espell(term)
111
+ term.strip! if term.class == String
112
+ server = EUTILS_HOST + "espell.fcgi"
113
+ params = {"db" => "pubmed", "term" => term}
114
+ response = post_eutils(server, params)
115
+ corrected = response.scan(/<CorrectedQuery>(.+)<\/CorrectedQuery>/).flatten.first.to_s
116
+ corrected = term if corrected.empty?
117
+ return corrected
118
+ end
119
+
120
+ private
121
+
122
+ def post_eutils(server, params)
123
+ check_tool_and_email
124
+ ncbi_access_wait
125
+ params["tool"] = tool
126
+ params["email"] = email
127
+ response = Net::HTTP.post_form(URI.parse(server), params)
128
+ return response.body
129
+ end
130
+
131
+ # (Private) Sleeps until allowed to access. Adapted from BioRuby
132
+ # ---
133
+ # *Arguments*:
134
+ # * (required) _wait_: wait unit time
135
+ # *Returns*:: (undefined)
136
+ def ncbi_access_wait(wait = EUTILS_INTERVAL)
137
+ @@last_access_mutex ||= Mutex.new
138
+ @@last_access_mutex.synchronize {
139
+ if @@last_access
140
+ duration = Time.now - @@last_access
141
+ if wait > duration
142
+ sleep wait - duration
143
+ end
144
+ end
145
+ @@last_access = Time.now
146
+ }
147
+ nil
148
+ end
149
+
150
+ # (Private) Checks parameters as NCBI requires. Adapted from BioRuby
151
+ # If no email or tool parameter, raises an error.
152
+ #
153
+ # NCBI announces that "Effective on
154
+ # June 1, 2010, all E-utility requests, either using standard URLs or
155
+ # SOAP, must contain non-null values for both the &tool and &email
156
+ # parameters. Any E-utility request made after June 1, 2010 that does
157
+ # not contain values for both parameters will return an error explaining
158
+ # that these parameters must be included in E-utility requests."
159
+ # ---
160
+ # *Arguments*:
161
+ # * (required) _opts_: Hash containing parameters
162
+ # *Returns*:: (undefined)
163
+ def check_tool_and_email
164
+ if @email.to_s.empty? then
165
+ raise 'Set email parameter for the query, or set eutils.email = "(your email address)"'
166
+ end
167
+ if @tool.to_s.empty? then
168
+ raise 'Set tool parameter for the query, or set eutils.tool = "(your tool name)"'
169
+ end
170
+ nil
171
+ end
172
+ end
data/test/helper.rb ADDED
@@ -0,0 +1,10 @@
1
+ require 'rubygems'
2
+ require 'test/unit'
3
+ require 'shoulda'
4
+
5
+ $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
6
+ $LOAD_PATH.unshift(File.dirname(__FILE__))
7
+ require 'eutils'
8
+
9
+ class Test::Unit::TestCase
10
+ end
@@ -0,0 +1,87 @@
1
+ require 'helper'
2
+
3
+ class TestEutils < Test::Unit::TestCase
4
+ tool = "eutilstest"
5
+ email = "seouri@gmail.com"
6
+ eutils = Eutils.new(tool, email)
7
+ should "set tool and email at instance creation" do
8
+ assert_equal eutils.tool, tool
9
+ assert_equal eutils.email, email
10
+ end
11
+
12
+ should "set tool and email after instance creation" do
13
+ eutils_no_tool_email = Eutils.new
14
+ eutils_no_tool_email.tool = tool
15
+ eutils_no_tool_email.email = email
16
+ assert_equal eutils_no_tool_email.tool, tool
17
+ assert_equal eutils_no_tool_email.email, email
18
+ end
19
+
20
+ should "raise runtime error without tool or email" do
21
+ eutils_no = Eutils.new
22
+ assert_raise RuntimeError do
23
+ eutils_no.einfo
24
+ end
25
+ end
26
+
27
+ should "get array of db names from EInfo with no parameter" do
28
+ db = eutils.einfo
29
+ assert_equal Array, db.class
30
+ assert_equal true, db.include?("pubmed")
31
+ assert_equal Array, eutils.einfo("").class
32
+ assert_equal Array, eutils.einfo(" ").class
33
+ end
34
+
35
+ should "get a hash from EInfo with db parameter" do
36
+ i = eutils.einfo("pubmed")
37
+ assert_equal Hash, i.class
38
+ assert_equal "eInfoResult", i.keys.first
39
+ assert_equal "pubmed", i['eInfoResult']['DbInfo']['DbName']
40
+ end
41
+
42
+ should "get a hash from ESearch for a term" do
43
+ r = eutils.esearch("cancer")
44
+ assert_equal Hash, r.class
45
+ assert_equal "cancer", r["eSearchResult"]["TranslationSet"]["Translation"]["From"]
46
+ assert_equal Array, r["eSearchResult"]["IdList"]["Id"].class
47
+ end
48
+
49
+ should "get webenv and querykey from EPost for posted ids" do
50
+ ids = [11877539, 11822933, 11871444]
51
+ webenv, querykey = eutils.epost(ids)
52
+ assert_equal 1, querykey
53
+ assert_equal "NCID", webenv.scan(/^(\w{4})/).flatten.first
54
+ webenv, querykey = eutils.epost(ids, "invalid")
55
+ assert_nil querykey
56
+ assert_nil webenv
57
+ end
58
+
59
+ should "get a hash from ESummary for posted ids" do
60
+ ids = [11850928, 11482001]
61
+ i = eutils.esummary(ids)
62
+ assert_equal Hash, i.class
63
+ assert_equal ids[0], i['eSummaryResult']['DocSum'][0]['Id'].to_i
64
+ end
65
+
66
+ should "get a hash from EFetch for ESearch result" do
67
+ s = eutils.esearch("cancer")
68
+ webenv = s["eSearchResult"]["WebEnv"]
69
+ query_key = s["eSearchResult"]["QueryKey"]
70
+ r = eutils.efetch("pubmed", webenv, query_key)
71
+ assert_equal Hash, r.class
72
+ assert_equal "PubmedArticleSet", r.keys.first
73
+ end
74
+
75
+ should "get spelling suggestion for a term" do
76
+ assert_equal "breast cancer", eutils.espell("brest cancr")
77
+ assert_equal "breast cancer", eutils.espell("brest cancer")
78
+ assert_equal "", eutils.espell(" ")
79
+ end
80
+
81
+ should "get hash from EGQuery" do
82
+ i = eutils.egquery("autism")
83
+ assert_equal Hash, i.class
84
+ assert_equal "Result", i.keys.first
85
+ assert_equal "autism", i["Result"]["Term"]
86
+ end
87
+ end
metadata ADDED
@@ -0,0 +1,95 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: eutils
3
+ version: !ruby/object:Gem::Version
4
+ prerelease: false
5
+ segments:
6
+ - 0
7
+ - 1
8
+ - 0
9
+ version: 0.1.0
10
+ platform: ruby
11
+ authors:
12
+ - Joon Lee
13
+ autorequire:
14
+ bindir: bin
15
+ cert_chain: []
16
+
17
+ date: 2010-08-25 00:00:00 -04:00
18
+ default_executable:
19
+ dependencies:
20
+ - !ruby/object:Gem::Dependency
21
+ name: shoulda
22
+ prerelease: false
23
+ requirement: &id001 !ruby/object:Gem::Requirement
24
+ requirements:
25
+ - - ">="
26
+ - !ruby/object:Gem::Version
27
+ segments:
28
+ - 0
29
+ version: "0"
30
+ type: :development
31
+ version_requirements: *id001
32
+ - !ruby/object:Gem::Dependency
33
+ name: nokogiri
34
+ prerelease: false
35
+ requirement: &id002 !ruby/object:Gem::Requirement
36
+ requirements:
37
+ - - ">="
38
+ - !ruby/object:Gem::Version
39
+ segments:
40
+ - 0
41
+ version: "0"
42
+ type: :runtime
43
+ version_requirements: *id002
44
+ description: This gem only provides API for NCBI Eutils. If you need full access to other NCBI databases, try BioRuby (bio gem) instead.
45
+ email: seouri@gmail.com
46
+ executables: []
47
+
48
+ extensions: []
49
+
50
+ extra_rdoc_files:
51
+ - README.rdoc
52
+ files:
53
+ - .document
54
+ - .gitignore
55
+ - MIT-LICENSE
56
+ - README.rdoc
57
+ - Rakefile
58
+ - VERSION
59
+ - eutils.gemspec
60
+ - lib/eutils.rb
61
+ - test/helper.rb
62
+ - test/test_eutils.rb
63
+ has_rdoc: true
64
+ homepage: http://github.com/seouri/eutils
65
+ licenses: []
66
+
67
+ post_install_message:
68
+ rdoc_options:
69
+ - --charset=UTF-8
70
+ require_paths:
71
+ - lib
72
+ required_ruby_version: !ruby/object:Gem::Requirement
73
+ requirements:
74
+ - - ">="
75
+ - !ruby/object:Gem::Version
76
+ segments:
77
+ - 0
78
+ version: "0"
79
+ required_rubygems_version: !ruby/object:Gem::Requirement
80
+ requirements:
81
+ - - ">="
82
+ - !ruby/object:Gem::Version
83
+ segments:
84
+ - 0
85
+ version: "0"
86
+ requirements: []
87
+
88
+ rubyforge_project:
89
+ rubygems_version: 1.3.6
90
+ signing_key:
91
+ specification_version: 3
92
+ summary: Lightweight Ruby API for NCBI Eutils
93
+ test_files:
94
+ - test/helper.rb
95
+ - test/test_eutils.rb