/ 
AlignAid-v0.0.2
River stage zero No dependents
/ AlignAid

NAME

AlignAid - easily run sequence alignments locally or on a cluster

VERSION

This document describes AlignAid version 0.0.2

SYNOPSIS

  use AlignAid;

  # create an AlignAid object
  # a single, locally run blast job is the default
  my $job = AlignAid->new( db => 'my_blast_db', dir => $dir, 
                           fasta => 'my_query.fa',
                           prog_args => 'V=20 -nonnegok' );

 # run the job on the current host
 my $return_value = $job->submit(outfile => 'my_results.out');

 # create an AlignAid cross_match object
 # specify the alignment program and the queue to override the defaults
 my $job2 = AlignAid->new( program => 'cross_match',
                           db => 'my_db.fa', dir => $dir,
                           fasta => 'my_query_seqs.fa', queue => 'LSF');

 # submit the cross_match jobs to an LSF queue (of compute nodes)
 my $return_value2 = $job2->submit(outfile => 'my_output');

 # kill the queued jobs
 my $return_value3 = $job2->kill_all;

DESCRIPTION

AlignAid is designed to make it easy to run the sequence alignment programs Blast and cross_match. AlignAid can accept a large number of query sequences. If a compute cluster queue such as LSF or PBS is available, AlignAid can automatically split the queries into multiple queue jobs. Likewise, if you want to run the alignments locally on a single host, a single change is all that is necessary -- AlignAid will take care of how to invoke the alignment programs and manage the output.

AlignAid also has rudimentary support for LSF queue job control; it is possible to kill jobs through AlignAid's interface.

DIAGNOSTICS

could not load PP -- submitting to LSF or PBS queues will not be possible

The PP module couldn't be loaded by Perl. Usually this means it isn't installed. PP is available from the Washington University Genome Sequencing Center.

new requires a database

The mandatory database parameter wasn't passed to new(). You must specify a database for the queries to be aligned to.

database [<foo>] does not exist

The database file 'foo' supplied to new() could not be located.

new requires an output dir

The mandatory output directory parameter wasn't passed to new().

directory [<foo>] does not exist

The directory 'foo' supplied to new() could not be located.

[<foo>] is, that's right, not a directory

The value 'foo' of the directory parameter is not a directory.

new requires a fasta file of queries

The mandatory fasta (query) parameter wasn't passed to new().

fasta [<foo>] does not exist

The fasta file 'foo' could not be located.

fasta [<foo>] is not a text file

The fasta file 'foo' is, well, not a text file.

The PP module is required for submitting jobs to LSF or PBS queues.

The value of the queue parameter passed to new() was 'LSF' or 'PBS', but the PP module isn't loaded (it's needed by AlignAid to talk to the queueing system).

<foo> is not a supported queue type

The value of the queue parameter passed to new() was not one of: 'single', 'LSF', or 'PBS'.

must supply outfile as argument: $job->submit(outfile => 'foo')

The mandatory outfile parameter wasn't passed to submit().

Couldn't open <foo>

The fasta file 'foo' could not be opened. This could be referring to either the value of the 'fasta' parameter passed to new() or a temporary fasta file created by AlignAid in preparation for submitting multiple jobs to a queueing system.

unrecognized alignment program

The value of the program parameter is not 'blastn', 'blastp', 'blastx', 'tblastn', 'tblastx', or 'cross_match'.

job didn't get submitted!

One of the queue jobs AlignAid tried to submit to a queue did not actually make it onto the queue. This is usually a transient error that occurs when jobs are being submitted to the queueing system faster than it can handle. This is only a warning; AlignAid will try to proceed with additional jobs.

Sorry! PBS queueing not implemented yet!

Yep, you can't actually use AlignAid with a PBS queueing system yet. I don't personally need this feature anymore, but if you really want it, feel free to send me an email.

single job killing not implemented yet

The kill_all() method only works with jobs submitted to a queueing system right now. If you are itchin' to have this power over single jobs too, begging via email would be appropriate.

<num> weren't killed and still are in the queue

<num> jobs weren't successfully killed by kill_all() and are still on the queue. You'll probably want to go kill them manually (or make another attempt with kill_all() ).

can't validate_blasts -- BPdeluxe 1.0 did not load.

BPdeluxe version 1.0 is needed to use the validate_blasts() method. The most likely cause of this error is that BPdeluxe v1.0 isn't installed on your system or it's in a directory that's not in @INC. BPdeluxe 1.0 is available from Jarret Glasscock <glasscock_cpan@mac.com>.

validate_blasts only works on blast jobs

validate_blasts() will not work on any alignment program's output other than one of the blast programs.

CONFIGURATION AND ENVIRONMENT

AlignAid requires no configuration files or environment variables.

DEPENDENCIES

Bio::SeqIO

part of BioPerl, available at bioperl.org

version

available from CPAN

PP

This is an optional dependency, needed if you want to submit jobs to a compute cluster queueing system like LSF

BPdeluxe 1.0

This is an optional dependency, needed only if you want to use the validate_blasts() method. Available from Jarret Glasscock <glasscock_cpan@mac.com>.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

Spews Blast and cross_match STDERR all over the place.

No bugs have been reported.

Please report any bugs or feature requests to dave-pause@davemessina.net.

AUTHOR

Dave Messina <dave-pause@davemessina.net>

LICENCE AND COPYRIGHT

Copyright (c) 2006, Dave Messina <dave-pause@davemessina.net>. All rights reserved.

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

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

APPENDIX

The rest of the documentation details each of the functions. Internal methods are preceded with a "_".

new

Title        : new
Usage        : AlignAid->new();
Function     : Constructor for AlignAid class.
Returns      : Object handle.
Required Args: dir       => '' - the output directory you want created
             : db        => '' - the database file
             : fasta     => '' - the file of FASTA queries
Optional Args: queue     => '' - 'single' by default, 'LSF' for an LSF queue
             : program   => '' - the alignment program to use. 'blastn',
             :                   'blastp', 'blastx', 'tblastn', 'tblastx', or
             :                   'cross_match'
             : prog_args => '' - args to pass to the alignment program
Throws       : croaks if required parameters are missing or suspect.
Comments     : none

submit

Title        : submit
Usage        : AlignAid->submit();
Function     : start the alignment job(s) running.
Returns      : 1 upon success, 0 upon failure
Required Args: outfile => '' - the file where you want the output to go
Throws       : croaks if required parameters are missing or suspect.
Comments     : none

kill_all

Title        : kill_all
Usage        : AlignAid->kill_all();
Function     : kills all running jobs
Returns      : 1 upon success, 0 upon failure
Args         : none
Throws       : croaks on error
Comments     : none

validate_blasts

Title        : validate_blasts
Usage        : AlignAid->validate_blasts();
Function     : checks ot make sure all of the blasts completed correctly
Returns      : 1 upon success (no failed blasts), 0 upon failure
Args         : none
Throws       : croaks if you try to run it on a non-blast job
             : or if file can't be opened
Comments     : this method is optional and requires BPdeluxe 1.0

consolidate_output

Title        : consolidate_output
Usage        : AlignAid->consolidate_output();
Function     : checks to make sure all of the blasts completed correctly
Returns      : 1 upon success
Args         : none
Throws       : croaks if you try to run it on a non-blast job
             : or if file can't be opened
Comments     : none