view release on metacpan or  search on metacpan

lib/FAST/Bio/Search/Result/ResultI.pm  view on Meta::CPAN

use base qw(FAST::Bio::AnalysisResultI);


=head2 next_hit

 Title   : next_hit
 Usage   : while( $hit = $result->next_hit()) { ... }
 Function: Returns the next available Hit object, representing potential
           matches between the query and various entities from the database.
 Returns : a FAST::Bio::Search::Hit::HitI object or undef if there are no more.
 Args    : none


=cut

sub next_hit {
    my ($self,@args) = @_;
    $self->throw_not_implemented;
}

=head2 sort_hits

 Title		: sort_hits
 Usage		: $result->sort_hits(\&sort_function)
 Function	: Sorts the available hit objects by a user-supplied function. Defaults to sort
                  by descending score.
 Returns	: n/a
 Args		: A coderef for the sort function.  See the documentation on the Perl sort() 
                  function for guidelines on writing sort functions.  
 Note		: To access the special variables $a and $b used by the Perl sort() function 
                  the user function must access FAST::Bio::Search::Result::ResultI namespace. 
                  For example, use : 
                  $result->sort_hits( sub{$FAST::Bio::Search::Result::ResultI::a->length <=> 
					      $FAST::Bio::Search::Result::ResultI::b->length});
                   NOT $result->sort_hits($a->length <=>$b->length);

=cut

sub sort_hits {
    my ($self, $coderef) = @_;
    my @sorted_hits;

    if ($coderef)  {
	$self->throw('sort_hits requires a sort function passed as a subroutine reference')
	    unless (ref($coderef) eq 'CODE');
    }
    else {
	$coderef = \&_default_sort_hits;
	# throw a warning?
    }

    my @hits = $self->hits();
    
    eval {@sorted_hits = sort $coderef @hits };

   if ($@) {
       $self->throw("Unable to sort hits: $@");
   }
   else {
       $self->{'_hits'} = \@sorted_hits;
       $self->{'_no_iterations'} = 1; # to bypass iteration checking in hits() method
       1;
   }
}

=head2 _default sort_hits

  Title	: _default_sort_hits
  Usage	: Do not call directly.
  Function: Sort hits in descending order by score
  Args	: None
  Returns: 1 on success
  Note	: Used by $result->sort_hits()

=cut

sub _default_sort_hits {
    $FAST::Bio::Search::Result::ResultI::b->score <=> 
	    $FAST::Bio::Search::Result::ResultI::a->score;

}

=head2 query_name

 Title   : query_name
 Usage   : $id = $result->query_name();
 Function: Get the string identifier of the query used by the
           algorithm that performed the search.
 Returns : a string.
 Args    : none

=cut

sub query_name {
    my ($self,@args) = @_;
    $self->throw_not_implemented;
}

=head2 query_accession

 Title   : query_accession
 Usage   : $id = $result->query_accession();
 Function: Get the accession (if available) for the query sequence
 Returns : a string
 Args    : none

=cut

sub query_accession {
    my ($self,@args) = @_;
    $self->throw_not_implemented;
}


=head2 query_length

 Title   : query_length
 Usage   : $id = $result->query_length();
 Function: Get the length of the query sequence
           used in the search.
 Returns : a number