class InterMine::Service
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.
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.
- author
-
Alex Kalderimis dev@intermine.org
- homepage
- Licence
-
Copyright (C) 2002-2011 FlyMine
This code may be freely distributed and modified under the terms of the GNU Lesser General Public Licence. This should be distributed with the code. See the LICENSE file for more information or www.gnu.org/copyleft/lesser.html.
Constants
- LISTS_PATH
- LIST_APPEND_PATH
- LIST_DIFFERENCE_PATH
- LIST_ENRICHMENT_PATH
- LIST_INTERSECTION_PATH
- LIST_RENAME_PATH
- LIST_SUBTRACTION_PATH
- LIST_TAG_PATH
- LIST_UNION_PATH
- MODEL_PATH
- QUERY_APPEND_PATH
- QUERY_RESULTS_PATH
- QUERY_TO_LIST_PATH
- RELEASE_PATH
- SEQUENCE_PATH
- TEMPLATES_PATH
- TEMPLATE_APPEND_PATH
- TEMPLATE_RESULTS_PATH
- TEMPLATE_TO_LIST_PATH
- VERSION_PATH
Attributes
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.
The root of the query. If you supplied an abbreviated version, this attribute will hold the expanded URL.
The token you supplied to the constructor.
The webservice version. An integer that supplies information about what features are supported.
Public Class Methods
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.
# File lib/intermine/service.rb 149 def initialize(root, token=nil, mock_model=nil) 150 u = URI.parse(root) 151 unless u.scheme 152 root = "http://" + root 153 end 154 unless root.end_with?("/service") # All webservices must 155 root << "/service" 156 end 157 @root = root 158 @token = token 159 @model = mock_model 160 @_templates = nil 161 @broken_templates = [] 162 @list_manager = InterMine::Lists::ListManager.new(self) 163 164 root_uri = URI.parse(@root) 165 @root_path = root_uri.path 166 167 @http = Net::HTTP.new(root_uri.host, root_uri.port) 168 if root_uri.scheme == 'https' 169 @http.use_ssl = true 170 end 171 172 v_path = @root + VERSION_PATH 173 begin 174 @version = fetch(v_path).to_i 175 rescue Exception => e 176 raise ServiceError, "Error fetching version at #{ v_path }: #{e.message}" 177 end 178 end
Public Instance Methods
Get the data used for constructing the lists. Called internally.
# File lib/intermine/service.rb 258 def get_list_data 259 return fetch(@root + LISTS_PATH) 260 end
Retrieve the model from the service. This contains all the metadata about the data-model which defines what is queriable.
# File lib/intermine/service.rb 191 def model 192 if @model.nil? 193 data = fetch(@root + MODEL_PATH) 194 @model = InterMine::Metadata::Model.new(data, self) 195 end 196 @model 197 end
Get the basic parameters used by all requests. This includes the authorization token.
# File lib/intermine/service.rb 264 def params 265 return @token.nil? ? {} : {"token" => @token} 266 end
Create a new query against the data at this webservice
# File lib/intermine/service.rb 205 def query(rootClass=nil) 206 return InterMine::PathQuery::Query.new(self.model, rootClass, self) 207 end
Return the release string
# File lib/intermine/service.rb 181 def release 182 return @release ||= fetch(@root + RELEASE_PATH) 183 end
Create a new query with the given view.
# File lib/intermine/service.rb 213 def select(*columns) 214 return InterMine::PathQuery::Query.new(self.model, nil, self).select(*columns) 215 end
Get a Template by name, Returns nil if there is no such template.
# File lib/intermine/service.rb 223 def template(name) 224 return templates[name] 225 end
Get all the names of the available templates, in alphabetical order.
# File lib/intermine/service.rb 253 def template_names 254 return templates.keys.sort 255 end
Returns all the templates available to query against in the service
# File lib/intermine/service.rb 235 def templates 236 parsed = {} 237 parser = InterMine::PathQuery::Template.parser(model) 238 template_xml = fetch(@root + TEMPLATES_PATH) 239 doc = REXML::Document.new(template_xml) 240 doc.elements.each("template-queries/template") do |t| 241 begin 242 temp = parser.parse(t) 243 parsed[temp.name] = temp 244 rescue 245 @broken_templates.push(t.attribute("name").value) 246 end 247 end 248 return parsed 249 end
Private Instance Methods
Retrieves data from a url with a get request.
# File lib/intermine/service.rb 271 def fetch(url) 272 ps = params 273 qs = ps.empty? ? '' : '?' + ps.map{ |k,v| "#{k}=#{CGI::escape(v.to_s)}" }.join('&') 274 uri = URI.parse(url + qs) 275 276 req = Net::HTTP::Get.new(uri.path + qs) 277 resp = @http.request req 278 279 return case resp 280 when Net::HTTPSuccess 281 resp.body 282 else 283 raise ServiceError, resp.code, resp.body 284 end 285 end