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.



419
420
421
422
423
424
 
# File 'lib/intermine/lists.rb', line 419

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



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

def service
  @service
end

#temporary_lists ⇒ Object (readonly)

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



413
414
415
 
# File 'lib/intermine/lists.rb', line 413

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



499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
 
# File 'lib/intermine/lists.rb', line 499

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.



521
522
523
524
525
526
527
528
529
530
531
532
 
# File 'lib/intermine/lists.rb', line 521

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



450
451
452
453
454
455
 
# File 'lib/intermine/lists.rb', line 450

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



554
555
556
 
# File 'lib/intermine/lists.rb', line 554

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.



440
441
442
443
 
# File 'lib/intermine/lists.rb', line 440

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

#list_names ⇒ Object

Get the names of the lists currently available in the webservice



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

def list_names
    refresh_lists
    return @lists.keys.sort
end

#lists ⇒ Object

Get the lists currently available in the webservice.



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

def lists
    refresh_lists
    return @lists.values
end

#params_to_query_string(p) ⇒ Object

only handles single value keys!



589
590
591
 
# File 'lib/intermine/lists.rb', line 589

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.



577
578
579
580
581
582
583
584
585
586
 
# File 'lib/intermine/lists.rb', line 577

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.



459
460
461
462
463
464
465
466
 
# File 'lib/intermine/lists.rb', line 459

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



563
564
565
566
567
568
569
570
571
572
573
 
# File 'lib/intermine/lists.rb', line 563

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



538
539
540
 
# File 'lib/intermine/lists.rb', line 538

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



546
547
548
 
# File 'lib/intermine/lists.rb', line 546

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