lib/Bio/FeatureHolderI.pm

   1 #
   2 # BioPerl module for Bio::FeatureHolderI
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Hilmar Lapp <hlapp at 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::FeatureHolderI - the base interface an object with features must implement
  17
  18 =head1 SYNOPSIS
  19
  20     use Bio::SeqIO;
  21     # get a feature-holding object somehow: for example, Bio::SeqI objects
  22     # have features
  23     my $seqio = Bio::SeqIO->new(-fh => \*STDIN, -format => 'genbank');
  24     while (my $seq = $seqio->next_seq()) {
  25         # $seq is-a Bio::FeatureHolderI, hence:
  26         my @feas = $seq->get_SeqFeatures();
  27         # each element is-a Bio::SeqFeatureI
  28         foreach my $fea (@feas) {
  29             # do something with the feature objects
  30         }
  31     }
  32
  33 =head1 DESCRIPTION
  34
  35 This is the base interface that all feature-holding objects must
  36 implement.
  37
  38 Popular feature-holders are for instance L<Bio::Seq> objects. Since
  39 L<Bio::SeqFeatureI> defines a sub_SeqFeature() method, most
  40 Bio::SeqFeatureI implementations like L<Bio::SeqFeature::Generic> will
  41 implement the feature holder interface as well.
  42
  43 =head1 FEEDBACK
  44
  45 =head2 Mailing Lists
  46
  47 User feedback is an integral part of the evolution of this and other
  48 Bioperl modules. Send your comments and suggestions preferably to
  49 the Bioperl mailing list.  Your participation is much appreciated.
  50
  51   bioperl-l@bioperl.org                  - General discussion
  52   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  53
  54 =head2 Support
  55
  56 Please direct usage questions or support issues to the mailing list:
  57
  58 I<bioperl-l@bioperl.org>
  59
  60 rather than to the module maintainer directly. Many experienced and
  61 reponsive experts will be able look at the problem and quickly
  62 address it. Please include a thorough description of the problem
  63 with code and data examples if at all possible.
  64
  65 =head2 Reporting Bugs
  66
  67 Report bugs to the Bioperl bug tracking system to help us keep track
  68 of the bugs and their resolution. Bug reports can be submitted via the
  69 web:
  70
  71   https://github.com/bioperl/bioperl-live/issues
  72
  73 =head1 AUTHOR - Hilmar Lapp
  74
  75 Email hlapp at gmx.net
  76
  77 =head1 CONTRIBUTORS
  78
  79 Steffen Grossmann [SG], grossman-at-molgen.mpg.de
  80 Mark A. Jensen, maj -at- fortinbras -dot- us
  81
  82 =head1 APPENDIX
  83
  84 The rest of the documentation details each of the object methods.
  85 Internal methods are usually preceded with a _
  86
  87 =cut
  88
  89
  90 # Let the code begin...
  91
  92
  93
  94 package Bio::FeatureHolderI;
  95
  96 use strict;
  97 use Carp;
  98
  99 use base qw(Bio::Root::RootI);
 100
 101 =head2 get_SeqFeatures()
 102
 103  Usage   : @feats = $obj->get_SeqFeatures()
 104  Function: Get the feature objects held by this feature holder.
 105  Example :
 106  Returns : an array of Bio::SeqFeatureI implementing objects
 107            if tag specified, return features having that tag
 108  Args    : [optional] scalar string (feature tag)
 109
 110 =cut
 111
 112 sub get_SeqFeatures {
 113   shift->throw_not_implemented();
 114 }
 115
 116 =head2 add_SeqFeature()
 117
 118  Usage   : $feat->add_SeqFeature($subfeat);
 119            $feat->add_SeqFeature($subfeat,'EXPAND')
 120  Function: Add a SeqFeature into the subSeqFeature array.
 121            with no 'EXPAND' qualifer, subfeat will be tested
 122            as to whether it lies inside the parent, and throw
 123            an exception if not.
 124
 125            If EXPAND is used and the object implements Bio::RangeI
 126            (which is not guaranteed), the parent''s start/end/strand
 127            will be extended so that the new subFeature can be accomodated.
 128  Example :
 129  Returns : nothing
 130  Args    : a Bio::SeqFeatureI object
 131
 132 =cut
 133
 134 sub add_SeqFeature {
 135   shift->throw_not_implemented();
 136 }
 137
 138
 139 =head2 remove_SeqFeatures()
 140
 141  Usage   : $obj->remove_SeqFeatures
 142  Function: Removes all sub SeqFeatures.  If you want to remove only a subset,
 143            remove that subset from the returned array, and add back the rest.
 144  Returns : The array of Bio::SeqFeatureI implementing sub-features that was
 145            deleted from this feature.
 146  Args    : none
 147
 148 =cut
 149
 150 sub remove_SeqFeatures {
 151   shift->throw_not_implemented();
 152 }
 153
 154 =head2 feature_count
 155
 156  Title   : feature_count
 157  Usage   : $obj->feature_count()
 158  Function: Return the number of SeqFeatures attached to a feature holder.
 159
 160            This is before flattening a possible sub-feature tree.
 161
 162            We provide a default implementation here that just counts
 163            the number of objects returned by get_SeqFeatures().
 164            Implementors may want to override this with a more
 165            efficient implementation.
 166
 167  Returns : integer representing the number of SeqFeatures
 168  Args    : None
 169
 170 At some day we may want to expand this method to allow for a feature
 171 filter to be passed in.
 172
 173 Our default implementation allows for any number of additional
 174 arguments and will pass them on to get_SeqFeatures(). I.e., in order to
 175 support filter arguments, just support them in get_SeqFeatures().
 176
 177 =cut
 178
 179 sub feature_count {
 180     return scalar(shift->get_SeqFeatures(@_));
 181 }
 182
 183 =head2 get_all_SeqFeatures
 184
 185  Title   : get_all_SeqFeatures
 186  Usage   :
 187  Function: Get the flattened tree of feature objects held by this
 188            feature holder. The difference to get_SeqFeatures is that
 189            the entire tree of sub-features will be flattened out.
 190
 191            We provide a default implementation here, so implementors
 192            don''t necessarily need to implement this method.
 193
 194  Example :
 195  Returns : an array of Bio::SeqFeatureI implementing objects
 196  Args    : none
 197
 198 At some day we may want to expand this method to allow for a feature
 199 filter to be passed in.
 200
 201 Our default implementation allows for any number of additional
 202 arguments and will pass them on to any invocation of
 203 get_SeqFeatures(), wherever a component of the tree implements
 204 FeatureHolderI. I.e., in order to support filter arguments, just
 205 support them in get_SeqFeatures().
 206
 207 =cut
 208
 209 sub get_all_SeqFeatures{
 210     my $self = shift;
 211     my @flatarr;
 212
 213     foreach my $feat ( $self->get_SeqFeatures(@_) ){
 214         push(@flatarr,$feat);
 215         &_add_flattened_SeqFeatures(\@flatarr,$feat,@_);
 216     }
 217
 218     # needed to deal with subfeatures which appear more than once in the hierarchy [SG]
 219     my %seen = ();
 220     my @uniq_flatarr = ();
 221     foreach my $feat (@flatarr) {
 222         push(@uniq_flatarr, $feat) unless $seen{$feat}++;
 223     }
 224     return @uniq_flatarr;
 225 }
 226
 227 sub _add_flattened_SeqFeatures {
 228     my ($arrayref,$feat,@args) = @_;
 229     my @subs = ();
 230
 231     if($feat->isa("Bio::FeatureHolderI")) {
 232         @subs = $feat->get_SeqFeatures(@args);
 233     } elsif($feat->isa("Bio::SeqFeatureI")) {
 234         @subs = $feat->sub_SeqFeature();
 235     } else {
 236         confess ref($feat)." is neither a FeatureHolderI nor a SeqFeatureI. ".
 237             "Don't know how to flatten.";
 238     }
 239     foreach my $sub (@subs) {
 240         push(@$arrayref,$sub);
 241         &_add_flattened_SeqFeatures($arrayref,$sub);
 242     }
 243
 244 }
 245
 246 sub set_ParentIDs_from_hierarchy(){
 247     # DEPRECATED - use IDHandler
 248     my $self = shift;
 249     require "Bio/SeqFeature/Tools/IDHandler.pm";
 250     Bio::SeqFeature::Tools::IDHandler->new->set_ParentIDs_from_hierarchy($self);
 251 }
 252
 253 sub create_hierarchy_from_ParentIDs(){
 254     # DEPRECATED - use IDHandler
 255     my $self = shift;
 256     require "Bio/SeqFeature/Tools/IDHandler.pm";
 257     Bio::SeqFeature::Tools::IDHandler->new->create_hierarchy_from_ParentIDs($self);
 258 }
 259
 260
 261
 262 1;