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"

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.



145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/intermine/service.rb', line 145

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
    begin
        @version = fetch(@root + VERSION_PATH).to_i
    rescue => e
        raise ServiceError, "Error fetching version at #{@root + VERSION_PATH}: #{e.message}"
    end
    @model = mock_model
    @_templates = nil
    @broken_templates = []
    @list_manager = InterMine::Lists::ListManager.new(self)
end

Instance Attribute Details

#root ⇒ Object (readonly)

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



118
119
120
 
# File 'lib/intermine/service.rb', line 118

def root
  @root
end

#token ⇒ Object (readonly)

The token you supplied to the constructor.



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

def token
  @token
end

#version ⇒ Object (readonly)

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



114
115
116
 
# File 'lib/intermine/service.rb', line 114

def version
  @version
end

Instance Method Details

#get_list_data ⇒ Object

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



246
247
248
 
# File 'lib/intermine/service.rb', line 246

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.



177
178
179
180
181
182
183
 
# File 'lib/intermine/service.rb', line 177

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.



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

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



191
192
193
 
# File 'lib/intermine/service.rb', line 191

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

#release ⇒ Object

Return the release string



167
168
169
 
# File 'lib/intermine/service.rb', line 167

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.



199
200
201
 
# File 'lib/intermine/service.rb', line 199

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.



209
210
211
 
# File 'lib/intermine/service.rb', line 209

def template(name) 
    return templates[name]
end

#template_names ⇒ Object

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



241
242
243
 
# File 'lib/intermine/service.rb', line 241

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



221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
 
# File 'lib/intermine/service.rb', line 221

def templates 
    if @_templates.nil?
        @_templates = {}
        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)
                @_templates[temp.name] = temp
            rescue
                @broken_templates.push(t.attribute("name").value)
            end
        end
    end
    return @_templates
end