Class: InterMine::Lists::ListManager
- Inherits:
-
Object
- Object
- InterMine::Lists::ListManager
- 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
-
#service ⇒ Object
readonly
The service this manager belongs to.
-
#temporary_lists ⇒ Object
readonly
The temporary lists created in this session.
Instance Method Summary collapse
-
#add_tags(list, *tags) ⇒ Object
Add tags to a list.
-
#create_list(content, type = nil, tags = [], name = nil, description = nil) ⇒ Object
Create a new List with the given content.
-
#delete_lists(*lists) ⇒ Object
Deletes the given lists from the webservice.
-
#get_lists_with_tags(*tags) ⇒ Object
Gets all lists with the given tags.
-
#initialize(service) ⇒ ListManager
constructor
Construct a new ListManager.
-
#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.
-
#list(name) ⇒ Object
Get a list by name.
-
#list_names ⇒ Object
Get the names of the lists currently available in the webservice.
-
#lists ⇒ Object
Get the lists currently available in the webservice.
-
#params_to_query_string(p) ⇒ Object
only handles single value keys!.
-
#process_list_creation_response(response) ⇒ Object
Common code to all list requests for interpreting the response from the webservice.
-
#refresh_lists ⇒ Object
Update the stored record of lists.
-
#remove_tags(list, *tags) ⇒ Object
Remove tags from a list.
-
#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.
-
#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.
-
#tags_for(list) ⇒ Object
Get the current tags for a list.
-
#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.
Constructor Details
#initialize(service) ⇒ ListManager
Construct a new ListManager.
You will never need to call this constructor yourself.
492 493 494 495 496 497 498 499 500 501 502 |
# File 'lib/intermine/lists.rb', line 492 def initialize(service) @service = service @lists = {} @temporary_lists = [] @uri = URI.parse(@service.root) @http = Net::HTTP.new(@uri.host, @uri.port) if @uri.scheme == 'https' @http.use_ssl = true end do_at_exit(self) end |
Instance Attribute Details
#service ⇒ Object (readonly)
The service this manager belongs to
482 483 484 |
# File 'lib/intermine/lists.rb', line 482 def service @service end |
#temporary_lists ⇒ Object (readonly)
The temporary lists created in this session. These will be deleted at program exit.
486 487 488 |
# File 'lib/intermine/lists.rb', line 486 def temporary_lists @temporary_lists end |
Instance Method Details
#add_tags(list, *tags) ⇒ Object
Add tags to a list.
Returns the current tags
672 673 674 675 676 677 678 679 680 |
# File 'lib/intermine/lists.rb', line 672 def (list, *) uri = URI.parse(@service.root + Service::LIST_TAG_PATH) params = @service.params.merge("name" => list.name, "tags" => .join(";")) res = @http.start() do |http| Net::HTTP.post_form(uri, params) end check_response_for_error(res) return JSON.parse(res.body)["tags"] end |
#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}))
577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 |
# File 'lib/intermine/lists.rb', line 577 def create_list(content, type=nil, =[], name=nil, description=nil) name ||= get_unused_list_name description ||= DEFAULT_DESCRIPTION if content.is_a?(List) += content. response = create_list_from_query(content.list_query, , name, description) elsif content.respond_to?(:list_upload_uri) response = create_list_from_query(content, , name, description) else response = create_list_from_ids(content, type, , 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.
599 600 601 602 603 604 605 606 607 608 609 610 |
# File 'lib/intermine/lists.rb', line 599 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 = @http.start 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.("tagA", "tagB")
528 529 530 531 532 533 |
# File 'lib/intermine/lists.rb', line 528 def (*) return lists.select do |l| union = l. | union.size == l..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
632 633 634 |
# File 'lib/intermine/lists.rb', line 632 def intersection_of(lists=[], =[], name=nil, description=nil) do_commutative_list_operation(Service::LIST_INTERSECTION_PATH, "Intersection", lists, , name, description) end |
#list(name) ⇒ Object
Get a list by name. Returns nil if the list does not exist.
518 519 520 521 |
# File 'lib/intermine/lists.rb', line 518 def list(name) refresh_lists return @lists[name] end |
#list_names ⇒ Object
Get the names of the lists currently available in the webservice
512 513 514 515 |
# File 'lib/intermine/lists.rb', line 512 def list_names refresh_lists return @lists.keys.sort end |
#lists ⇒ Object
Get the lists currently available in the webservice.
506 507 508 509 |
# File 'lib/intermine/lists.rb', line 506 def lists refresh_lists return @lists.values end |
#params_to_query_string(p) ⇒ Object
only handles single value keys!
716 717 718 |
# File 'lib/intermine/lists.rb', line 716 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.
657 658 659 660 661 662 663 664 665 666 |
# File 'lib/intermine/lists.rb', line 657 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.
537 538 539 540 541 542 543 544 |
# File 'lib/intermine/lists.rb', line 537 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 |
#remove_tags(list, *tags) ⇒ Object
Remove tags from a list
Returns the current tags
686 687 688 689 690 691 692 693 694 695 696 697 698 699 |
# File 'lib/intermine/lists.rb', line 686 def (list, *) uri = URI.parse(@service.root + Service::LIST_TAG_PATH) params = @service.params.merge( "name" => list.name, "tags" => .join(";") ) req_path = uri.path + "?" + params_to_query_string(params) req = Net::HTTP::Delete.new(req_path) res = @http.start() do |http| http.request(req) end check_response_for_error(res) return JSON.parse(res.body)["tags"] 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
641 642 643 644 645 646 647 648 649 650 651 652 653 |
# File 'lib/intermine/lists.rb', line 641 def subtract(references=[], delenda=[], =[], 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" => .join(';')) res = @http.start() do |http| Net::HTTP.post_form(uri, params) end 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
616 617 618 |
# File 'lib/intermine/lists.rb', line 616 def symmetric_difference_of(lists=[], =[], name=nil, description=nil) do_commutative_list_operation(Service::LIST_DIFFERENCE_PATH, "Symmetric difference", lists, , name, description) end |
#tags_for(list) ⇒ Object
Get the current tags for a list
702 703 704 705 706 707 708 709 710 711 712 713 |
# File 'lib/intermine/lists.rb', line 702 def (list) uri = URI.parse(@service.root + Service::LIST_TAG_PATH) params = @service.params.merge( "name" => list.name ) req_path = uri.path + "?" + params_to_query_string(params) res = @http.start() do |http| http.get(req_path) end check_response_for_error(res) return JSON.parse(res.body)["tags"] 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
624 625 626 |
# File 'lib/intermine/lists.rb', line 624 def union_of(lists=[], =[], name=nil, description=nil) do_commutative_list_operation(Service::LIST_UNION_PATH, "Union", lists, , name, description) end |