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_status;
    }

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

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

        for my $file ($job->list_outputs) {
            $file->download( $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 three required parameters: username (user), passphrase (pass), and application ID (app_id). These can either be passed in on the constructor or read in from a configuration file, as demonstrated above. The configuration file should contain key=value pairs, one pair per line, as in:

    user=foo
    pass=bar
    app_id=foo_bar_baz

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.

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.

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.

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.

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/>.