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"
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.



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.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.



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

call-seq:

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

Create a new query against the data at this webservice



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

call-seq:

select(*columns) => PathQuery::Query

Create a new query with the given view.



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

call-seq:

template(name) => PathQuery::Template

Get a Template by name, Returns nil if there is no such 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