Class: InterMine::Lists::List

Inherits:
Object
  • Object
show all
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

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)



84
85
86
87
88
89
 
# File 'lib/intermine/lists.rb', line 84

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



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

def dateCreated
  @dateCreated
end

#description ⇒ Object (readonly)

An informative description.



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

def description
  @description
end

#name ⇒ Object

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



50
51
52
 
# File 'lib/intermine/lists.rb', line 50

def name
  @name
end

#size ⇒ Object (readonly)

The number of elements in the list



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

def size
  @size
end

#tags ⇒ Object (readonly)

The categories associated with this list



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

def tags
  @tags
end

#title ⇒ Object (readonly)

The title of the list. This is fixed.



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

def title
  @title
end

#type ⇒ Object (readonly)

The kind of object this list holds



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

def type
  @type
end

#unmatched_identifiers ⇒ Object (readonly)

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



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

def unmatched_identifiers
  @unmatched_identifiers
end

Instance Method Details

#<<(other) ⇒ Object

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



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

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



126
127
128
129
130
131
132
133
134
 
# File 'lib/intermine/lists.rb', line 126

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)



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

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

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



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

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



161
162
163
164
 
# File 'lib/intermine/lists.rb', line 161

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

#empty? ⇒ Boolean

True if the list has no elements.

Returns:

  • (Boolean) 


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

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



141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/intermine/lists.rb', line 141

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



112
113
114
115
116
117
118
 
# File 'lib/intermine/lists.rb', line 112

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.



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

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) 


102
103
104
 
# File 'lib/intermine/lists.rb', line 102

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



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

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

#map ⇒ Object

Return a list composed of the results of the elements of this list process by the given block

symbols = list.map {|gene| gene.symbol}



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

def map 
    ret = []
    query.each_result {|r|
        ret.push(yield r)
    }
    return ret
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



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

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.



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

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

#to_s ⇒ Object

Returns a simple, readable representation of the list

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



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

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