Bio/SeqFeature/SimilarityPair.pm

   1 #
   2 # BioPerl module for Bio::SeqFeature::SimilarityPair
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Hilmar Lapp <hlapp@gmx.net>
   7 #
   8 # Copyright Hilmar Lapp
   9 #
  10 # You may distribute this module under the same terms as perl itself
  11
  12 # POD documentation - main docs before the code
  13
  14 =head1 NAME
  15
  16 Bio::SeqFeature::SimilarityPair - Sequence feature based on the similarity
  17                   of two sequences.
  18
  19 =head1 SYNOPSIS
  20
  21   $sim_pair = Bio::SeqFeature::SimilarityPair->from_searchResult($blastHit);
  22
  23   $sim = $sim_pair->query(); # a Bio::SeqFeature::Similarity object - the query
  24   $sim = $sim_pair->hit();   # dto - the hit.
  25
  26   # some properties for the similarity pair
  27   $expect = $sim_pair->significance();
  28   $score = $sim_pair->score();
  29   $bitscore = $sim_pair->bits();
  30
  31   # this will not write the description for the sequence (only its name)
  32   print $sim_pair->query()->gff_string(), "\n";
  33
  34 =head1 DESCRIPTION
  35
  36 Lightweight similarity search result as a pair of Similarity
  37 features. This class inherits off Bio::SeqFeature::FeaturePair and
  38 therefore implements Bio::SeqFeatureI, whereas the two features of the
  39 pair are descendants of Bio::SeqFeature::Generic, with better support
  40 for representing similarity search results in a cleaner way.
  41
  42 =head1 FEEDBACK
  43
  44 =head2 Mailing Lists
  45
  46 User feedback is an integral part of the evolution of this and other
  47 Bioperl modules. Send your comments and suggestions preferably to one
  48 of the Bioperl mailing lists.  Your participation is much appreciated.
  49
  50   bioperl-l@bioperl.org                  - General discussion
  51   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  52
  53 =head2 Support
  54
  55 Please direct usage questions or support issues to the mailing list:
  56
  57 I<bioperl-l@bioperl.org>
  58
  59 rather than to the module maintainer directly. Many experienced and
  60 reponsive experts will be able look at the problem and quickly
  61 address it. Please include a thorough description of the problem
  62 with code and data examples if at all possible.
  63
  64 =head2 Reporting Bugs
  65
  66 Report bugs to the Bioperl bug tracking system to help us keep track
  67 the bugs and their resolution.  Bug reports can be submitted via the
  68 web:
  69
  70   https://redmine.open-bio.org/projects/bioperl/
  71
  72 =head1 AUTHOR - Hilmar Lapp
  73
  74 Email hlapp@gmx.net or hilmar.lapp@pharma.novartis.com
  75
  76 =head1 APPENDIX
  77
  78 The rest of the documentation details each of the object
  79 methods. Internal methods are usually preceded with a _
  80
  81 =cut
  82
  83
  84 # Let the code begin...
  85
  86
  87 package Bio::SeqFeature::SimilarityPair;
  88 use strict;
  89
  90 use Bio::SeqFeature::Similarity;
  91 use Bio::Factory::ObjectFactory;
  92
  93 use base qw(Bio::SeqFeature::FeaturePair);
  94
  95 =head2 new
  96
  97  Title   : new
  98  Usage   : my $similarityPair = Bio::SeqFeature::SimilarityPair->new
  99                                  (-hit   => $hit,
 100                                   -query => $query,
 101                                   -source => 'blastp');
 102  Function: Initializes a new SimilarityPair object
 103  Returns : Bio::SeqFeature::SimilarityPair
 104  Args    : -query => The query in a Feature pair
 105            -hit   => (formerly '-subject') the subject/hit in a Feature pair
 106
 107
 108 =cut
 109
 110 sub new {
 111     my($class,@args) = @_;
 112
 113     if(! grep { lc($_) eq "-feature_factory"; } @args) {
 114         # if no overriding factory is provided, provide our preferred one
 115         my $fact = Bio::Factory::ObjectFactory->new(
 116                                     -type => "Bio::SeqFeature::Similarity",
 117                                     -interface => "Bio::SeqFeatureI");
 118         push(@args, '-feature_factory', $fact);
 119     }
 120     my $self = $class->SUPER::new(@args);
 121
 122     my ($primary, $hit, $query, $fea1, $source,$sbjct) =
 123         $self->_rearrange([qw(PRIMARY
 124                               HIT
 125                               QUERY
 126                               FEATURE1
 127                               SOURCE
 128                               SUBJECT
 129                               )],@args);
 130
 131     if( $sbjct ) {
 132         # undeprecated by Jason before 1.1 release
 133         # $self->deprecated("use of -subject deprecated: SimilarityPair now uses 'hit'");
 134         if(! $hit) { $hit = $sbjct }
 135         else {
 136             $self->warn("-hit and -subject were specified, using -hit and ignoring -subject");
 137         }
 138     }
 139
 140     # set the query and subject feature if provided
 141     $self->query( $query) if $query && ! $fea1;
 142     $hit && $self->hit($hit);
 143
 144     # the following refer to feature1, which is guaranteed to exist
 145     if( defined $primary || ! defined $self->primary_tag) {
 146         $primary = 'similarity' unless defined $primary;
 147         $self->primary_tag($primary);
 148     }
 149
 150     $source && $self->source_tag($source);
 151
 152     return $self;
 153 }
 154
 155 #
 156 # Everything else is just inherited from SeqFeature::FeaturePair.
 157 #
 158
 159 =head2 query
 160
 161  Title   : query
 162  Usage   : $query_feature = $obj->query();
 163            $obj->query($query_feature);
 164  Function: The query object for this similarity pair
 165  Returns : Bio::SeqFeature::Similarity
 166  Args    : [optional] Bio::SeqFeature::Similarity
 167
 168 See L<Bio::SeqFeature::Similarity>, L<Bio::SeqFeature::FeaturePair>
 169
 170 =cut
 171
 172 sub query {
 173     return shift->feature1(@_);
 174 }
 175
 176
 177
 178
 179 =head2 subject
 180
 181  Title   : subject
 182  Usage   : $sbjct_feature = $obj->subject();
 183            $obj->subject($sbjct_feature);
 184  Function: Get/Set Subject for a SimilarityPair
 185  Returns : Bio::SeqFeature::Similarity
 186  Args    : [optional] Bio::SeqFeature::Similarity
 187  Notes   : Deprecated.  Use the method 'hit' instead
 188
 189 =cut
 190
 191 sub subject {
 192     my $self = shift;
 193 #    $self->deprecated("Method subject deprecated: use hit() instead");
 194     $self->hit(@_);
 195 }
 196
 197 =head2 hit
 198
 199  Title   : hit
 200  Usage   : $sbjct_feature = $obj->hit();
 201            $obj->hit($sbjct_feature);
 202  Function: Get/Set Hit for a SimilarityPair
 203  Returns : Bio::SeqFeature::Similarity
 204  Args    : [optional] Bio::SeqFeature::Similarity
 205
 206
 207 =cut
 208
 209 sub hit {
 210     return shift->feature2(@_);
 211 }
 212
 213 =head2 source_tag
 214
 215  Title   : source_tag
 216  Usage   : $source = $obj->source_tag(); # i.e., program
 217            $obj->source_tag($evalue);
 218  Function: Gets the source tag (program name typically) for a feature
 219  Returns : string
 220  Args    : [optional] string
 221
 222
 223 =cut
 224
 225 sub source_tag {
 226     my ($self, @args) = @_;
 227
 228     if(@args) {
 229         $self->hit()->source_tag(@args);
 230     }
 231     return $self->query()->source_tag(@args);
 232 }
 233
 234 =head2 significance
 235
 236  Title   : significance
 237  Usage   : $evalue = $obj->significance();
 238            $obj->significance($evalue);
 239  Function:
 240  Returns :
 241  Args    :
 242
 243
 244 =cut
 245
 246 sub significance {
 247     my ($self, @args) = @_;
 248
 249     if(@args) {
 250         $self->hit()->significance(@args);
 251     }
 252     return $self->query()->significance(@args);
 253 }
 254
 255 =head2 score
 256
 257  Title   : score
 258  Usage   : $score = $obj->score();
 259            $obj->score($value);
 260  Function:
 261  Returns :
 262  Args    :
 263
 264
 265 =cut
 266
 267 sub score {
 268     my ($self, @args) = @_;
 269
 270     if(@args) {
 271         $self->hit()->score(@args);
 272     }
 273     # Note: You might think it's only getting set on the hit object.
 274     # Actually, it's getting set on both hit and query.
 275
 276     return $self->query()->score(@args);
 277 }
 278
 279 =head2 bits
 280
 281  Title   : bits
 282  Usage   : $bits = $obj->bits();
 283            $obj->bits($value);
 284  Function:
 285  Returns :
 286  Args    :
 287
 288
 289 =cut
 290
 291 sub bits {
 292     my ($self, @args) = @_;
 293
 294     if(@args) {
 295         $self->hit()->bits(@args);
 296     }
 297     return $self->query()->bits(@args);
 298 }
 299
 300 #################################################################
 301 # aliases for backwards compatibility or convenience            #
 302 #################################################################
 303
 304 *sbjct = \&subject;
 305
 306 1;