The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
NAME
    Webservice::InterMine - modules for interacting with InterMine
    datawarehouse webservices

SYNOPSIS
        use Webservice::InterMine;

        my $service  = get_service($url, $user, $pass);
        my $template = $service->template($name);
        my $results  = $template->results_with(valueA => 'x', valueB => 'y');

    OR:

        use Webservice::InterMine 'flymine', 'SOMETOKEN';

        my $results = new_query(class => 'Gene')
                        ->select('symbol', 'primaryIdentifier', 'pathways.*')
                        ->where(symbol => [qw/H bib eve zen/])
                        ->all();

    OR:

        use Webservice::InterMine 'flymine', 'SOMETOKEN', ':no-import';

        my $results = Webservice::InterMine->new_query(class => 'Gene')
                        ->select('symbol', 'primaryIdentifier', 'pathways.*')
                        ->where(symbol => [qw/H bib eve zen/])
                        ->all();

    OR:

        use WebService::InterMine 'flymine';

        my $query = load_query(source_file => "my_query.xml");

        while (my $result = <$query>) {
            process($result);
        }

DESCRIPTION
    This distribution is the client interface to any implementation of the
    InterMine Datawarehousing WebService (www.intermine.org). Primarily used
    for biological genomic databases, the webservice allows the user to
    easily write and execute structured queries.

    This module allows you to interact with one or more webservices by
    providing a url to an InterMine implementation.

INSTALLATION AND DEPENDENCIES
    This package can be installed using the following commands
    (Module::Build >= 0.36 is required):

      perl Build.PL
      ./Build test
      sudo ./Build install

    If any runtime dependencies are missing, you can use the following
    command to install them:

      sudo ./Build installdeps

  IMPORT STATEMENTS
    You must import the module with "use" to utilise its functionality.
    Additional parameters can be supplied at import to specify a default
    service.

    Simply import the module:

        use Webservice::InterMine; 

    Import the module, and specify the default service as FlyMine (the url
    will be looked up at the central mine registry
    http://www.intermine.org/registry.

        use Webservice::InterMine 'flymine';

    The same, only with the full url, eliminating the need for an extra
    lookup:

        use Webservice::InterMine 'www.flymine.org/query';

    The same, but with authentication supplied by an API access token:

        use Webservice::InterMine 'flymine', 'SOMETOKEN';

    The same, but with authentication supplied username and password
    credentials: (deprecated)

        use Webservice::InterMine 'flymine', 'username', 'password';

    The same, with explicit, named parameters:

        use Webservice::InterMine root => 'flymine', user => 'username', pass => 'password';
  
    Calling `use Webservice::InterMine' without any parameters simply means
    you need to either specify the webservice url on every call, or call the
    methods on a service directly.

    If you pass parameters to import, a default service will be set meaning
    method calls will not require the webservice url. Unless you are
    intending to access multiple services, this form is recommended.

    If you do not wish to import the standard functions into your namespace,
    instead choosing to call them as class methods, but still wish to set a
    default service, you can use the following syntax:

        use Webservice::InterMine "flymine", "TOKEN", ':no-import';

  Using Queries
    The main reason to access the InterMine webservices is to query for
    data. The most flexible way to do this is by using Queries:

        my $query = resultset("Gene")->select("*", "proteins.*")->where(symbol => [qw/h r eve zen bib/]);

        while (my $gene = <$query>) {
            print $gene->symbol, map {$_->name} $gene->proteins, "\n";
        }

    As you can see, queries can be concisely defined, and their results
    easily accessed. You can process a query's results all at once, or using
    iteration, as in the example above. Iteration is less memory hungry, as
    only the current row of data needs to be held in memory at once, which
    can be important when dealing with large data sets.

  Using Templates
    Templates are predefined queries that make running queries easier, as
    you don't have to define the logic yourself. Every mine comes with many
    predefined searches, and you just have to enter a few parameters:

        my $results = $service->template("Gene_Proteins")->results_with(valueA => "eve");

    These templates are simple to use, and they have all the power of full
    queries as well. You can process results just as powerfully with them.

  Using Lists
    Lists are saved result sets in a webservice you can access, create,
    modify and delete (provided you are logged in):

        my $service = Webservice::InterMine->get_service("flymine", "MYTOKEN");
        my $list = $service->list("MyAwesomeList");
        my $new_list = $service->new_list(content => "some_file.text", type => "Gene");
        my $intersection = $list & $new_list;
        $intersection->rename("GenesInCommon");
        $new_list->delete; # Not actually necessary - it had no name so would have been automatically deleted anyway.

    Lists enable you to collect and manage results and lists of items of
    interest to you. You can use them in queries, and display their
    contents, as well as perforing set-logic operations on them. When you
    are done, you can view the lists in the webservice, where you can use
    the analysis widgets to assess the data you have processed.

IMPORTS
    The following functions are imported into the callers namespace. This
    can be prevented by "require"-ing the module instead.

    * get_service
    * new_query
    * resultset
    * get_template
    * get_list
    * new_list
    * load_query

METHODS
  new_query( [from => \@service_args], [%query_args] )
    returns a new query object for you to fill in with constraints before
    being run to get its results.

    Parameters:

    * from => [url, user, pass]
        An array ref of arguments to pass to get_service. This information
        can be used to specify a different service than the one named on
        import, or to specify one when none was named on import.

    * %query_args
        Key value pairs of arguments to pass to the query constructor in
        Webservice::InterMine::Service. This methid serves as sugar for the
        factory method in that class.

    Please see Webservice::InterMine::Query, Webservice::InterMine::Service.

  new_list( %list_args, [from => \@service_args] )
    Creates a new list with the content specified by the list arguments. The
    `content' key-word parameter will always be required. For a full
    specification of creating lists, see: Webservice::InterMine::Service.

    Parameters:

    * from => [url, user, pass]
        An array ref of arguments to pass to get_service. This information
        can be used to specify a different service than the one named on
        import, or to specify one when none was named on import.

    * %list_args
        Key value pairs of arguments to pass to the list constructor in
        Webservice::InterMine::Service. This methid serves as sugar for the
        factory method in that class.

  get_list( $list_name, [from => \@service_args] )
    Get the list of the given name from the default service, or the given
    service if details are supplied.

  load_query(source_file|source_string => $source, %opts, [from => [\@service_args]])
    Returns a query object based on xml you have previously saved, either as
    a string or as a file. For a file pass:

      load_query(source_file => $file);

    For a string:

      load_query(source_string => $string);

    If you want a specific service, call it thus:

      load_query(from => [$name, $user, $pass], source_string => $string);

    OR:

      load_query(from => [$name, $user, $pass], source_string => $string);

    Please see Webservice::InterMine::Query::Saved

  template( $name, [from => \@service_args], [%opts] )
    returns the named template (if it exists - if not it returns undef). If
    you pass a url, it returns the named template from the specified
    webservice.

    Please see Webservice::InterMine::Query::Template

  get_template
    Alias for `template'

  saved_query( $name, [from => \@service_args], %options ) NOT IMPLEMENTED YET
    returns the named saved_query (if it exists - if not it returns undef).
    If you pass a url, it returns the named query from the specified
    webservice.

    This method requires you to have provided a username and password to the
    webservice for authentication.

    Please see Webservice::InterMine::Query::Saved

  get_service( $root, ($token | $user, $pass) )
    returns a webservice object, which is used to construct queries and
    fetch templates and saved queries. If a url is passed, the webservice
    for that url is returned, otherwise the service for the url given to
    `use' is returned.

    Get the default service defined at import:

      use Webservice::InterMine qw(http://www.intermine.org/intermine-demo SOMETOKEN);

      my $service =  InterMine::Webservice->get_service;

    OR get a specific service, authenticated using an API access token:

      my $service = InterMine::Webservice->get_service($url, $token);

    Fetch that same authenticated service later:

      my $service = InterMine::Webservice->get_service($url);

    OR make the same call using a hash reference and named parameters:

      my $service = InterMine::Webservice->get_service({ 
        root => $url, token => $token
      });

    Parameters:

    * $root - The base url for the service.
    * $token - An API access key
    * $username, $password - A user's login credentials

    InterMine webservices support two authentication mechanisms to provide
    access to private data. The recommended method is to use API access
    keys, which have the advantage of eliminating the need to transmit your
    login details. If compromised, an access key can be easily changed or
    disabled without needing to change either the associated username or
    password. However this facility is new, so for backwards compatibility,
    the older mechanism for passing along username and password credentials
    has been retained.

    If three arguments are supplied, they will be interpreted as `($root,
    $user, $pass)', but if two are supplied, they will be intepreted as
    `($root, $token)'.

    These arguments may also be passed in a keyword/hash style, either as a
    list or a hash reference, in which case the full list will be passed to
    the Webservice::InterMine::Service::new constructor.

    If a service for a url has been created previously, that one is
    returned, even if different login details are provided.

    Please see: Webservice::InterMine::Service

  clean_temp_lists()
    Deletes all automatically created anonymous lists. Any renamed lists
    will be spared the clean-up. This method is called on system exit,
    unless the variable $Webservice::InterMine::CLEAN_UP is set to a false
    value.

  get_{minename}(user, pass)
    An unknown method preceded with 'get_' will be interpreted as a mine
    name, and an attempt will be made to return a service with that name.

SEE ALSO
    * Webservice::InterMine::Cookbook for a guide on how to use these
    modules.
    * Webservice::InterMine::Query
    * Webservice::InterMine::Service
    * Webservice::InterMine::List
    * Webservice::InterMine::Query::Template
    * Webservice::InterMine::Query::Saved
    * Webservice::InterMine::Bio Biologically specific roles.

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

    You can also look for information at:

    * InterMine
        http://www.intermine.org

    * Documentation
        http://www.intermine.org/perlapi

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.