Class: InterMine::Lists::List

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/intermine/lists.rb

Overview

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.

:include:contact_header.rdoc

Defined Under Namespace

Classes: SymbolAcceptingHash

Constant Summary collapse

ENRICHMENT_DEFAULTS = 
{:correction => "Holm-Bonferroni", :maxp => 0.05, :format => 'json'}

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(details, manager = nil) ⇒ List

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)



91
92
93
94
95
96
 
# File 'lib/intermine/lists.rb', line 91

def initialize(details, manager=nil)
    @manager = manager
    details.each {|k,v| instance_variable_set('@' + k, v)}
    @unmatched_identifiers = []
    @tags ||= []
end

Instance Attribute Details

#dateCreated ⇒ Object (readonly)

The date that this list was originally created



67
68
69
 
# File 'lib/intermine/lists.rb', line 67

def dateCreated
  @dateCreated
end

#description ⇒ Object (readonly)

An informative description.



58
59
60
 
# File 'lib/intermine/lists.rb', line 58

def description
  @description
end

#name ⇒ Object

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



52
53
54
 
# File 'lib/intermine/lists.rb', line 52

def name
  @name
end

#size ⇒ Object (readonly)

The number of elements in the list



64
65
66
 
# File 'lib/intermine/lists.rb', line 64

def size
  @size
end

#status ⇒ Object (readonly)

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



72
73
74
 
# File 'lib/intermine/lists.rb', line 72

def status
  @status
end

#tags ⇒ Object (readonly)

The categories associated with this list



75
76
77
 
# File 'lib/intermine/lists.rb', line 75

def tags
  @tags
end

#title ⇒ Object (readonly)

The title of the list. This is fixed.



55
56
57
 
# File 'lib/intermine/lists.rb', line 55

def title
  @title
end

#type ⇒ Object (readonly)

The kind of object this list holds



61
62
63
 
# File 'lib/intermine/lists.rb', line 61

def type
  @type
end

#unmatched_identifiers ⇒ Object (readonly)

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



78
79
80
 
# File 'lib/intermine/lists.rb', line 78

def unmatched_identifiers
  @unmatched_identifiers
end

Instance Method Details

#<<(other) ⇒ Object

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



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

def <<(other)
    return add(other)
end

#[](index) ⇒ Object

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

puts list[2].length
puts list[-1].length



133
134
135
136
137
138
139
140
141
 
# File 'lib/intermine/lists.rb', line 133

def [](index)
    if index < 0
        index = @size + index
    end
    unless index < @size && index >= 0
        return nil
    end
    return query.first(index)
end

#add(*others) ⇒ Object

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)



242
243
244
245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/intermine/lists.rb', line 242

def add(*others)
    unionables, ids = classify_others(others)
    unless unionables.empty?
        if unionables.size == 1
            append_list(unionables.first)
        else
            append_lists(unionables)
        end
    end
    unless ids.empty?
        ids.each {|x| append_ids(x)}
    end
    return self
end

#add_tags(*tags) ⇒ Object

Add tags to the list

Updates the current tags by adding tags to the list.



294
295
296
 
# File 'lib/intermine/lists.rb', line 294

def add_tags(*tags)
    @tags = @manager.add_tags(self, tags)
end

#calculate_enrichment(widget, opts = {}) ⇒ Object

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.



333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
 
# File 'lib/intermine/lists.rb', line 333

def calculate_enrichment(widget, opts = {})
    s = @manager.service
    params = s.params.merge(ENRICHMENT_DEFAULTS).merge(opts).merge(:widget => widget, :list => @name)
    uri = URI.parse(s.root + Service::LIST_ENRICHMENT_PATH)
    res = Net::HTTP.post_form(uri, params)
    return case res
    when Net::HTTPSuccess
        JSON.parse(res.body)["results"].map {|row| SymbolAcceptingHash[row] }
    else
        begin
            container = JSON.parse(res.body)
            raise ServiceError, container["error"]
        rescue
            res.error!
        end
    end
end

#delete ⇒ Object

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.



229
230
231
232
233
 
# File 'lib/intermine/lists.rb', line 229

def delete
    @manager.delete_lists(self)
    @size = 0
    @name = nil
end

#each ⇒ Object

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

list.each do |gene|
  puts gene.symbol
end



168
169
170
171
 
# File 'lib/intermine/lists.rb', line 168

def each
    query.results.each {|r| yield r}
    return self
end

#empty? ⇒ Boolean

True if the list has no elements.

Returns:

  • (Boolean) 


99
100
101
 
# File 'lib/intermine/lists.rb', line 99

def empty?
    @size == 0
end

#fetch(index, default = nil) ⇒ Object

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



148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/intermine/lists.rb', line 148

def fetch(index, default=nil)
    if index < 0
        index = @size + index
    end
    unless index < @size && index >= 0
        if default
            return default
        else
            raise IndexError, "#{index} is not a suitable index for this list"
        end
    end
    return query.first(index)
end

#first ⇒ Object

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



119
120
121
122
123
124
125
 
# File 'lib/intermine/lists.rb', line 119

def first
    if @size > 0
        return self[0]
    else
        return nil
    end
end

#inspect ⇒ Object

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



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

def inspect
    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}>"
end

#is_authorized? ⇒ Boolean

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

if list.is_authorized?
  list.remove("h")
end

Returns:

  • (Boolean) 


109
110
111
 
# File 'lib/intermine/lists.rb', line 109

def is_authorized?
    return @authorized.nil? ? true : @authorized
end

#list_query ⇒ Object

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}))



178
179
180
 
# File 'lib/intermine/lists.rb', line 178

def list_query
    return @manager.service.query(@type).select(@type + '.id').where(@type => self)
end

#query ⇒ Object

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



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

def query
    return @manager.service.query(@type).where(@type => self)
end

#remove(*others) ⇒ Object

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.



271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
 
# File 'lib/intermine/lists.rb', line 271

def remove(*others)
    unionables, ids = classify_others(others)
    unless ids.empty?
        unionables += ids.map {|x| @manager.create_list(x, @type)}
    end
    unless unionables.empty?
        myname = @name
        new_list = @manager.subtract([self], unionables, @tags, nil, @description)
        self.delete
        @size = new_list.size
        @name = new_list.name
        @description = new_list.description
        @dateCreated = new_list.dateCreated
        @tags = new_list.tags
        self.name = myname
    end
    return self
end

#remove_tags(*tags) ⇒ Object

Remove one or more tags from the list

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



303
304
305
306
307
308
 
# File 'lib/intermine/lists.rb', line 303

def remove_tags(*tags)
    to_remove = tags.select {|t| @tags.include? t}
    unless to_remove.empty?
        @tags = @manager.remove_tags(self, to_remove)
    end
end

#to_s ⇒ Object

Returns a simple, readable representation of the list

puts list
=> "My new list: 5 genes"



200
201
202
 
# File 'lib/intermine/lists.rb', line 200

def to_s
    return "#{@name}: #{@size} #{@type}s"
end

#update_tags ⇒ Object

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



311
312
313
 
# File 'lib/intermine/lists.rb', line 311

def update_tags
    @tags = @manager.tags_for(self)
end