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
97
98
99
100
101
# 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 ||= []
    @uri = URI.parse(@manager.service.root)
    @http = Net::HTTP.new(@uri.host, @uri.port)
    if @uri.scheme == 'https'
        @http.use_ssl = true
    end
end

Instance Attribute Details

#dateCreatedObject (readonly)

The date that this list was originally created


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

def dateCreated
  @dateCreated
end

#descriptionObject (readonly)

An informative description.


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

def description
  @description
end

#nameObject

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

#sizeObject (readonly)

The number of elements in the list


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

def size
  @size
end

#statusObject (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

#tagsObject (readonly)

The categories associated with this list


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

def tags
  @tags
end

#titleObject (readonly)

The title of the list. This is fixed.


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

def title
  @title
end

#typeObject (readonly)

The kind of object this list holds


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

def type
  @type
end

#unmatched_identifiersObject (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


265
266
267
# File 'lib/intermine/lists.rb', line 265

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

138
139
140
141
142
143
144
145
146
# File 'lib/intermine/lists.rb', line 138

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)

249
250
251
252
253
254
255
256
257
258
259
260
261
262
# File 'lib/intermine/lists.rb', line 249

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.


301
302
303
# File 'lib/intermine/lists.rb', line 301

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.


340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
# File 'lib/intermine/lists.rb', line 340

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 = @http.start() do |http|
        Net::HTTP.post_form(uri, params)
    end
    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

#deleteObject

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.


236
237
238
239
240
# File 'lib/intermine/lists.rb', line 236

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

#eachObject

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

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

173
174
175
176
# File 'lib/intermine/lists.rb', line 173

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

#empty?Boolean

True if the list has no elements.

Returns:

  • (Boolean)

104
105
106
# File 'lib/intermine/lists.rb', line 104

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

153
154
155
156
157
158
159
160
161
162
163
164
165
# File 'lib/intermine/lists.rb', line 153

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

#firstObject

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

124
125
126
127
128
129
130
# File 'lib/intermine/lists.rb', line 124

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

#inspectObject

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


210
211
212
# File 'lib/intermine/lists.rb', line 210

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)

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

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

#list_queryObject

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

183
184
185
# File 'lib/intermine/lists.rb', line 183

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

#queryObject

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

196
197
198
# File 'lib/intermine/lists.rb', line 196

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.


278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
# File 'lib/intermine/lists.rb', line 278

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.


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

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_sObject

Returns a simple, readable representation of the list

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

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

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

#update_tagsObject

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


318
319
320
# File 'lib/intermine/lists.rb', line 318

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