Class: InterMine::Service
- Inherits:
-
Object
- Object
- InterMine::Service
- Extended by:
- Forwardable
- Defined in:
- lib/intermine/service.rb
Overview
A Representation of Connection to an InterMine Webservice
Synopsis
require "intermine/service"
service = Service.new("www.flymine.org/query")
query = service.query("Gene")
list = service.list("My-Favourite-List")
template = service.template("Probe_Gene")
model = service.model
Description
The service object is the gateway to all InterMine webservice functionality, and the mechanism by which resources such as queries, lists, templates and models can be obtained. In itself, it doen’t do much, but it facilitates all the operations that can be achieved with the InterMine API.
Using Queries
service.query("Gene").
select("*", "proteins.proteinDomains.*").
where(:symbol => %{h bib r eve zen}).
order_by(:molecularWeight).
each_result do |gene|
handle_result(gene)
end
Queries are arbitrarily complex requests for data over the whole resources of the data-warehouse, similar in scope and design to the SQL queries that they are eventually run as in the webservice. The PathQuery::Query object can be obtained directly from the service with the Service#query constructor. See PathQuery::Query for more details.
Using Templates
service.template("Probe_Genes").each_row(:A => "probeid") do |row|
puts row["gene.primaryIdentifier"]
end
Templates are a simpler way of running queries, as they are mostly predefined, and simply require a parameter or two to be changed to get different results. They are an effective way of saving and repeating workflows, and can be precomputed to improve response times for queries you run frequently.
See PathQuery::Template
Using Lists
new_list = service.create_list("my/gene_list.txt", "Gene", ["experimentA", "projectB"])
existing_list = service.list("Genes I'm interested in")
intersection = new_list & existing_list
intersection.name = "My genes from experimentA"
Lists are saved result-sets and user curated collections of objects of a particular type. You may have a list of Genes you are particularly interested in, or Pathways that concern your research. Using lists simplifies queries against large groups of objects at once, and allows for more streamlined analysis. Unlike queries and (to a degree) Templates, Lists are not just about reading in information - they can be created, renamed, modified, deleted. You can manage your lists effectively and quickly using the API.
Inspecting the model
model = service.model
puts "Classes in the model:"
model.classes.each do |c|
puts c.name
end
The data model, which defines what queries are possible in the data-warehouse, is fully introspectible and queriable. This allows for sophisticated meta-programming and dynamic query generation.
:include:contact_header.rdoc
Constant Summary collapse
- VERSION_PATH =
"/version"
- RELEASE_PATH =
"/version/release"
- MODEL_PATH =
"/model/json"
- TEMPLATES_PATH =
"/templates"
- QUERY_RESULTS_PATH =
"/query/results"
- QUERY_TO_LIST_PATH =
"/query/tolist/json"
- QUERY_APPEND_PATH =
"/query/append/tolist/json"
- TEMPLATE_RESULTS_PATH =
"/template/results"
- TEMPLATE_TO_LIST_PATH =
"/template/tolist/json"
- TEMPLATE_APPEND_PATH =
"/template/append/tolist/json"
- LISTS_PATH =
"/lists/json"
- LIST_APPEND_PATH =
"/lists/append/json"
- LIST_RENAME_PATH =
"/lists/rename/json"
- LIST_UNION_PATH =
"/lists/union/json"
- LIST_DIFFERENCE_PATH =
"/lists/diff/json"
- LIST_INTERSECTION_PATH =
"/lists/intersect/json"
- LIST_SUBTRACTION_PATH =
"/lists/subtract/json"
- LIST_TAG_PATH =
"/list/tags/json"
- LIST_ENRICHMENT_PATH =
"/list/enrichment"
Instance Attribute Summary collapse
-
#broken_templates ⇒ Object
readonly
A collection of the names of any templates that this service was not able to parse, and you will thus not be able to access.
-
#root ⇒ Object
readonly
The root of the query.
-
#token ⇒ Object
readonly
The token you supplied to the constructor.
-
#version ⇒ Object
readonly
The webservice version.
Instance Method Summary collapse
-
#get_list_data ⇒ Object
Get the data used for constructing the lists.
-
#initialize(root, token = nil, mock_model = nil) ⇒ Service
constructor
Construct a new service.
-
#model ⇒ Object
(also: #get_model)
call-seq: model() => Model.
-
#params ⇒ Object
Get the basic parameters used by all requests.
-
#query(rootClass = nil) ⇒ Object
(also: #new_query)
call-seq: query(rootClass=nil) => PathQuery::Query.
-
#release ⇒ Object
Return the release string.
-
#select(*columns) ⇒ Object
call-seq: select(*columns) => PathQuery::Query.
-
#template(name) ⇒ Object
(also: #get_template)
call-seq: template(name) => PathQuery::Template.
-
#template_names ⇒ Object
Get all the names of the available templates, in alphabetical order.
-
#templates ⇒ Object
call-seq: templates() => Hash=> Template.
Constructor Details
#initialize(root, token = nil, mock_model = nil) ⇒ Service
Construct a new service.
service = Service.new("www.flymine.org/query", "TOKEN")
Arguments:
root
-
The URL to the root of the webservice. For example, for FlyMine this is: “www.flymine.org/query/service” For simplicity’s sake, it is possible to omit the scheme and the “/service” section, and just pass the bare minimum: “www.flymine.org/query”
token
-
An optional API access token to authenticate your webservice access with. If you supply a token, you will have access to your private lists and templates.
148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 |
# File 'lib/intermine/service.rb', line 148 def initialize(root, token=nil, mock_model=nil) u = URI.parse(root) unless u.scheme root = "http://" + root end unless root.end_with?("/service") # All webservices must root << "/service" end @root = root @token = token @model = mock_model @_templates = nil @broken_templates = [] @list_manager = InterMine::Lists::ListManager.new(self) root_uri = URI.parse(@root) @root_path = root_uri.path @http = Net::HTTP.new(root_uri.host, root_uri.port) v_path = @root + VERSION_PATH begin @version = fetch(v_path).to_i rescue Exception => e raise ServiceError, "Error fetching version at #{ v_path }: #{e.}" end end |
Instance Attribute Details
#broken_templates ⇒ Object (readonly)
A collection of the names of any templates that this service was not able to parse, and you will thus not be able to access.
126 127 128 |
# File 'lib/intermine/service.rb', line 126 def broken_templates @broken_templates end |
#root ⇒ Object (readonly)
The root of the query. If you supplied an abbreviated version, this attribute will hold the expanded URL.
119 120 121 |
# File 'lib/intermine/service.rb', line 119 def root @root end |
#token ⇒ Object (readonly)
The token you supplied to the constructor.
122 123 124 |
# File 'lib/intermine/service.rb', line 122 def token @token end |
#version ⇒ Object (readonly)
The webservice version. An integer that supplies information about what features are supported.
115 116 117 |
# File 'lib/intermine/service.rb', line 115 def version @version end |
Instance Method Details
#get_list_data ⇒ Object
Get the data used for constructing the lists. Called internally.
254 255 256 |
# File 'lib/intermine/service.rb', line 254 def get_list_data return fetch(@root + LISTS_PATH) end |
#model ⇒ Object Also known as: get_model
call-seq:
model() => Model
Retrieve the model from the service. This contains all the metadata about the data-model which defines what is queriable.
187 188 189 190 191 192 193 |
# File 'lib/intermine/service.rb', line 187 def model if @model.nil? data = fetch(@root + MODEL_PATH) @model = InterMine::Metadata::Model.new(data, self) end @model end |
#params ⇒ Object
Get the basic parameters used by all requests. This includes the authorization token.
260 261 262 |
# File 'lib/intermine/service.rb', line 260 def params return @token.nil? ? {} : {"token" => @token} end |
#query(rootClass = nil) ⇒ Object Also known as: new_query
201 202 203 |
# File 'lib/intermine/service.rb', line 201 def query(rootClass=nil) return InterMine::PathQuery::Query.new(self.model, rootClass, self) end |
#release ⇒ Object
Return the release string
177 178 179 |
# File 'lib/intermine/service.rb', line 177 def release return @release ||= fetch(@root + RELEASE_PATH) end |
#select(*columns) ⇒ Object
209 210 211 |
# File 'lib/intermine/service.rb', line 209 def select(*columns) return InterMine::PathQuery::Query.new(self.model, nil, self).select(*columns) end |
#template(name) ⇒ Object Also known as: get_template
219 220 221 |
# File 'lib/intermine/service.rb', line 219 def template(name) return templates[name] end |
#template_names ⇒ Object
Get all the names of the available templates, in alphabetical order.
249 250 251 |
# File 'lib/intermine/service.rb', line 249 def template_names return templates.keys.sort end |
#templates ⇒ Object
call-seq:
templates() => Hash{String => Template}
Returns all the templates available to query against in the service
231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 |
# File 'lib/intermine/service.rb', line 231 def templates parsed = {} parser = InterMine::PathQuery::Template.parser(model) template_xml = fetch(@root + TEMPLATES_PATH) doc = REXML::Document.new(template_xml) doc.elements.each("template-queries/template") do |t| begin temp = parser.parse(t) parsed[temp.name] = temp rescue @broken_templates.push(t.attribute("name").value) end end return parsed end |