NAME
    Bio::CIPRES - interface to the CIPRES REST API

SYNOPSIS
        use Bio::CIPRES;

        my $ua = Bio::CIPRES->new(
            user    => $username,
            pass    => $password,
            app_id  => $id,
            timeout => 60,
        );

        my $job = $ua->submit_job( %job_params );

        while (! $job->is_finished) {
            sleep $job->poll_interval;
            $job->refresh;
        }

        print STDOUT $job->stdout;
        print STDERR $job->stderr;

        if ($job->exit_code == 0) {

            for my $file ($job->outputs) {
                $file->download( out => $file->name );
            }

        }

DESCRIPTION
    "Bio::CIPRES" is an interface to the CIPRES REST API for running
    phylogenetic analyses. Currently it provides general classes and methods
    for job submission and handling - determination of the correct
    parameters to submit is up to the user (check "SEE ALSO" for links to
    tool documentation).

METHODS
    new
            my $ua = Bio::CIPRES->new(
                user    => $username,
                pass    => $password,
                app_id  => $id,
                timeout => 60,
            );

            # or read configuration from file

            my $ua = Bio::CIPRES->new(
                conf => "$ENV{HOME}/.cipres"
            );

        Create a new "Bio::CIPRES" object. There are a number of required
        and optional parameters which can be specified in the constructor or
        read from a configuration file. The configuration file should
        contain key=value pairs, one pair per line, as in:

            user=foo
            pass=bar
            app_id=foo_bar-12345

        Required parameters (no defaults):

        *
         user - the username of your registered CIPRES REST account

        *
         pass - the password of your registered CIPRES REST account

        The passphrase must be stored in plaintext, so the usual precautions
        apply (e.g. the file should not be world-readable). If possible,
        find another way to retrieve the passphrase within your code and
        pass it in directly as a method argument.

        Optional parameters (must be defined but defaults are provided):

        *
         app_id - override the application ID assigned to Bio::CIPRES

        *
         url - override the default base REST url (don't change this unless
         you know what you're doing).

        *
         timeout - set the network timeout for HTTP requests

        UMBRELLA parameters:

        These parameters are only for use with UMBRELLA applications (you
        will need you register your own UMBRELLA application to use this
        functionality). They are not needed for non-UMBRELLA applications,
        but if "eu" is defined then UMBRELLA is assumed and "eu_email" and
        "app_name" must be defined as well.

        *
         eu - end user name

        *
         eu_email - end user email address

        *
         app_name - UMBRELLA application name as registered with CIPRES

        *
         eu_institution - end user institution (currently optional)

        *
         eu_country - end user two-letter country code (currently optional)

    submit_job
            my $job = $ua->submit_job( %params );

        Submit a new job to the CIPRES service. Params are set based on the
        tool documentation (not covered here). Returns a Bio::CIPRES::Job
        object.

        Most params are passed as simple key => value pairs of strings based
        on the CIPRES tool documentation. One important nuance, however, is
        in the handling of input files. If the contents of a input file are
        to be passed in as a scalar, they should be provided directly as the
        scalar value to the appropriate key:

            my $job = $ua->submit_job( 'input.infile_' => $in_contents );

        However, if the input file is to be uploaded by filename, it should
        be passed as an array reference:

            my $job = $ua->submit_job( 'input.infile_' => [$in_filename] );

        Failure to understand the difference will result in errors either
        during job submission or during the job run.

    list_jobs
            for my $job ( $ua->list_jobs ) {
                # do something
            }

        Returns an array of Bio::CIPRES::Job objects representing jobs in
        the user's workspace.

    get_job
            my $job = $ua->get_job( $job_handle );

        Takes a single argument (string containing the job handle/ID) and
        returns a Bio::CIPRES::Job object representing the appropriate job,
        or undef if not found.

TESTING
    The distribution can be installed and tested in the usual ways. Note
    however, that running the full test suite requires CIPRES REST
    credentials (not shipped with package for obvious reasons). If a
    credentials file is found at "$ENV{HOME}/.cipres", the full test suite
    will be run -- otherwise only rudimentary tests will be run and most
    will be skipped.

CAVEATS AND BUGS
    This is code is in alpha testing stage and the API is not guaranteed to
    be stable.

    Currently the use of UMBRELLA authentication is not implemented.

    Please report bugs to the author.

SEE ALSO
    <https://www.phylo.org/restusers/documentation.action>

AUTHOR
    Jeremy Volkening <jdv@base2bio.com>

COPYRIGHT AND LICENSE
    Copyright 2016 Jeremy Volkening

    This program is free software: you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation, either version 3 of the License, or (at your
    option) any later version.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
    Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program. If not, see <http://www.gnu.org/licenses/>.