class InterMine::Lists::List

Synopsis

list = service.create_list(%{h eve H bib zen}, "Gene")
list.name = "My new list of genes" # Updates name on server
puts list.size                     # 5
list.each do |gene|                # Inspect the contents
  puts gene.name
end

list << "Hox"                      # Append an element
puts list.size

Description

A representation of a saved list in the account of an individual user of an InterMine service. Lists represent homogenous collections of objects, which are themselves linked to records in the data-warehouse. A list behaves much as a normal Array would: it has a size, and can be processed with each and map, and allows for positional access with list. In addition, as this list is backed by its representation in the webapp, it has a name, and description, as well as a type. Any changes to the list, either in its contents or by renaming, are reflected in the stored object.

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

ENRICHMENT_DEFAULTS

Attributes

dateCreated[R]

The date that this list was originally created

description[R]

An informative description.

name[R]

The name of the list. This can be changed at any time.

size[R]

The number of elements in the list

status[R]

The upgrade status of this list Anything other than current means this list needs to be manually curated.

tags[R]

The categories associated with this list

title[R]

The title of the list. This is fixed.

type[R]

The kind of object this list holds

unmatched_identifiers[R]

Any ids used to construct this list that did not match any objects in the database

Public Class Methods

new(details, manager=nil) click to toggle source

Construct a new list with details from the webservice.

This method is called internally. You will not need to construct new list objects directly.

Arguments:

details

The information about this list received from the webservice.

manager

The object responsible for keeping track of all the known lists

list = List.new({"name" => "Foo"}, manager)
    # File lib/intermine/lists.rb
 91 def initialize(details, manager=nil)
 92     @manager = manager
 93     details.each {|k,v| instance_variable_set('@' + k, v)}
 94     @unmatched_identifiers = []
 95     @tags ||= []
 96     @uri = URI.parse(@manager.service.root)
 97     @http = Net::HTTP.new(@uri.host, @uri.port)
 98     if @uri.scheme == 'https'
 99         @http.use_ssl = true
100     end
101 end

Public Instance Methods

<<(other) click to toggle source

Add the other item to the list, exactly as in List#add

    # File lib/intermine/lists.rb
265 def <<(other)
266     return add(other)
267 end
[](index) click to toggle source

Retrieve an element at a given position. Negative indices count from the end of the list.

puts list[2].length
puts list[-1].length
    # File lib/intermine/lists.rb
138 def [](index)
139     if index < 0
140         index = @size + index
141     end
142     unless index < @size && index >= 0
143         return nil
144     end
145     return query.first(index)
146 end
add(*others) click to toggle source

Add other items to this list. The other items can be identifiers in the same form as were used to create this list orginally (strings, or arrays or files). Or other lists or queries can be used to add items to the list. Any combination of these elements is possible.

list.add("Roughened", other_list, a_query)
    # File lib/intermine/lists.rb
249 def add(*others)
250     unionables, ids = classify_others(others)
251     unless unionables.empty?
252         if unionables.size == 1
253             append_list(unionables.first)
254         else
255             append_lists(unionables)
256         end
257     end
258     unless ids.empty?
259         ids.each {|x| append_ids(x)}
260     end
261     return self
262 end
add_tags(*tags) click to toggle source

Add tags to the list

Updates the current tags by adding tags to the list.

    # File lib/intermine/lists.rb
301 def add_tags(*tags)
302     @tags = @manager.add_tags(self, tags)
303 end
calculate_enrichment(widget, opts = {}) click to toggle source

Retrieve the results of an enrichment calculation

Get the results of an enrichment calculate_enrichment with the default parameter values:

calculate_enrichment(widget)

Pass optional parameters to the enrichment service:

calculate_enrichment(widget, :correction => "Benjamini-Hochberg", :maxp => 0.1)

The optional parameters are: :correction, :maxp, :filter

Each result returned by the enrichment service is a hash with the following keys: “p-value”, “identifier”, “matches”, “description”. The Hash returned also allows key access with symbols.

    # File lib/intermine/lists.rb
340 def calculate_enrichment(widget, opts = {})
341     s = @manager.service
342     params = s.params.merge(ENRICHMENT_DEFAULTS).merge(opts).merge(:widget => widget, :list => @name)
343     uri = URI.parse(s.root + Service::LIST_ENRICHMENT_PATH)
344     res = @http.start() do |http|
345         Net::HTTP.post_form(uri, params)
346     end
347     return case res
348     when Net::HTTPSuccess
349         JSON.parse(res.body)["results"].map {|row| SymbolAcceptingHash[row] }
350     else
351         begin
352             container = JSON.parse(res.body)
353             raise ServiceError, container["error"]
354         rescue
355             res.error!
356         end
357     end
358 end
delete() click to toggle source

Delete this list from the webservice. After this method is called this object should not be used again, and any attempt to do so will cause errors.

    # File lib/intermine/lists.rb
236 def delete
237     @manager.delete_lists(self)
238     @size = 0
239     @name = nil
240 end
each() { |r| ... } click to toggle source

Apply the given block to each element in the list. Return the list.

list.each do |gene|
  puts gene.symbol
end
    # File lib/intermine/lists.rb
173 def each
174     query.results.each {|r| yield r}
175     return self
176 end
empty?() click to toggle source

True if the list has no elements.

    # File lib/intermine/lists.rb
104 def empty?
105     @size == 0
106 end
fetch(index, default=nil) click to toggle source

Retrieve the object at the given index, or raise an IndexError, unless a default is supplied, in which case that is returned instead.

gene = list.fetch(6)  # Blows up if the list has only 6 elements or less
    # File lib/intermine/lists.rb
153 def fetch(index, default=nil)
154     if index < 0
155         index = @size + index
156     end
157     unless index < @size && index >= 0
158         if default
159             return default
160         else
161             raise IndexError, "#{index} is not a suitable index for this list"
162         end
163     end
164     return query.first(index)
165 end
first() click to toggle source

Returns the first element in the list. The order elements are returned in depends on the fields that its class has. It is not related to the order of the identifiers given at creation.

puts list.first.symbol
    # File lib/intermine/lists.rb
124 def first
125     if @size > 0
126         return self[0]
127     else
128         return nil
129     end
130 end
inspect() click to toggle source

Returns a detailed representation of the list, useful for debugging.

    # File lib/intermine/lists.rb
210 def inspect
211     return "<#{self.class.name} @name=#{@name.inspect} @size=#{@size} @type=#{@type.inspect} @description=#{@description.inspect} @title=#{@title.inspect} @dateCreated=#{@dateCreated.inspect} @authorized=#{@authorized.inspect} @tags=#{@tags.inspect}>"
212 end
is_authorized?() click to toggle source

True if the list can be changed by the current user.

if list.is_authorized?
  list.remove("h")
end
    # File lib/intermine/lists.rb
114 def is_authorized?
115     return @authorized.nil? ? true : @authorized
116 end
list_query() click to toggle source

Used to create a new list from the contents of this one. This can be used to define a sub-list

sub_list = service.create_list(list.list_query.where(:length => {"<" => 500}))
    # File lib/intermine/lists.rb
183 def list_query
184     return @manager.service.query(@type).select(@type + '.id').where(@type => self)
185 end
name=(new_name) click to toggle source

Update the name of the list, making sure that the name is also changed in the respective service.

list.name = "My new list"

If a list is created without a name, it will be considered as a “temporary” list until it is given one. All temporary lists are deleted from the webapp when the program exits.

    # File lib/intermine/lists.rb
223 def name=(new_name)
224     return if (@name == new_name)
225     uri = URI.parse(@manager.service.root + Service::LIST_RENAME_PATH)
226     params = @manager.service.params.merge("oldname" => @name, "newname" => new_name)
227     res = @http.start() do |http|
228         Net::HTTP.post_form(uri, params)
229     end
230     @manager.process_list_creation_response(res)
231     @name = new_name
232 end
query() click to toggle source

A PathQuery::Query with all attributes selected for output, and restricted to the content of this list. This object is used to fetch elements for other methods. This can be used for composing further filters on a list, or for adding other attributes for output.

list.query.select("pathways.*").each_result do |gene|
  puts "#{gene.symbol}: #{gene.pathways.map {|p| p.identifier}.inspect}"
end
    # File lib/intermine/lists.rb
196 def query
197     return @manager.service.query(@type).where(@type => self)
198 end
remove(*others) click to toggle source

Remove items as specified by the arguments from this list. As in List#add these others can be identifiers specified by strings or arrays or files, or other lists or queries.

list.remove("eve", sub_list)

If the items were not in the list in the first place, no error will be raised, and the size of this list will simply not change.

    # File lib/intermine/lists.rb
278 def remove(*others)
279     unionables, ids = classify_others(others)
280     unless ids.empty?
281         unionables += ids.map {|x| @manager.create_list(x, @type)}
282     end
283     unless unionables.empty?
284         myname = @name
285         new_list = @manager.subtract([self], unionables, @tags, nil, @description)
286         self.delete
287         @size = new_list.size
288         @name = new_list.name
289         @description = new_list.description
290         @dateCreated = new_list.dateCreated
291         @tags = new_list.tags
292         self.name = myname
293     end
294     return self
295 end
remove_tags(*tags) click to toggle source

Remove one or more tags from the list

If the tags are not currently associated with the list, they will be ignored.

    # File lib/intermine/lists.rb
310 def remove_tags(*tags)
311     to_remove = tags.select {|t| @tags.include? t}
312     unless to_remove.empty?
313         @tags = @manager.remove_tags(self, to_remove)
314     end
315 end
to_s() click to toggle source

Returns a simple, readable representation of the list

puts list
=> "My new list: 5 genes"
    # File lib/intermine/lists.rb
205 def to_s
206     return "#{@name}: #{@size} #{@type}s"
207 end
update_tags() click to toggle source

Update this lists tags with the current tags on the server.

    # File lib/intermine/lists.rb
318 def update_tags
319     @tags = @manager.tags_for(self)
320 end

Private Instance Methods

append_ids(ids) click to toggle source

Add items defined by ids to this list

    # File lib/intermine/lists.rb
417 def append_ids(ids)
418     uri = URI.parse(@manager.service.root + Service::LIST_APPEND_PATH)
419     params = {"name" => @name}
420     if ids.is_a?(File)
421         f = ids
422     elsif ids.is_a?(Array)
423         f = StringIO.new(ids.map {|x| '"' + x.gsub(/"/, '\"') + '"'}.join(" "))
424     elsif File.readable?(ids.to_s)
425         f = File.open(ids, "r")
426     else
427         f = StringIO.new(ids.to_s)
428     end
429     req = Net::HTTP::Post.new(uri.path + "?" + @manager.params_to_query_string(params))
430     req.body_stream = f
431     req.content_type = "text/plain"
432     req.content_length = f.size
433 
434     res = @http.start() do |http|
435         http.request(req)
436     end
437     handle_response(res)
438     f.close
439 end
append_list(list) click to toggle source

Add a List to this List

    # File lib/intermine/lists.rb
400 def append_list(list)
401     q = (list.is_a?(List)) ? list.list_query : list
402     params = q.params.merge(@manager.service.params).merge("listName" => @name)
403     uri = URI.parse(q.list_append_uri)
404     res = @http.start() do |http|
405         Net::HTTP.post_form(uri, params)
406     end
407     handle_response(res)
408 end
append_lists(lists) click to toggle source

Add a collection of lists and queries to this List

    # File lib/intermine/lists.rb
411 def append_lists(lists)
412     addendum = @manager.union_of(lists)
413     append_list(addendum)
414 end
classify_others(others) click to toggle source

Used to interpret arguments to add and remove

    # File lib/intermine/lists.rb
375 def classify_others(others)
376     unionables = []
377     ids = []
378     others.each do |o|
379         case o
380         when List
381             unionables << o
382         when o.respond_to?(:list_upload_uri)
383             unionables << o
384         else 
385             ids << o
386         end
387     end
388     return [unionables, ids]
389 end
handle_response(res) click to toggle source

Used to handle the responses returned by queries used to update the list by add and remove

    # File lib/intermine/lists.rb
393 def handle_response(res)
394     new_list = @manager.process_list_creation_response(res)
395     @unmatched_identifiers += new_list.unmatched_identifiers
396     @size = new_list.size
397 end