view release on metacpan or  search on metacpan

lib/AlignAid.pm  view on Meta::CPAN

=item C<< fasta [<foo>] does not exist >>

The fasta file 'foo' could not be located.

=item C<< fasta [<foo>] is not a text file >>

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

=item C<< 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).

=item C<< <foo> is not a supported queue type >>

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

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

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

=item C<< 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.

=item C<< unrecognized alignment program >>

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

=item C<< 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.

=item C<< 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.

=item C<< 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.

=item C<< <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() ).

=item C<< 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 C<< <glasscock_cpan@mac.com> >>.

=item C<< 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.

=back


=head1 CONFIGURATION AND ENVIRONMENT
  
AlignAid requires no configuration files or environment variables.


=head1 DEPENDENCIES

=over

=item Bio::SeqIO

part of BioPerl, available at bioperl.org

=item version

available from CPAN

=item PP

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

=item BPdeluxe 1.0

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

=back

=head1 INCOMPATIBILITIES

None reported.


=head1 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
C<dave-pause@davemessina.net>.


=head1 AUTHOR

Dave Messina  C<< <dave-pause@davemessina.net> >>


=head1 LICENCE AND COPYRIGHT

Copyright (c) 2006, Dave Messina C<< <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 L<perlartistic>.


=head1 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.

=head1 APPENDIX

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

lib/AlignAid.pm  view on Meta::CPAN

            $ENTRIES = "";
            $counter = 0;
            $internal++;
        }
    }    # end of multi-processor else

    # add refs to the jobs
    $class->{_jobs} = \@jobs;

    return $ret_val;
}

=head2 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

=cut

sub kill_all {

    my ( $self, %arg ) = @_;

    if ( $self->{_queue} eq 'single' ) {
        croak "single job killing not implemented yet";
    }
    elsif ( $self->{_queue} eq 'LSF' ) {

        # kill each job
        my $i = 0;
        foreach my $job ( @{ $self->{_jobs} } ) {
            $job->kill;

            unless ( $job->is_in_queue(1) ) {
                delete $self->{_jobs}[ $i++ ];
            }
        }

        if ( scalar @{ $self->{_jobs} } > 0 ) {
            my $num_jobs = scalar @{ $self->{_jobs} };
            warn "$num_jobs weren't killed and still are in the queue";
            return 0;
        }
        else { return 1; }
    }
    elsif ( $self->{_queue} eq 'PBS' ) {
        croak "Sorry! PBS queue support not implemented yet!\n";
        return 0;
    }
    else {
        croak "$self->{_queue} is not a supported queue type";
        return 0;
    }
}

=head2 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

=cut

sub validate_blasts {
    eval { require 'BPdeluxe 1.0'; };
    if ($@) {
        croak "can't validate_blasts -- BPdeluxe 1.0 did not load.\n";
        return;
    };

    my ( $class ) = @_;

### ------------------------------------------
    # not yet implemented for single-proc runs
    if ( $class->{_queue} eq 'single' ) {
	return 1;
    }
### ------------------------------------------

    my @jobs = @{ $class->{_jobs} };
    my %skip; # files to skip due to incomplete blast reports
    my $ret_val = 1;

    if ( $class->{_prog_name} !~ /[t]*blast[nxp]/ ) {
	croak "validate_blasts only works on blast jobs";
    }

    if ( $class->{_queue} eq 'single' ) {
	
    }
    foreach  my $job (@jobs) {
	my $blast_reports = $job->{oo};
	my $file = IO::File->new($blast_reports, "r")
	    or croak "couldn't open $blast_reports";
	my $multi_report = new BPdeluxe::Multi($file);
	REPORT: while ( my $report = $multi_report->nextReport ) {
	    my $name = $report->query;
	    unless ( $report->completed ) {
		print STDOUT "blast of $name didn't complete correctly\n",
		"    see file $blast_reports.\n",
		"    skipping file...\n";
		$skip{$blast_reports} = 1;
		$ret_val = 0;
		last REPORT;
	    }
	}
    }
    # save the bad files to our object
    $class->{_skip} = \%skip;
    return $ret_val;
}

=head2 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

=cut

sub consolidate_output {
    my ( $class, %args ) = @_;

    my %skip    = %{ $class->{_skip} };
    my $outfile = $class->{_outfile};
    if (!$outfile) { croak "no output file specified!"; }
    my $out_fh  = IO::File->new($outfile, "w")
	or croak "couldn't open $outfile";

    my @jobs = @{ $class->{_jobs} };
    JOB: foreach my $job (@jobs) {
	my $job_outfile = $job->{oo};

	# skip files with incomplete jobs
	# (currently only works with blast jobs)
	next JOB if $skip{$job_outfile};

	# open and copy output files into one big file
	my $job_fh = IO::File->new($job_outfile, "r")
	    or croak "couldn't open $job_outfile";