Class: InterMine::Service

Inherits:
Object
  • Object
show all
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"
SEQUENCE_PATH = 
"/sequence"
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

Instance Method Summary collapse

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.



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
175
176
177
178
 
# File 'lib/intermine/service.rb', line 149

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)
    if root_uri.scheme == 'https'
        @http.use_ssl = true
    end

    v_path = @root + VERSION_PATH
    begin
        @version = fetch(v_path).to_i
    rescue Exception => e
        raise ServiceError, "Error fetching version at #{ v_path }: #{e.message}"
    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.



127
128
129
 
# File 'lib/intermine/service.rb', line 127

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.



120
121
122
 
# File 'lib/intermine/service.rb', line 120

def root
  @root
end

#token ⇒ Object (readonly)

The token you supplied to the constructor.



123
124
125
 
# File 'lib/intermine/service.rb', line 123

def token
  @token
end

#version ⇒ Object (readonly)

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



116
117
118
 
# File 'lib/intermine/service.rb', line 116

def version
  @version
end

Instance Method Details

#get_list_data ⇒ Object

Get the data used for constructing the lists. Called internally.



258
259
260
 
# File 'lib/intermine/service.rb', line 258

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.



191
192
193
194
195
196
197
 
# File 'lib/intermine/service.rb', line 191

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.



264
265
266
 
# File 'lib/intermine/service.rb', line 264

def params
    return @token.nil? ? {} : {"token" => @token}
end

#query(rootClass = nil) ⇒ Object Also known as: new_query

call-seq:

query(rootClass=nil) => PathQuery::Query

Create a new query against the data at this webservice



205
206
207
 
# File 'lib/intermine/service.rb', line 205

def query(rootClass=nil)
    return InterMine::PathQuery::Query.new(self.model, rootClass, self)
end

#release ⇒ Object

Return the release string



181
182
183
 
# File 'lib/intermine/service.rb', line 181

def release
    return @release ||= fetch(@root + RELEASE_PATH)
end

#select(*columns) ⇒ Object

call-seq:

select(*columns) => PathQuery::Query

Create a new query with the given view.



213
214
215
 
# File 'lib/intermine/service.rb', line 213

def select(*columns)
    return InterMine::PathQuery::Query.new(self.model, nil, self).select(*columns)
end

#template(name) ⇒ Object Also known as: get_template

call-seq:

template(name) => PathQuery::Template

Get a Template by name, Returns nil if there is no such template.



223
224
225
 
# File 'lib/intermine/service.rb', line 223

def template(name) 
    return templates[name]
end

#template_names ⇒ Object

Get all the names of the available templates, in alphabetical order.



253
254
255
 
# File 'lib/intermine/service.rb', line 253

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



235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
 
# File 'lib/intermine/service.rb', line 235

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