199
73
# Let the code begin...
201
76
package Bio::Search::Hit::BlastHit;
204
use Bio::Search::Hit::HitI;
206
require Bio::Search::BlastUtils;
207
use vars qw( @ISA %SUMMARY_OFFSET $Revision);
212
@ISA = qw( Bio::Root::Root Bio::Search::Hit::HitI );
214
$Revision = '$Id: BlastHit.pm,v 1.9 2002/01/23 11:30:25 heikki Exp $'; #'
80
use Bio::Search::Hit::GenericHit;
81
require Bio::Search::SearchUtils;
83
@ISA = qw(Bio::Search::Hit::GenericHit);
219
Usage : $hit = Bio::Search::Hit::BlastHit->new( %named_params );
220
: Bio::Search::Hit::BlastHit.pm objects are constructed
221
: automatically by Bio::SearchIO::BlastHitFactory.pm,
222
: so there is no need for direct instantiation.
223
Purpose : Constructs a new BlastHit object and Initializes key variables
225
Returns : A Bio::Search::Hit::BlastHit object
226
Argument : Named Parameters:
227
: Parameter keys are case-insensitive.
228
: -RAW_DATA => array reference holding raw BLAST report data
229
: for a single hit. This includes all lines
230
: within the HSP alignment listing section of a
231
: traditional BLAST or PSI-BLAST (non-XML) report,
232
: starting at (or just after) the leading '>'.
233
: -HOLD_RAW_DATA => boolean, should -RAW_DATA be saved within the object.
234
: -QUERY_LEN => Length of the query sequence
235
: -ITERATION => integer (PSI-BLAST iteration number in which hit was found)
236
: -OVERLAP => integer (maximum overlap between adjacent
238
: -PROGRAM => string (type of Blast: BLASTP, BLASTN, etc)
239
: -SIGNIF => significance
240
: -IS_PVAL => boolean, true if -SIGNIF contains a P-value
241
: -SCORE => raw BLAST score
242
: -FOUND_AGAIN => boolean, true if this was a hit from the
243
: section of a PSI-BLAST with iteration > 1
244
: containing sequences that were also found
246
Comments : This object accepts raw Blast report data not because it
247
: is required for parsing, but in order to retrieve it
248
: (only available if -HOLD_RAW_DATA is set to true).
250
See Also : L<Bio::Search::BlastUtils::tile_hsps()|Bio::Search::BlastUtils>, L<Bio::Root::Root::new()|Bio::Root::Root>
88
Usage : my $obj = new Bio::Search::Hit::GenericHit();
89
Function: Builds a new Bio::Search::Hit::GenericHit object
90
Returns : Bio::Search::Hit::GenericHit
91
Args : See Bio::Search::Hit::GenericHit() for other args.
92
Here are the BLAST-specific args that can be used when
93
creating BlastHit objects:
94
-iteration => integer for the PSI-Blast iteration number
95
-found_again => boolean, true if hit appears in a
96
"previously found" section of a PSI-Blast report.
257
my ($class, @args ) = @_;
258
my $self = $class->SUPER::new( @args );
260
my ($raw_data, $signif, $is_pval, $hold_raw);
262
($self->{'_blast_program'}, $self->{'_query_length'}, $raw_data, $hold_raw,
263
$self->{'_overlap'}, $self->{'_iteration'}, $signif, $is_pval,
264
$self->{'_score'}, $self->{'_found_again'} ) =
265
$self->_rearrange( [qw(PROGRAM
274
FOUND_AGAIN )], @args );
276
$self->_set_id( $raw_data->[0] );
279
$self->{'_p'} = $signif;
281
$self->{'_expect'} = $signif;
285
$self->{'_hit_data'} = $raw_data;
293
#print STDERR "-->DESTROYING $self\n";
297
#=================================================
298
# Begin Bio::Search::Hit::HitI implementation
299
#=================================================
304
Usage : $alg = $hit->algorithm();
305
Function: Gets the algorithm specification that was used to obtain the hit
306
For BLAST, the algorithm denotes what type of sequence was aligned
307
against what (BLASTN: dna-dna, BLASTP prt-prt, BLASTX translated
308
dna-prt, TBLASTN prt-translated dna, TBLASTX translated
310
Returns : a scalar string
318
my ($self,@args) = @_;
319
return $self->{'_blast_program'};
324
Usage : $hit->name([string]);
325
Purpose : Set/Get a string to identify the hit.
326
This is parsed out of the "Query=" line as the first chunk of
327
non-whitespace text. If you want the rest of the line, use
329
Example : $name = $hit->name;
330
: $hit->name('M81707');
331
Returns : String consisting of the hit's name or undef if not set.
343
$name =~ s/^\s+|(\s+|,)$//g;
344
$self->{'_name'} = $name;
346
return $self->{'_name'};
351
Usage : $hit_object->description( [integer] );
352
Purpose : Set/Get a description string for the hit.
353
This is parsed out of the "Query=" line as everything after
354
the first chunk of non-whitespace text. Use $hit->name()
355
to get the first chunk (the ID of the sequence).
356
Example : $description = $hit->description;
357
: $desc_60char = $hit->description(60);
358
Argument : Integer (optional) indicating the desired length of the
359
: description string to be returned.
360
Returns : String consisting of the hit's description or undef if not set.
369
my( $self, $len ) = @_;
370
$len = (defined $len) ? $len : (CORE::length $self->{'_description'});
371
return substr( $self->{'_description'}, 0 ,$len );
376
Usage : $hit_object->raw_score();
377
Purpose : Gets the BLAST score of the best HSP for the current Blast hit.
378
Example : $score = $hit_object->raw_score();
383
See Also : L<bits()|bits>
392
# The check for $self->{'_score'} is a remnant from the 'query' mode days
393
# in which the sbjct object would collect data from the description line only.
396
if(not defined($self->{'_score'})) {
397
$score = $self->hsp->score;
399
$score = $self->{'_score'};
407
Usage : $hit_object->length();
408
Purpose : Get the total length of the hit sequence.
409
Example : $len = $hit_object->length();
413
Comments : Developer note: when using the built-in length function within
414
: this module, call it as CORE::length().
416
See Also : L<logical_length()|logical_length>, L<length_aln()|length_aln>
424
return $self->{'_length'};
429
Equivalent to L<signif()|signif>
434
sub significance { shift->signif( @_ ); }
441
Usage : $hsp = $obj->next_hsp();
442
Function : returns the next available High Scoring Pair object
444
Returns : Bio::Search::HSP::BlastHSP or undef if finished
454
unless($self->{'_hsp_queue_started'}) {
455
$self->{'_hsp_queue'} = [$self->hsps()];
456
$self->{'_hsp_queue_started'} = 1;
458
pop @{$self->{'_hsp_queue'}};
461
#=================================================
462
# End Bio::Search::Hit::HitI implementation
463
#=================================================
466
# Providing a more explicit method for getting name of hit
467
# (corresponds with column name in HitTableWriter)
475
# Older method Delegates to description()
480
return $self->description( @_ );
483
# Providing a more explicit method for getting description of hit
484
# (corresponds with column name in HitTableWriter)
486
sub hit_description {
489
return $self->description( @_ );
494
Equivalent to L<raw_score()|raw_score>
499
sub score { shift->raw_score( @_ ); }
505
Equivalent to L<length()|length>
509
# Providing a more explicit method for getting length of hit
511
sub hit_length { shift->length( @_ ); }
517
Usage : $hit_object->signif( [format] );
518
Purpose : Get the P or Expect value for the best HSP of the given BLAST hit.
519
: The value returned is the one which is reported in the description
520
: section of the Blast report. For Blast1 and WU-Blast2, this
521
: is a P-value, for Blast2, it is an Expect value.
522
Example : $obj->signif() # returns 1.3e-34
523
: $obj->signif('exp') # returns -34
524
: $obj->signif('parts') # returns (1.3, -34)
525
Returns : Float or scientific notation number (the raw P/Expect value, DEFAULT).
526
: Integer if format == 'exp' (the magnitude of the base 10 exponent).
527
: 2-element list (float, int) if format == 'parts' and P/Expect value
528
: is in scientific notation (see Comments).
529
Argument : format: string of 'raw' | 'exp' | 'parts'
530
: 'raw' returns value given in report. Default. (1.2e-34)
531
: 'exp' returns exponent value only (34)
532
: 'parts' returns the decimal and exponent as a
533
: 2-element list (1.2, -34) (see Comments).
535
Comments : The signif() method provides a way to deal with the fact that
536
: Blast1 and Blast2 formats (and WU- vs. NCBI-BLAST) differ in
537
: what is reported in the description lines of each hit in the
538
: Blast report. The signif() method frees any client code from
539
: having to know if this is a P-value or an Expect value,
540
: making it easier to write code that can process both
541
: Blast1 and Blast2 reports. This is not necessarily a good thing,
542
: since one should always know when one is working with P-values or
543
: Expect values (hence the deprecated status).
544
: Use of expect() is recommended since all hits will have an Expect value.
546
: Using the 'parts' argument is not recommended since it will not
547
: work as expected if the expect value is not in scientific notation.
548
: That is, floats are not converted into sci notation before
549
: splitting into parts.
551
See Also : L<p()|p>, L<expect()|expect>, L<Bio::Search::BlastUtils::get_exponent()|Bio::Search::BlastUtils>
558
# Some duplication of logic for p(), expect() and signif() for the sake of performance.
559
my ($self, $fmt) = @_;
561
my $val = defined($self->{'_p'}) ? $self->{'_p'} : $self->{'_expect'};
564
defined($val) or $self->throw("Can't get P- or Expect value: HSPs may not have been set.");
566
return $val if not $fmt or $fmt =~ /^raw/i;
567
## Special formats: exponent-only or as list.
568
return &Bio::Search::BlastUtils::get_exponent($val) if $fmt =~ /^exp/i;
569
return (split (/eE/, $val)) if $fmt =~ /^parts/i;
571
## Default: return the raw P/Expect-value.
580
# Need to add blank lines where we've removed them.
581
foreach( @{$self->{'_hit_data'}} ) {
586
$data .= /^\s*(Score|Query)/ ? "\n$_" : $_;
595
# Usage : $hit_object->_set_length( "233" );
596
# Purpose : Set the total length of the hit sequence.
597
# Example : $hit_object->_set_length( $len );
599
# Argument : Integer (only when setting). Any commas will be stripped out.
607
my ($self, $len) = @_;
608
$len =~ s/,//g; # get rid of commas
609
$self->{'_length'} = $len;
612
#=head2 _set_description
614
# Usage : Private method; called automatically during construction
615
# Purpose : Sets the description of the hit sequence.
616
# : For sequence without descriptions, does not set any description.
617
# Argument : Array containing description (multiple lines).
618
# Comments : Processes the supplied description:
619
# 1. Join all lines into one string.
620
# 2. Remove sequence id at the beginning of description.
621
# 3. Removes junk charactes at begin and end of description.
626
sub _set_description {
628
my( $self, @desc ) = @_;
631
# print STDERR "BlastHit: RAW DESC:\n@desc\n";
633
$desc = join(" ", @desc);
635
my $name = $self->name;
638
$desc =~ s/^\s*\S+\s+//; # remove the sequence ID(s)
639
# This won't work if there's no description.
640
$desc =~ s/^\s*$name//; # ...but this should.
641
$desc =~ s/^[\s!]+//;
644
$self->{'_description'} = $desc;
647
# print STDERR "BlastHit: _set_description = $desc\n";
653
Usage : print $hit->to_string;
654
Function: Returns a string representation for the Blast Hit.
655
Primarily intended for debugging purposes.
657
Returns : A string of the form:
658
[BlastHit] <name> <description>
660
[BlastHit] emb|Z46660|SC9725 S.cerevisiae chromosome XIII cosmid
669
return "[BlastHit] " . $self->name . " " . $self->description;
675
# Usage : Private method; automatically called by new()
676
# Purpose : Sets the name of the BlastHit sequence from the BLAST summary line.
677
# : The identifier is assumed to be the first
678
# : chunk of non-whitespace characters in the description line
679
# : Does not assume any semantics in the structure of the identifier
680
# : (Formerly, this method attempted to extract database name from
681
# : the seq identifiers, but this was prone to break).
683
# Argument : String containing description line of the hit from Blast report
684
# : or first line of an alignment section (with or without the leading '>').
685
# Throws : Warning if cannot locate sequence ID.
687
#See Also : L<new()|new>
694
my( $self, $desc ) = @_;
696
# New strategy: Assume only that the ID is the first white space
697
# delimited chunk. Not attempting to extract database name.
698
# Clients will have to interpret it as necessary.
699
if($desc =~ /^>?(\S+)\s*(.*)/) {
701
$self->{'_description'} = $2;
702
# Note that this description comes from the summary section of the
703
# BLAST report and so may be truncated. The full description will be
704
# set from the alignment section. We're setting description here in case
705
# the alignment section isn't being parsed.
708
$self->warn("Can't locate sequence identifier in summary line.", "Line = $desc");
709
$desc = 'Unknown sequence ID' if not $desc;
717
Usage : $ambig_code = $hit_object->ambiguous_aln();
718
Purpose : Sets/Gets ambiguity code data member.
719
Example : (see usage)
720
Returns : String = 'q', 's', 'qs', '-'
721
: 'q' = query sequence contains overlapping sub-sequences
722
: while sbjct does not.
723
: 's' = sbjct sequence contains overlapping sub-sequences
724
: while query does not.
725
: 'qs' = query and sbjct sequence contains overlapping sub-sequences
726
: relative to each other.
727
: '-' = query and sbjct sequence do not contains multiple domains
728
: relative to each other OR both contain the same distribution
729
: of similar domains.
732
Status : Experimental
734
See Also : L<Bio::Search::BlastUtils::tile_hsps>, L<HSP Tiling and Ambiguous Alignments>
738
#--------------------
740
#--------------------
742
if(@_) { $self->{'_ambiguous_aln'} = shift; }
743
$self->{'_ambiguous_aln'} || '-';
750
Usage : $blast_object->overlap( [integer] );
751
Purpose : Gets/Sets the allowable amount overlap between different HSP sequences.
752
Example : $blast_object->overlap(5);
753
: $overlap = $blast_object->overlap;
757
Status : Experimental
758
Comments : Any two HSPs whose sequences overlap by less than or equal
759
: to the overlap() number of resides will be considered separate HSPs
760
: and will not get tiled by Bio::Search::BlastUtils::_adjust_contigs().
762
See Also : L<Bio::Search::BlastUtils::_adjust_contigs()|Bio::Search::BlastUtils>, L<BUGS | BUGS>
770
if(@_) { $self->{'_overlap'} = shift; }
771
defined $self->{'_overlap'} ? $self->{'_overlap'} : 0;
781
Usage : $hit_object->bits();
782
Purpose : Gets the BLAST bit score of the best HSP for the current Blast hit.
783
Example : $bits = $hit_object->bits();
786
Throws : Exception if bit score is not set.
787
Comments : For BLAST1, the non-bit score is listed in the summary line.
789
See Also : L<score()|score>
798
# The check for $self->{'_bits'} is a remnant from the 'query' mode days
799
# in which the sbjct object would collect data from the description line only.
802
if(not defined($self->{'_bits'})) {
803
$bits = $self->hsp->bits;
805
$bits = $self->{'_bits'};
814
Usage : $hit_object->n();
815
Purpose : Gets the N number for the current Blast hit.
816
: This is the number of HSPs in the set which was ascribed
817
: the lowest P-value (listed on the description line).
818
: This number is not the same as the total number of HSPs.
819
: To get the total number of HSPs, use num_hsps().
820
Example : $n = $hit_object->n();
823
Throws : Exception if HSPs have not been set (BLAST2 reports).
824
Comments : Note that the N parameter is not reported in gapped BLAST2.
825
: Calling n() on such reports will result in a call to num_hsps().
826
: The num_hsps() method will count the actual number of
827
: HSPs in the alignment listing, which may exceed N in
830
See Also : L<num_hsps()|num_hsps>
839
# The check for $self->{'_n'} is a remnant from the 'query' mode days
840
# in which the sbjct object would collect data from the description line only.
843
if(not defined($self->{'_n'})) {
848
$n ||= $self->num_hsps;
857
Usage : $hit_object->frame();
858
Purpose : Gets the reading frame for the hit sequence (TBLASTN/X only).
859
Example : $frame = $hit_object->frame();
860
Returns : Integer (-3 .. +3).
862
Throws : Exception if HSPs have not been set (BLAST2 reports).
864
See Also : L<hsps()|hsps>
873
# The check for $self->{'_frame'} is a remnant from the 'query' mode days
874
# in which the sbjct object would collect data from the description line only.
877
if(not defined($self->{'_frame'})) {
878
$frame = $self->hsp->frame;
880
$frame = $self->{'_frame'};
891
Usage : $hit_object->p( [format] );
892
Purpose : Get the P-value for the best HSP of the given BLAST hit.
893
: (Note that P-values are not provided with NCBI Blast2 reports).
894
Example : $p = $sbjct->p;
895
: $p = $sbjct->p('exp'); # get exponent only.
896
: ($num, $exp) = $sbjct->p('parts'); # split sci notation into parts
897
Returns : Float or scientific notation number (the raw P-value, DEFAULT).
898
: Integer if format == 'exp' (the magnitude of the base 10 exponent).
899
: 2-element list (float, int) if format == 'parts' and P-value
900
: is in scientific notation (See Comments).
901
Argument : format: string of 'raw' | 'exp' | 'parts'
902
: 'raw' returns value given in report. Default. (1.2e-34)
903
: 'exp' returns exponent value only (34)
904
: 'parts' returns the decimal and exponent as a
905
: 2-element list (1.2, -34) (See Comments).
906
Throws : Warns if no P-value is defined. Uses expect instead.
907
Comments : Using the 'parts' argument is not recommended since it will not
908
: work as expected if the P-value is not in scientific notation.
909
: That is, floats are not converted into sci notation before
910
: splitting into parts.
912
See Also : L<expect()|expect>, L<signif()|signif>, L<Bio::Search::BlastUtils::get_exponent()|Bio::Search::BlastUtils>
919
# Some duplication of logic for p(), expect() and signif() for the sake of performance.
920
my ($self, $fmt) = @_;
922
my $val = $self->{'_p'};
925
if(not defined $val) {
926
# P-value not defined, must be a NCBI Blast2 report.
927
# Use expect instead.
928
$self->warn( "P-value not defined. Using expect() instead.");
929
$val = $self->{'_expect'};
932
return $val if not $fmt or $fmt =~ /^raw/i;
933
## Special formats: exponent-only or as list.
934
return &Bio::Search::BlastUtils::get_exponent($val) if $fmt =~ /^exp/i;
935
return (split (/eE/, $val)) if $fmt =~ /^parts/i;
937
## Default: return the raw P-value.
945
Usage : $hit_object->expect( [format] );
946
Purpose : Get the Expect value for the best HSP of the given BLAST hit.
947
Example : $e = $sbjct->expect;
948
: $e = $sbjct->expect('exp'); # get exponent only.
949
: ($num, $exp) = $sbjct->expect('parts'); # split sci notation into parts
950
Returns : Float or scientific notation number (the raw expect value, DEFAULT).
951
: Integer if format == 'exp' (the magnitude of the base 10 exponent).
952
: 2-element list (float, int) if format == 'parts' and Expect
953
: is in scientific notation (see Comments).
954
Argument : format: string of 'raw' | 'exp' | 'parts'
955
: 'raw' returns value given in report. Default. (1.2e-34)
956
: 'exp' returns exponent value only (34)
957
: 'parts' returns the decimal and exponent as a
958
: 2-element list (1.2, -34) (see Comments).
959
Throws : Exception if the Expect value is not defined.
960
Comments : Using the 'parts' argument is not recommended since it will not
961
: work as expected if the expect value is not in scientific notation.
962
: That is, floats are not converted into sci notation before
963
: splitting into parts.
965
See Also : L<p()|p>, L<signif()|signif>, L<Bio::Search::BlastUtils::get_exponent()|Bio::Search::BlastUtils>
972
# Some duplication of logic for p(), expect() and signif() for the sake of performance.
973
my ($self, $fmt) = @_;
977
# For Blast reports that list the P value on the description line,
978
# getting the expect value requires fully parsing the HSP data.
979
# For NCBI blast, there's no problem.
980
if(not defined($self->{'_expect'})) {
981
if( defined $self->{'_hsps'}) {
982
$self->{'_expect'} = $val = $self->hsp->expect;
984
# If _expect is not set and _hsps are not set,
985
# then this must be a P-value-based report that was
986
# run without setting the HSPs (shallow parsing).
987
$self->throw("Can't get expect value. HSPs have not been set.");
990
$val = $self->{'_expect'};
994
defined($val) or $self->throw("Can't get Expect value.");
996
return $val if not $fmt or $fmt =~ /^raw/i;
997
## Special formats: exponent-only or as list.
998
return &Bio::Search::BlastUtils::get_exponent($val) if $fmt =~ /^exp/i;
999
return (split (/eE/, $val)) if $fmt =~ /^parts/i;
1001
## Default: return the raw Expect-value.
1008
Usage : $hit_object->hsps();
1009
Purpose : Get a list containing all HSP objects.
1010
: Get the numbers of HSPs for the current hit.
1011
Example : @hsps = $hit_object->hsps();
1012
: $num = $hit_object->hsps(); # alternatively, use num_hsps()
1013
Returns : Array context : list of Bio::Search::HSP::BlastHSP.pm objects.
1014
: Scalar context: integer (number of HSPs).
1015
: (Equivalent to num_hsps()).
1016
Argument : n/a. Relies on wantarray
1017
Throws : Exception if the HSPs have not been collected.
1019
See Also : L<hsp()|hsp>, L<num_hsps()|num_hsps>
1028
if (not ref $self->{'_hsps'}) {
1029
$self->throw("Can't get HSPs: data not collected.");
1033
# returning list containing all HSPs.
1034
? @{$self->{'_hsps'}}
1035
# returning number of HSPs.
1036
: scalar(@{$self->{'_hsps'}});
1043
Usage : $hit_object->hsp( [string] );
1044
Purpose : Get a single BlastHSP.pm object for the present BlastHit.pm object.
1045
Example : $hspObj = $hit_object->hsp; # same as 'best'
1046
: $hspObj = $hit_object->hsp('best');
1047
: $hspObj = $hit_object->hsp('worst');
1048
Returns : Object reference for a Bio::Search::HSP::BlastHSP.pm object.
1049
Argument : String (or no argument).
1050
: No argument (default) = highest scoring HSP (same as 'best').
1051
: 'best' or 'first' = highest scoring HSP.
1052
: 'worst' or 'last' = lowest scoring HSP.
1053
Throws : Exception if the HSPs have not been collected.
1054
: Exception if an unrecognized argument is used.
1056
See Also : L<hsps()|hsps>, L<num_hsps>()
1063
my( $self, $option ) = @_;
1066
if (not ref $self->{'_hsps'}) {
1067
$self->throw("Can't get HSPs: data not collected.");
1070
my @hsps = @{$self->{'_hsps'}};
1072
return $hsps[0] if $option =~ /best|first|1/i;
1073
return $hsps[$#hsps] if $option =~ /worst|last/i;
1075
$self->throw("Can't get HSP for: $option\n" .
1076
"Valid arguments: 'best', 'worst'");
1083
Usage : $hit_object->num_hsps();
1084
Purpose : Get the number of HSPs for the present Blast hit.
1085
Example : $nhsps = $hit_object->num_hsps();
1088
Throws : Exception if the HSPs have not been collected.
1090
See Also : L<hsps()|hsps>
1099
if (not defined $self->{'_hsps'}) {
1100
$self->throw("Can't get HSPs: data not collected.");
1103
return scalar(@{$self->{'_hsps'}});
1108
=head2 logical_length
1110
Usage : $hit_object->logical_length( [seq_type] );
1111
: (mostly intended for internal use).
1112
Purpose : Get the logical length of the hit sequence.
1113
: If the Blast is a TBLASTN or TBLASTX, the returned length
1114
: is the length of the would-be amino acid sequence (length/3).
1115
: For all other BLAST flavors, this function is the same as length().
1116
Example : $len = $hit_object->logical_length();
1118
Argument : seq_type = 'query' or 'hit' or 'sbjct' (default = 'query')
1119
('sbjct' is synonymous with 'hit')
1121
Comments : This is important for functions like frac_aligned_query()
1122
: which need to operate in amino acid coordinate space when dealing
1123
: with [T]BLAST[NX] type reports.
1125
See Also : L<length()|length>, L<frac_aligned_query()|frac_aligned_query>, L<frac_aligned_hit()|frac_aligned_hit>
1129
#--------------------
1130
sub logical_length {
1131
#--------------------
1133
my $seqType = shift || 'query';
1134
$seqType = 'sbjct' if $seqType eq 'hit';
1138
# For the sbjct, return logical sbjct length
1139
if( $seqType eq 'sbjct' ) {
1140
$length = $self->{'_logical_length'} || $self->{'_length'};
1143
# Otherwise, return logical query length
1144
$length = $self->{'_query_length'};
1146
# Adjust length based on BLAST flavor.
1147
if($self->{'_blast_program'} =~ /T?BLASTX/ ) {
1157
Usage : $hit_object->length_aln( [seq_type] );
1158
Purpose : Get the total length of the aligned region for query or sbjct seq.
1159
: This number will include all HSPs
1160
Example : $len = $hit_object->length_aln(); # default = query
1161
: $lenAln = $hit_object->length_aln('query');
1163
Argument : seq_Type = 'query' or 'hit' or 'sbjct' (Default = 'query')
1164
('sbjct' is synonymous with 'hit')
1165
Throws : Exception if the argument is not recognized.
1166
Comments : This method will report the logical length of the alignment,
1167
: meaning that for TBLAST[NX] reports, the length is reported
1168
: using amino acid coordinate space (i.e., nucleotides / 3).
1170
: This method requires that all HSPs be tiled. If they have not
1171
: already been tiled, they will be tiled first automatically..
1172
: If you don't want the tiled data, iterate through each HSP
1173
: calling length() on each (use hsps() to get all HSPs).
1175
See Also : L<length()|length>, L<frac_aligned_query()|frac_aligned_query>, L<frac_aligned_hit()|frac_aligned_hit>, L<gaps()|gaps>, L<Bio::Search::BlastUtils::tile_hsps()|Bio::Search::BlastUtils>, L<Bio::Search::HSP::BlastHSP::length()|Bio::Search::HSP::BlastHSP>
1182
my( $self, $seqType ) = @_;
1184
$seqType ||= 'query';
1185
$seqType = 'sbjct' if $seqType eq 'hit';
1187
Bio::Search::BlastUtils::tile_hsps($self) if not $self->{'_tile_hsps'};
1189
my $data = $self->{'_length_aln_'.$seqType};
1191
## If we don't have data, figure out what went wrong.
1193
$self->throw("Can't get length aln for sequence type \"$seqType\"" .
1194
"Valid types are 'query', 'hit', 'sbjct' ('sbjct' = 'hit')");
1202
Usage : $hit_object->gaps( [seq_type] );
1203
Purpose : Get the number of gaps in the aligned query, sbjct, or both sequences.
1204
: Data is summed across all HSPs.
1205
Example : $qgaps = $hit_object->gaps('query');
1206
: $hgaps = $hit_object->gaps('hit');
1207
: $tgaps = $hit_object->gaps(); # default = total (query + hit)
1208
Returns : scalar context: integer
1209
: array context without args: two-element list of integers
1210
: (queryGaps, sbjctGaps)
1211
: Array context can be forced by providing an argument of 'list' or 'array'.
1213
: CAUTION: Calling this method within printf or sprintf is arrray context.
1214
: So this function may not give you what you expect. For example:
1215
: printf "Total gaps: %d", $hit->gaps();
1216
: Actually returns a two-element array, so what gets printed
1217
: is the number of gaps in the query, not the total
1219
Argument : seq_type: 'query' | 'hit' or 'sbjct' | 'total' | 'list' (default = 'total')
1220
('sbjct' is synonymous with 'hit')
1222
Comments : If you need data for each HSP, use hsps() and then interate
1223
: through each HSP object.
1224
: This method requires that all HSPs be tiled. If they have not
1225
: already been tiled, they will be tiled first automatically..
1226
: Not relying on wantarray since that will fail in situations
1227
: such as printf "%d", $hit->gaps() in which you might expect to
1228
: be printing the total gaps, but evaluates to array context.
1230
See Also : L<length_aln()|length_aln>
1237
my( $self, $seqType ) = @_;
1239
$seqType ||= (wantarray ? 'list' : 'total');
1240
$seqType = 'sbjct' if $seqType eq 'hit';
1242
Bio::Search::BlastUtils::tile_hsps($self) if not $self->{'_tile_hsps'};
1244
$seqType = lc($seqType);
1246
if($seqType =~ /list|array/i) {
1247
return ($self->{'_gaps_query'}, $self->{'_gaps_sbjct'});
1250
if($seqType eq 'total') {
1251
return ($self->{'_gaps_query'} + $self->{'_gaps_sbjct'}) || 0;
1253
return $self->{'_gaps_'.$seqType} || 0;
1261
Usage : $hit_object->matches( [class] );
1262
Purpose : Get the total number of identical or conserved matches
1263
: (or both) across all HSPs.
1264
: (Note: 'conservative' matches are indicated as 'positives'
1265
: in the Blast report.)
1266
Example : ($id,$cons) = $hit_object->matches(); # no argument
1267
: $id = $hit_object->matches('id');
1268
: $cons = $hit_object->matches('cons');
1269
Returns : Integer or a 2-element array of integers
1270
Argument : class = 'id' | 'cons' OR none.
1271
: If no argument is provided, both identical and conservative
1272
: numbers are returned in a two element list.
1273
: (Other terms can be used to refer to the conservative
1274
: matches, e.g., 'positive'. All that is checked is whether or
1275
: not the supplied string starts with 'id'. If not, the
1276
: conservative matches are returned.)
1277
Throws : Exception if the requested data cannot be obtained.
1278
Comments : If you need data for each HSP, use hsps() and then interate
1279
: through the HSP objects.
1280
: Does not rely on wantarray to return a list. Only checks for
1281
: the presence of an argument (no arg = return list).
1283
See Also : L<Bio::Search::HSP::BlastHSP::matches()|Bio::Search::HSP::BlastHSP>, L<hsps()|hsps>
1290
my( $self, $arg) = @_;
1294
@data = ($self->{'_totalIdentical'}, $self->{'_totalConserved'});
1296
return @data if @data;
1300
if($arg =~ /^id/i) {
1301
$data = $self->{'_totalIdentical'};
1303
$data = $self->{'_totalConserved'};
1305
return $data if $data;
1308
## Something went wrong if we make it to here.
1309
$self->throw("Can't get identical or conserved data: no data.");
1315
Usage : $sbjct->start( [seq_type] );
1316
Purpose : Gets the start coordinate for the query, sbjct, or both sequences
1317
: in the BlastHit object. If there is more than one HSP, the lowest start
1318
: value of all HSPs is returned.
1319
Example : $qbeg = $sbjct->start('query');
1320
: $sbeg = $sbjct->start('hit');
1321
: ($qbeg, $sbeg) = $sbjct->start();
1322
Returns : scalar context: integer
1323
: array context without args: list of two integers (queryStart, sbjctStart)
1324
: Array context can be "induced" by providing an argument of 'list' or 'array'.
1325
Argument : In scalar context: seq_type = 'query' or 'hit' or 'sbjct' (default = 'query')
1326
('sbjct' is synonymous with 'hit')
1328
Comments : This method requires that all HSPs be tiled. If there is more than one
1329
: HSP and they have not already been tiled, they will be tiled first automatically..
1330
: Remember that the start and end coordinates of all HSPs are
1331
: normalized so that start < end. Strand information can be
1332
: obtained by calling $hit->strand().
1334
See Also : L<end()|end>, L<range()|range>, L<strand()|strand>, L<HSP Tiling and Ambiguous Alignments>, L<Bio::Search::HSP::BlastHSP::start|Bio::Search::HSP::BlastHSP>
1341
my ($self, $seqType) = @_;
1343
$seqType ||= (wantarray ? 'list' : 'query');
1344
$seqType = 'sbjct' if $seqType eq 'hit';
1346
# If there is only one HSP, defer this call to the solitary HSP.
1347
if($self->num_hsps == 1) {
1348
return $self->hsp->start($seqType);
1350
Bio::Search::BlastUtils::tile_hsps($self) if not $self->{'_tile_hsps'};
1351
if($seqType =~ /list|array/i) {
1352
return ($self->{'_queryStart'}, $self->{'_sbjctStart'});
1354
## Sensitive to member name changes.
1355
$seqType = "_\L$seqType\E";
1356
return $self->{$seqType.'Start'};
1364
Usage : $sbjct->end( [seq_type] );
1365
Purpose : Gets the end coordinate for the query, sbjct, or both sequences
1366
: in the BlastHit object. If there is more than one HSP, the largest end
1367
: value of all HSPs is returned.
1368
Example : $qend = $sbjct->end('query');
1369
: $send = $sbjct->end('hit');
1370
: ($qend, $send) = $sbjct->end();
1371
Returns : scalar context: integer
1372
: array context without args: list of two integers (queryEnd, sbjctEnd)
1373
: Array context can be "induced" by providing an argument of 'list' or 'array'.
1374
Argument : In scalar context: seq_type = 'query' or 'sbjct'
1375
: (case insensitive). If not supplied, 'query' is used.
1377
Comments : This method requires that all HSPs be tiled. If there is more than one
1378
: HSP and they have not already been tiled, they will be tiled first automatically..
1379
: Remember that the start and end coordinates of all HSPs are
1380
: normalized so that start < end. Strand information can be
1381
: obtained by calling $hit->strand().
1383
See Also : L<start()|start>, L<range()|range>, L<strand()|strand>, L<HSP Tiling and Ambiguous Alignments>, L<Bio::Search::HSP::BlastHSP::end|Bio::Search::HSP::BlastHSP>
1390
my ($self, $seqType) = @_;
1392
$seqType ||= (wantarray ? 'list' : 'query');
1393
$seqType = 'sbjct' if $seqType eq 'hit';
1395
# If there is only one HSP, defer this call to the solitary HSP.
1396
if($self->num_hsps == 1) {
1397
return $self->hsp->end($seqType);
1399
Bio::Search::BlastUtils::tile_hsps($self) if not $self->{'_tile_hsps'};
1400
if($seqType =~ /list|array/i) {
1401
return ($self->{'_queryStop'}, $self->{'_sbjctStop'});
1403
## Sensitive to member name changes.
1404
$seqType = "_\L$seqType\E";
1405
return $self->{$seqType.'Stop'};
1412
Usage : $sbjct->range( [seq_type] );
1413
Purpose : Gets the (start, end) coordinates for the query or sbjct sequence
1414
: in the HSP alignment.
1415
Example : ($qbeg, $qend) = $sbjct->range('query');
1416
: ($sbeg, $send) = $sbjct->range('hit');
1417
Returns : Two-element array of integers
1418
Argument : seq_type = string, 'query' or 'hit' or 'sbjct' (default = 'query')
1419
('sbjct' is synonymous with 'hit')
1422
See Also : L<start()|start>, L<end()|end>
1429
my ($self, $seqType) = @_;
1430
$seqType ||= 'query';
1431
$seqType = 'sbjct' if $seqType eq 'hit';
1432
return ($self->start($seqType), $self->end($seqType));
1436
=head2 frac_identical
1438
Usage : $hit_object->frac_identical( [seq_type] );
1439
Purpose : Get the overall fraction of identical positions across all HSPs.
1440
: The number refers to only the aligned regions and does not
1441
: account for unaligned regions in between the HSPs, if any.
1442
Example : $frac_iden = $hit_object->frac_identical('query');
1443
Returns : Float (2-decimal precision, e.g., 0.75).
1444
Argument : seq_type: 'query' | 'hit' or 'sbjct' | 'total'
1445
: default = 'query' (but see comments below).
1446
: ('sbjct' is synonymous with 'hit')
1448
Comments : Different versions of Blast report different values for the total
1449
: length of the alignment. This is the number reported in the
1450
: denominators in the stats section:
1451
: "Identical = 34/120 Positives = 67/120".
1452
: NCBI BLAST uses the total length of the alignment (with gaps)
1453
: WU-BLAST uses the length of the query sequence (without gaps).
1455
: Therefore, when called with an argument of 'total',
1456
: this method will report different values depending on the
1457
: version of BLAST used. Total does NOT take into account HSP
1458
: tiling, so it should not be used.
1460
: To get the fraction identical among only the aligned residues,
1461
: ignoring the gaps, call this method without an argument or
1462
: with an argument of 'query' or 'hit'.
1464
: If you need data for each HSP, use hsps() and then iterate
1465
: through the HSP objects.
1466
: This method requires that all HSPs be tiled. If they have not
1467
: already been tiled, they will be tiled first automatically.
1469
See Also : L<frac_conserved()|frac_conserved>, L<frac_aligned_query()|frac_aligned_query>, L<matches()|matches>, L<Bio::Search::BlastUtils::tile_hsps()|Bio::Search::BlastUtils>
1474
sub frac_identical {
1476
my ($self, $seqType) = @_;
1477
$seqType ||= 'query';
1478
$seqType = 'sbjct' if $seqType eq 'hit';
1480
## Sensitive to member name format.
1481
$seqType = lc($seqType);
1483
Bio::Search::BlastUtils::tile_hsps($self) if not $self->{'_tile_hsps'};
1485
sprintf( "%.2f", $self->{'_totalIdentical'}/$self->{'_length_aln_'.$seqType});
1490
=head2 frac_conserved
1492
Usage : $hit_object->frac_conserved( [seq_type] );
1493
Purpose : Get the overall fraction of conserved positions across all HSPs.
1494
: The number refers to only the aligned regions and does not
1495
: account for unaligned regions in between the HSPs, if any.
1496
Example : $frac_cons = $hit_object->frac_conserved('hit');
1497
Returns : Float (2-decimal precision, e.g., 0.75).
1498
Argument : seq_type: 'query' | 'hit' or 'sbjct' | 'total'
1499
: default = 'query' (but see comments below).
1500
: ('sbjct' is synonymous with 'hit')
1502
Comments : Different versions of Blast report different values for the total
1503
: length of the alignment. This is the number reported in the
1504
: denominators in the stats section:
1505
: "Positives = 34/120 Positives = 67/120".
1506
: NCBI BLAST uses the total length of the alignment (with gaps)
1507
: WU-BLAST uses the length of the query sequence (without gaps).
1509
: Therefore, when called with an argument of 'total',
1510
: this method will report different values depending on the
1511
: version of BLAST used. Total does NOT take into account HSP
1512
: tiling, so it should not be used.
1514
: To get the fraction conserved among only the aligned residues,
1515
: ignoring the gaps, call this method without an argument or
1516
: with an argument of 'query' or 'hit'.
1518
: If you need data for each HSP, use hsps() and then interate
1519
: through the HSP objects.
1520
: This method requires that all HSPs be tiled. If they have not
1521
: already been tiled, they will be tiled first automatically.
1523
See Also : L<frac_identical()|frac_identical>, L<matches()|matches>, L<Bio::Search::BlastUtils::tile_hsps()|Bio::Search::BlastUtils>
1527
#--------------------
1528
sub frac_conserved {
1529
#--------------------
1530
my ($self, $seqType) = @_;
1531
$seqType ||= 'query';
1532
$seqType = 'sbjct' if $seqType eq 'hit';
1534
## Sensitive to member name format.
1535
$seqType = lc($seqType);
1537
Bio::Search::BlastUtils::tile_hsps($self) if not $self->{'_tile_hsps'};
1539
sprintf( "%.2f", $self->{'_totalConserved'}/$self->{'_length_aln_'.$seqType});
1545
=head2 frac_aligned_query
1547
Usage : $hit_object->frac_aligned_query();
1548
Purpose : Get the fraction of the query sequence which has been aligned
1549
: across all HSPs (not including intervals between non-overlapping
1551
Example : $frac_alnq = $hit_object->frac_aligned_query();
1552
Returns : Float (2-decimal precision, e.g., 0.75).
1555
Comments : If you need data for each HSP, use hsps() and then interate
1556
: through the HSP objects.
1557
: To compute the fraction aligned, the logical length of the query
1558
: sequence is used, meaning that for [T]BLASTX reports, the
1559
: full length of the query sequence is converted into amino acids
1560
: by dividing by 3. This is necessary because of the way
1561
: the lengths of aligned sequences are computed.
1562
: This method requires that all HSPs be tiled. If they have not
1563
: already been tiled, they will be tiled first automatically.
1565
See Also : L<frac_aligned_hit()|frac_aligned_hit>, L<logical_length()|logical_length>, L<length_aln()|length_aln>, L<Bio::Search::BlastUtils::tile_hsps()|Bio::Search::BlastUtils>
1569
#----------------------
1570
sub frac_aligned_query {
1571
#----------------------
1574
Bio::Search::BlastUtils::tile_hsps($self) if not $self->{'_tile_hsps'};
1576
sprintf( "%.2f", $self->{'_length_aln_query'}/$self->logical_length('query'));
1581
=head2 frac_aligned_hit
1583
Usage : $hit_object->frac_aligned_hit();
1584
Purpose : Get the fraction of the hit (sbjct) sequence which has been aligned
1585
: across all HSPs (not including intervals between non-overlapping
1587
Example : $frac_alnq = $hit_object->frac_aligned_hit();
1588
Returns : Float (2-decimal precision, e.g., 0.75).
1591
Comments : If you need data for each HSP, use hsps() and then interate
1592
: through the HSP objects.
1593
: To compute the fraction aligned, the logical length of the sbjct
1594
: sequence is used, meaning that for TBLAST[NX] reports, the
1595
: full length of the sbjct sequence is converted into amino acids
1596
: by dividing by 3. This is necessary because of the way
1597
: the lengths of aligned sequences are computed.
1598
: This method requires that all HSPs be tiled. If they have not
1599
: already been tiled, they will be tiled first automatically.
1601
See Also : L<frac_aligned_query()|frac_aligned_query>, L<matches()|matches>, , L<logical_length()|logical_length>, L<length_aln()|length_aln>, L<Bio::Search::BlastUtils::tile_hsps()|Bio::Search::BlastUtils>
1605
#--------------------
1606
sub frac_aligned_hit {
1607
#--------------------
1610
Bio::Search::BlastUtils::tile_hsps($self) if not $self->{'_tile_hsps'};
1612
sprintf( "%.2f", $self->{'_length_aln_sbjct'}/$self->logical_length('sbjct'));
1616
## These methods are being maintained for backward compatibility.
1618
=head2 frac_aligned_sbjct
1620
Same as L<frac_aligned_hit()|frac_aligned_hit>
1625
sub frac_aligned_sbjct { my $self=shift; $self->frac_aligned_hit(@_); }
1628
=head2 num_unaligned_sbjct
1630
Same as L<num_unaligned_hit()|num_unaligned_hit>
1635
sub num_unaligned_sbjct { my $self=shift; $self->num_unaligned_hit(@_); }
1640
=head2 num_unaligned_hit
1642
Usage : $hit_object->num_unaligned_hit();
1643
Purpose : Get the number of the unaligned residues in the hit sequence.
1644
: Sums across all all HSPs.
1645
Example : $num_unaln = $hit_object->num_unaligned_hit();
1649
Comments : See notes regarding logical lengths in the comments for frac_aligned_hit().
1650
: They apply here as well.
1651
: If you need data for each HSP, use hsps() and then interate
1652
: through the HSP objects.
1653
: This method requires that all HSPs be tiled. If they have not
1654
: already been tiled, they will be tiled first automatically..
1656
See Also : L<num_unaligned_query()|num_unaligned_query>, L<Bio::Search::BlastUtils::tile_hsps()|Bio::Search::BlastUtils>, L<frac_aligned_hit()|frac_aligned_hit>
1660
#---------------------
1661
sub num_unaligned_hit {
1662
#---------------------
1665
Bio::Search::BlastUtils::tile_hsps($self) if not $self->{'_tile_hsps'};
1667
my $num = $self->logical_length('sbjct') - $self->{'_length_aln_sbjct'};
1668
($num < 0 ? 0 : $num );
1672
=head2 num_unaligned_query
1674
Usage : $hit_object->num_unaligned_query();
1675
Purpose : Get the number of the unaligned residues in the query sequence.
1676
: Sums across all all HSPs.
1677
Example : $num_unaln = $hit_object->num_unaligned_query();
1681
Comments : See notes regarding logical lengths in the comments for frac_aligned_query().
1682
: They apply here as well.
1683
: If you need data for each HSP, use hsps() and then interate
1684
: through the HSP objects.
1685
: This method requires that all HSPs be tiled. If they have not
1686
: already been tiled, they will be tiled first automatically..
1688
See Also : L<num_unaligned_hit()|num_unaligned_hit>, L<frac_aligned_query()|frac_aligned_query>, L<Bio::Search::BlastUtils::tile_hsps()|Bio::Search::BlastUtils>
1692
#-----------------------
1693
sub num_unaligned_query {
1694
#-----------------------
1697
Bio::Search::BlastUtils::tile_hsps($self) if not $self->{'_tile_hsps'};
1699
my $num = $self->logical_length('query') - $self->{'_length_aln_query'};
1700
($num < 0 ? 0 : $num );
1707
Usage : $hit->seq_inds( seq_type, class, collapse );
1708
Purpose : Get a list of residue positions (indices) across all HSPs
1709
: for identical or conserved residues in the query or sbjct sequence.
1710
Example : @s_ind = $hit->seq_inds('query', 'identical');
1711
: @h_ind = $hit->seq_inds('hit', 'conserved');
1712
: @h_ind = $hit->seq_inds('hit', 'conserved', 1);
1713
Returns : Array of integers
1714
: May include ranges if collapse is non-zero.
1715
Argument : [0] seq_type = 'query' or 'hit' or 'sbjct' (default = 'query')
1716
: ('sbjct' is synonymous with 'hit')
1717
: [1] class = 'identical' or 'conserved' (default = 'identical')
1718
: (can be shortened to 'id' or 'cons')
1719
: (actually, anything not 'id' will evaluate to 'conserved').
1720
: [2] collapse = boolean, if non-zero, consecutive positions are merged
1721
: using a range notation, e.g., "1 2 3 4 5 7 9 10 11"
1722
: collapses to "1-5 7 9-11". This is useful for
1723
: consolidating long lists. Default = no collapse.
1726
See Also : L<Bio::Search::HSP::BlastHSP::seq_inds()|Bio::Search::HSP::BlastHSP>
1733
my ($self, $seqType, $class, $collapse) = @_;
1735
$seqType ||= 'query';
1736
$class ||= 'identical';
1739
$seqType = 'sbjct' if $seqType eq 'hit';
1742
foreach $hsp ($self->hsps) {
1743
# This will merge data for all HSPs together.
1744
push @inds, $hsp->seq_inds($seqType, $class);
1747
# Need to remove duplicates and sort the merged positions.
1749
my %tmp = map { $_, 1 } @inds;
1750
@inds = sort {$a <=> $b} keys %tmp;
1753
$collapse ? &Bio::Search::BlastUtils::collapse_nums(@inds) : @inds;
101
my($class,@args) = @_;
103
my $self = $class->SUPER::new(@args);
104
my ($iter,$found) = $self->_rearrange([qw(ITERATION
108
defined $iter && $self->iteration($iter);
109
defined $found && $self->found_again($found);
1757
114
=head2 iteration
1759
Usage : $sbjct->iteration( );
116
Usage : $hit->iteration( $iteration_num );
1760
117
Purpose : Gets the iteration number in which the Hit was found.
1761
118
Example : $iteration_num = $sbjct->iteration();
1762
119
Returns : Integer greater than or equal to 1
1763
120
Non-PSI-BLAST reports will report iteration as 1, but this number
1764
121
is only meaningful for PSI-BLAST reports.
122
Argument : iteration_num (optional, used when setting only)
1768
125
See Also : L<found_again()|found_again>
1773
sub iteration { shift->{'_iteration'} }
130
my ($self,$value) = @_;
131
if( defined $value) {
132
$self->{'_psiblast_iteration'} = $value;
134
return $self->{'_psiblast_iteration'};
1777
137
=head2 found_again
1779
Usage : $sbjct->found_again;
140
Usage : $hit->found_again;
141
$hit->found_again(1);
1780
142
Purpose : Gets a boolean indicator whether or not the hit has
1781
143
been found in a previous iteration.
1782
144
This is only applicable to PSI-BLAST reports.
1784
This method indicates if the hit was reported in the
1785
"Sequences used in model and found again" section of the
1786
PSI-BLAST report or if it was reported in the
1787
"Sequences not found previously or not previously below threshold"
1788
section of the PSI-BLAST report. Only for hits in iteration > 1.
146
This method indicates if the hit was reported in the
147
"Sequences used in model and found again" section of the
148
PSI-BLAST report or if it was reported in the
149
"Sequences not found previously or not previously below threshold"
150
section of the PSI-BLAST report. Only for hits in iteration > 1.
1790
Example : if( $sbjct->found_again()) { ... };
1791
Returns : Boolean (1 or 0) for PSI-BLAST report iterations greater than 1.
1792
Returns undef for PSI-BLAST report iteration 1 and non PSI_BLAST
152
Example : if( $hit->found_again()) { ... };
153
Returns : Boolean, true (1) if the hit has been found in a
154
previous PSI-BLAST iteration.
155
Returns false (0 or undef) for hits that have not occurred in a
156
previous PSI-BLAST iteration.
157
Argument : Boolean (1 or 0). Only used for setting.
1797
See Also : L<found_again()|found_again>
1802
sub found_again { shift->{'_found_again'} }
1808
Usage : $sbjct->strand( [seq_type] );
1809
Purpose : Gets the strand(s) for the query, sbjct, or both sequences
1810
: in the BlastHit object.
1811
Example : $qstrand = $sbjct->strand('query');
1812
: $sstrand = $sbjct->strand('hit');
1813
: ($qstrand, $sstrand) = $sbjct->strand();
1814
Returns : scalar context: integer '1', '-1', or '-1/1'
1815
: if there are HSPs on both strands.
1816
: array context without args: list of two strings (queryStrand, sbjctStrand)
1817
: Array context can be "induced" by providing an argument of 'list' or 'array'.
1818
Argument : In scalar context: seq_type = 'query' or 'hit' or 'sbjct' (default = 'query')
1819
('sbjct' is synonymous with 'hit')
1822
See Also : B<Bio::Search::HSP::BlastHSP::strand>()
1829
my ($self, $seqType) = @_;
1831
$seqType ||= (wantarray ? 'list' : 'query');
1832
$seqType = 'sbjct' if $seqType eq 'hit';
1834
# If there is only one HSP, defer this call to the solitary HSP.
1835
if($self->num_hsps == 1) {
1836
return $self->hsp->strand($seqType);
1838
# otherwise, iterate through all HSPs collecting strand info.
1840
foreach my $hsp( $self->hsps ) {
1841
my ( $q, $h ) = $hsp->strand();
1845
my $qstr = join( '/', sort keys %qstr);
1846
my $hstr = join( '/', sort keys %hstr);
1847
if($seqType =~ /list|array/i) {
1848
return ($qstr, $hstr);
1849
} elsif( $seqType eq 'query' ) {
160
See Also : L<iteration()|iteration>
166
return $self->{'_found_again'} = shift if @_;
167
return $self->{'_found_again'};
1861
#####################################################################################
1863
#####################################################################################
1866
=head1 FOR DEVELOPERS ONLY
1870
Information about the various data members of this module is provided for those
1871
wishing to modify or understand the code. Two things to bear in mind:
1875
=item 1 Do NOT rely on these in any code outside of this module.
1877
All data members are prefixed with an underscore to signify that they are private.
1878
Always use accessor methods. If the accessor doesn't exist or is inadequate,
1879
create or modify an accessor (and let me know, too!). (An exception to this might
1880
be for BlastHSP.pm which is more tightly coupled to BlastHit.pm and
1881
may access BlastHit data members directly for efficiency purposes, but probably
1884
=item 2 This documentation may be incomplete and out of date.
1886
It is easy for these data member descriptions to become obsolete as
1887
this module is still evolving. Always double check this info and search
1888
for members not described here.
1892
An instance of Bio::Search::Hit::BlastHit.pm is a blessed reference to a hash containing
1893
all or some of the following fields:
1896
--------------------------------------------------------------
1897
_hsps : Array ref for a list of Bio::Search::HSP::BlastHSP.pm objects.
1899
_db : Database identifier from the summary line.
1901
_desc : Description data for the hit from the summary line.
1903
_length : Total length of the hit sequence.
1905
_score : BLAST score.
1907
_bits : BLAST score (in bits). Matrix-independent.
1909
_p : BLAST P value. Obtained from summary section. (Blast1/WU-Blast only)
1911
_expect : BLAST Expect value. Obtained from summary section.
1913
_n : BLAST N value (number of HSPs) (Blast1/WU-Blast2 only)
1915
_frame : Reading frame for TBLASTN and TBLASTX analyses.
1917
_totalIdentical: Total number of identical aligned monomers.
1919
_totalConserved: Total number of conserved aligned monomers (a.k.a. "positives").
1921
_overlap : Maximum number of overlapping residues between adjacent HSPs
1922
: before considering the alignment to be ambiguous.
1924
_ambiguous_aln : Boolean. True if the alignment of all HSPs is ambiguous.
1926
_length_aln_query : Length of the aligned region of the query sequence.
1928
_length_aln_sbjct : Length of the aligned region of the sbjct sequence.
171
sub expect { shift->significance(@_) }
added
removed
Bio/Search/Hit/BlastHit.pm
