AlignAid - easily run sequence alignments locally or on a cluster
This document describes AlignAid version 0.0.2
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;
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.
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>.
<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.
AlignAid requires no configuration files or environment variables.
part of BioPerl, available at bioperl.org
available from CPAN
This is an optional dependency, needed if you want to submit jobs to a compute cluster queueing system like LSF
This is an optional dependency, needed only if you want to use the validate_blasts() method. Available from Jarret Glasscock <glasscock_cpan@mac.com>.
None reported.
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.
dave-pause@davemessina.net
Dave Messina <dave-pause@davemessina.net>
<dave-pause@davemessina.net>
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.
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.
The rest of the documentation details each of the functions. Internal methods are preceded with a "_".
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
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
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
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
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
To install AlignAid, copy and paste the appropriate command in to your terminal.
cpanm
cpanm AlignAid
CPAN shell
perl -MCPAN -e shell install AlignAid
For more information on module installation, please visit the detailed CPAN module installation guide.