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.

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.

author

Alex Kalderimis dev@intermine.org

homepage

www.intermine.org

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

broken_templates[R]

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[R]

The root of the query. If you supplied an abbreviated version, this attribute will hold the expanded URL.

token[R]

The token you supplied to the constructor.

version[R]

The webservice version. An integer that supplies information about what features are supported.

Public Class Methods

new(root, token=nil, mock_model=nil) click to toggle source

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_list_data() click to toggle source

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
Alias for: model
Alias for: template
model() → Model click to toggle source

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
Also aliased as: get_model
Alias for: query
params() click to toggle source

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
query(rootClass=nil) → PathQuery::Query click to toggle source

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
Also aliased as: new_query
release() click to toggle source

Return the release string

    # File lib/intermine/service.rb
181 def release
182     return @release ||= fetch(@root + RELEASE_PATH)
183 end
select(*columns) → PathQuery::Query click to toggle source

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
template(name) → PathQuery::Template click to toggle source

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
Also aliased as: get_template
template_names() click to toggle source

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
templates() => Hash{String → Template} click to toggle source

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

fetch(url) click to toggle source

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