/ 
Webservice-InterMine-1.0200
River stage one • 1 direct dependent • 1 total dependent
/ Webservice::InterMine::List

NAME

Webservice::InterMine::List - a representation of a List of objects stored on a webservice's server.

SYNOPSIS

use Webservice::InterMine;

my $service = Webservice::InterMine->get_service('www.flymine.org/query/service', $url, $password);

my @lists = $service->get_lists();
my $list = $service->list("name_of_list");
my $new_list = $service->new_list(
  type => "Gene", content => 'indentifiers.list');
my $intersection = $list ^ $new_list;

while (<$intersection>) {
  printf $intersection->table_format, @$_;
}

DESCRIPTION

An object of this type represents a list on the corresponding webservice's server. While not containing the list data itself, it provides methods for obtaining and iterating over that data, and manipulating the list by addition, which alters the current list, and the operations of union, intersection, symmetric difference, and subtraction which create new lists.

Lists can be created de novo, but for that you should see Webservice::InterMine::Service, which provides the new_list method.

For all active list operations (as opposed to just getting information about the available lists and querying against them) you will need to be authenticated to your user account.

OVERLOADED OPERATIONS

The following operations on list objects are overloaded:

  • "" (Stringification)

    Returns a human readable representation of the list, with its name, size, creation time, and description.

  • +, | (Unions)

    Returns a new list from the union of this list and the other operand. Lists can be joined to other lists, or any of the suitable content types for new queries. In the case of lists of identifiers (whether in Arrays, strings or files), the type will be assumed to be the same as that of the current list.

  • +=, |= (Appending)

    Adds elements to the current list. Items can be appended from other lists, or any of the suitable content types for new queries. In the case of lists of identifiers (whether in Arrays, strings or files), the type will be assumed to be the same as that of the current list.

  • -, -= (Subtraction, Removal)

    Creates a new list by removing elements from the current list. Lists can be subtracted from other lists, as can suitable queries or other content types, where the type will be assumed from that of the current list.

  • &, &= (Intersections)

    Creates a new list from the intersection of this list and the other operand, modifying the current list in the case of the assignment variant. As with other operations, where the type of an operands must be inferred, it will be assumed to be the same as the current list.

  • ^, ^= (Symmetric Difference)

    Creates a new list, or modifies the current one, to have the symmetric difference of the operands - ie. only elements not shared by all operands will be in the new list. As with other operations, where the type of an operands must be inferred, it will be assumed to be the same as the current list.

  • <> (Iteration over results)

    Calling iteration over a list directly will iterate over a result set comprising the members of the list, where the output columns are all the attributes of the list's type. For more fine grained control over list results and other list queries, you can call to_query to get a query of the right class with the attribute view already added on.

ATTRIBUTES

title

The permananent title of the list. This will not change over the list's lifetime.

description

The human readable description of the list. This can be altered, and may be undefined.

has_description

Returns whether or not this list has a description.

name

The name of the list. This can be changed by calling rename, which will also update the name on the server.

size

The number of members in the list. This will be updated if the list is appended to, or if elements are removed through list operations.

type

The class of object this list contains. Each list must be homogenous, and the classes are defined in the data-model for each mine. (See InterMine::Model). A class defines the attributes and references each member possesses. The type of a list cannot change, unless through list operations, and then it will only ever become less specific, and never more specific.

date

The creation date of the list. Not all lists will necessarily have creation dates.

status

The status of the list. Usable lists are "CURRENT", all other statuses mean that the user should log in to the web-app to resolve issues caused by a data-base upgrade.

get_unmatched_ids

Gets a list of identifiers that did not match objects when this list was created. This is primarily of use when debugging list creation issues. The set of unmatched ids does not persist accross sessions, and is only available immediately after a list is created.

get_tags, has_tag

Get the labels this list is tagged with. Tags are short categorisations that enable lists to be more effectively sorted and grouped. get_tags returns the list of all tags, and has_tag returns whether the list has a particular tag.

is_authorized

Returns whether the current user has the authority to make changes to this list. In the case of global lists, this value will return false. For all lists a user creates (for which you must provide authentication) it will return true.

METHODS AND OPERATIONS

delete

Delete this list. This method deletes the list permanently from the originating mine. USE WITH EXTEME CAUTION - it WILL cause loss of data. Once this method has been called, you should not use the list object in any further operations, as it will throw errors.

join_with(something_else)

Make a union of this list with something else. The other operand can be a list, a query, a string of identifiers, the name of a file containing identifiers, an array-ref of identifiers, or an array-ref of lists or queries.

intersect_with(something_else)

Make an intersection of this list with something else. The other operand can be a list, a query, a string of identifiers, the name of a file containing identifiers, an array-ref of identifiers, or an array-ref of lists or queries.

difference_with(something_else)

Make a new list of the symmetric difference between this list and something else. The other operand can be a list, a query, a string of identifiers, the name of a file containing identifiers, an array-ref of identifiers, or an array-ref of lists or queries.

remove(something_else)

Remove the other operand from this list. The other operand can be a list, a query, a string of identifiers, the name of a file containing identifiers, an array-ref of identifiers, or an array-ref of lists or queries.

subtract(something_else)

Make a new list by removing the other operand from this list. The other operand can be a list, a query, a string of identifiers, the name of a file containing identifiers, an array-ref of identifiers, or an array-ref of lists or queries.

enrichment(widget => $name, [population => $background, maxp => $val, correction => $algorithm, filter => $filter])

Receive results from an enrichment widget.

to_query

Return a Webservice::InterMine::Query representing the elements of this list. The resulting query will have this list's type as its root class, and already be contrained to only contain elements in this list. It will not have any output columns. Further contraints and views can be added.

build_query

Return a Webservice::InterMine::Query representing the elements of this list. The resulting query will have this list's type as its root class, and already be contrained to only contain elements in this list. It will have all the attribute fields of the list's type as its output columns. Further contraints and views can be added.

results_iterator

Get a results iterator for this list. It will by default iterate over results as arrayrefs, with the query set to the default values of build_query.

next_element

Get the next element (as a results row) from the list. Once the last element is returned, the list will reset and go back to the beginning on its underlying iterator.

append(something_else)

Add the elements represented by the other operand to this query. The other operand can be a list, a query, a string of identifiers, the name of a file containing identifiers, an array-ref of identifiers, or an array-ref of lists or queries.

add_tags(@tags)

Add the given tags to the list, updating this list on the server and changing the tags attribute of the object.

remove_tags(@tags)

Remove the given tags from the list, updating this list on the server and changing the tags attribute of the object.

update_tags()

Update the tags for this list to be up-to-date with those stored on the server.

to_string

Return a human readable string representation of this list. This consists of the name, the size, the type, the creation time, and the description, if it has all those things.

SEE ALSO

AUTHOR

Alex Kalderimis dev@intermine.org

BUGS

Please report any bugs or feature requests to dev@intermine.org.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Webservice::InterMine::List

You can also look for information at:

COPYRIGHT AND LICENSE

Copyright 2006 - 2011 FlyMine, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.