Class: InterMine::Lists::ListManager

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

Overview

Synopsis

An internal class for managing lists throughout the lifetime of a program. The main Service object delegates list functionality to this class.

# Creation
list = service.create_list("path/to/some/file.txt", "Gene", "my-favourite-genes")
# Retrieval
other_list = service.list("my-previously-saved-list")
# Combination
intersection = service.intersection_of([list, other_list])
# Deletion
service.delete_lists(list, other_list)

Description

This class contains logic for reading and updating the lists available to a given user at a webservice. This class in particular is responsible for parsing list responses, and performing the operations that combine lists into new result sets (intersection, union, symmetric difference, subtraction).

:include:contact_header.rdoc

Constant Summary collapse

DEFAULT_LIST_NAME =

The name given by default to all lists you do not explicitly name

l = service.create_list("genes.txt", "Gene")
puts l.name
=> "my_list_1"

"my_list"
DEFAULT_DESCRIPTION =

The description given by default to all new lists for which you do not provide a description explicitly. The purpose of this is to help you identify automatically created lists in you profile.

"Created with InterMine Ruby Webservice Client"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(service) ⇒ ListManager

Construct a new ListManager.

You will never need to call this constructor yourself.



414
415
416
417
418
419
 
# File 'lib/intermine/lists.rb', line 414

def initialize(service)
    @service = service
    @lists = {}
    @temporary_lists = []
    do_at_exit(self)
end

Instance Attribute Details

#service ⇒ Object (readonly)

The service this manager belongs to



404
405
406
 
# File 'lib/intermine/lists.rb', line 404

def service
  @service
end

#temporary_lists ⇒ Object (readonly)

The temporary lists created in this session. These will be deleted at program exit.



408
409
410
 
# File 'lib/intermine/lists.rb', line 408

def temporary_lists
  @temporary_lists
end

Instance Method Details

#create_list(content, type = nil, tags = [], name = nil, description = nil) ⇒ Object

Create a new List with the given content.

Creates a new List and stores it on the appropriate webservice:

Arguments:

content

Can be a string with delimited identifiers, an Array of identifiers, a File object containing identifiers, or a name of an unopened readable file containing identifiers. It can also be another List (in which case the list is cloned) or a query that describes a result set.

type

Required when identifiers are being given (but not when the content is a PathQuery::Query or a List. This should be the kind of object to look for (such as “Gene”).

tags

An Array of tags to apply to the new list. If a list is supplied as the content, these tags will be added to the existing tags.

name

The name of the new list. One will be generated if none is provided. Lists created with generated names are considered temporary and will be deleted upon program exit.

description

An informative description of the list

# With Array of Ids
list = service.create_list(%{eve bib zen}) 

# From a file
list = service.create_list("path/to/some/file.txt", "Gene", [], "my-stored-genes")

# With a query
list = service.create_list(service.query("Gene").select(:id).where(:length => {"<" => 500}))



494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
 
# File 'lib/intermine/lists.rb', line 494

def create_list(content, type=nil, tags=[], name=nil, description=nil)
    name ||= get_unused_list_name
    description ||= DEFAULT_DESCRIPTION

    if content.is_a?(List) 
        tags += content.tags
        response = create_list_from_query(content.list_query, tags, name, description)
    elsif content.respond_to?(:list_upload_uri)
        response = create_list_from_query(content, tags, name, description)
    else 
        response = create_list_from_ids(content, type, tags, name, description)
    end

    return process_list_creation_response(response)
end

#delete_lists(*lists) ⇒ Object

Deletes the given lists from the webservice. The lists can be supplied as List objects, or as their names as Strings.

Raises errors if problems occur with the deletion of these lists, including if the lists do not exist.



516
517
518
519
520
521
522
523
524
525
526
527
 
# File 'lib/intermine/lists.rb', line 516

def delete_lists(*lists)
    lists.map {|x| x.is_a?(List) ? x.name : x.to_s}.uniq.each do |name|
        uri = URI.parse(@service.root + Service::LISTS_PATH)
        params = {"name" => name}
        req = Net::HTTP::Delete.new(uri.path + "?" + params_to_query_string(params))
        res = Net::HTTP.start(uri.host, uri.port) do |http|
            http.request(req)
        end
        check_response_for_error(res)
    end
    refresh_lists
end

#get_lists_with_tags(*tags) ⇒ Object

Gets all lists with the given tags. If more than one tag is supplied, then a list must have all given tags to be returned.

tagged = service.get_lists_with_tags("tagA", "tagB")



445
446
447
448
449
450
 
# File 'lib/intermine/lists.rb', line 445

def get_lists_with_tags(*tags)
    return lists.select do |l|
        union = l.tags | tags
        union.size == l.tags.size
    end
end

#intersection_of(lists = [], tags = [], name = nil, description = nil) ⇒ Object

Create a new list in the webservice from the intersection of two or more lists, and return a List object that represents it.

See ListManager#create_list for an explanation of tags, name and description



549
550
551
 
# File 'lib/intermine/lists.rb', line 549

def intersection_of(lists=[], tags=[], name=nil, description=nil)
    do_commutative_list_operation(Service::LIST_INTERSECTION_PATH, "Intersection", lists, tags, name, description)
end

#list(name) ⇒ Object

Get a list by name. Returns nil if the list does not exist.



435
436
437
438
 
# File 'lib/intermine/lists.rb', line 435

def list(name)
    refresh_lists
    return @lists[name]
end

#list_names ⇒ Object

Get the names of the lists currently available in the webservice



429
430
431
432
 
# File 'lib/intermine/lists.rb', line 429

def list_names
    refresh_lists
    return @lists.keys.sort
end

#lists ⇒ Object

Get the lists currently available in the webservice.



423
424
425
426
 
# File 'lib/intermine/lists.rb', line 423

def lists
    refresh_lists
    return @lists.values
end

#params_to_query_string(p) ⇒ Object

only handles single value keys!



584
585
586
 
# File 'lib/intermine/lists.rb', line 584

def params_to_query_string(p)
    return @service.params.merge(p).map { |k,v| "#{k}=#{CGI::escape(v.to_s)}" }.join('&')
end

#process_list_creation_response(response) ⇒ Object

Common code to all list requests for interpreting the response from the webservice.



572
573
574
575
576
577
578
579
580
581
 
# File 'lib/intermine/lists.rb', line 572

def process_list_creation_response(response)
    check_response_for_error(response)
    new_list = JSON.parse(response.body)
    new_name = new_list["listName"]
    failed_matches = new_list["unmatchedIdentifiers"] || []
    refresh_lists
    ret = list(new_name)
    ret.unmatched_identifiers.replace(failed_matches)
    return ret
end

#refresh_lists ⇒ Object

Update the stored record of lists. This method is called before all list retrieval methods.



454
455
456
457
458
459
460
461
 
# File 'lib/intermine/lists.rb', line 454

def refresh_lists
    lists = JSON.parse(@service.get_list_data)
    @lists = {}
    lists["lists"].each {|hash| 
        l = List.new(hash, self)
        @lists[l.name] = l
    }
end

#subtract(references = [], delenda = [], tags = [], name = nil, description = nil) ⇒ Object

Create a new list in the webservice by subtracting all the elements in the ‘delenda’ lists from all the elements in the ‘reference’ lists, and return a List object that represents it.

See ListManager#create_list for an explanation of tags, name and description



558
559
560
561
562
563
564
565
566
567
568
 
# File 'lib/intermine/lists.rb', line 558

def subtract(references=[], delenda=[], tags=[], name=nil, description=nil)
    ref_names = make_list_names(references)
    del_names = make_list_names(delenda)
    name ||= get_unused_list_name
    description ||= "Subtraction of #{del_names[0 .. -2].join(", ")} and #{del_names.last} from #{ref_names[0 .. -2].join(", ")} and #{ref_names.last}"
    uri = URI.parse(@service.root + Service::LIST_SUBTRACTION_PATH)
    params = @service.params.merge("name" => name, "description" => description, "references" => ref_names.join(';'),
                                   "subtract" => del_names.join(';'), "tags" => tags.join(';'))
    res = Net::HTTP.post_form(uri, params)
    return process_list_creation_response(res)
end

#symmetric_difference_of(lists = [], tags = [], name = nil, description = nil) ⇒ Object

Create a new list in the webservice from the symmetric difference of two or more lists, and return a List object that represents it.

See ListManager#create_list for an explanation of tags, name and description



533
534
535
 
# File 'lib/intermine/lists.rb', line 533

def symmetric_difference_of(lists=[], tags=[], name=nil, description=nil)
    do_commutative_list_operation(Service::LIST_DIFFERENCE_PATH, "Symmetric difference", lists, tags, name, description)
end

#union_of(lists = [], tags = [], name = nil, description = nil) ⇒ Object

Create a new list in the webservice from the union of two or more lists, and return a List object that represents it.

See ListManager#create_list for an explanation of tags, name and description



541
542
543
 
# File 'lib/intermine/lists.rb', line 541

def union_of(lists=[], tags=[], name=nil, description=nil)
    do_commutative_list_operation(Service::LIST_UNION_PATH, "Union", lists, tags, name, description)
end