lib/Bio/SeqFeature/CollectionI.pm

   1 #
   2 # BioPerl module for Bio::SeqFeature::CollectionI
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Jason Stajich <jason@bioperl.org>
   7 #
   8 # Copyright Jason Stajich
   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::CollectionI - An interface for a collection of SeqFeatureI objects.
  17
  18 =head1 SYNOPSIS
  19
  20
  21 # get a Bio::SeqFeature::CollectionI somehow
  22 # perhaps a Bio::SeqFeature::Collection
  23
  24
  25     use Bio::SeqFeature::Collection;
  26     my $collection = Bio::SeqFeature::Collection->new();
  27     $collection->add_features(\@featurelist);
  28
  29
  30     $collection->features(-attributes =>
  31                           [ { 'location' => Bio::Location::Simple->new
  32                                   (-start=> 1, -end => 300) ,
  33                                   'overlaps' }]);
  34
  35 =head1 DESCRIPTION
  36
  37 This interface describes the basic methods needed for a collection of Sequence Features.
  38
  39 =head1 FEEDBACK
  40
  41 =head2 Mailing Lists
  42
  43 User feedback is an integral part of the evolution of this and other
  44 Bioperl modules. Send your comments and suggestions preferably to
  45 the Bioperl mailing list.  Your participation is much appreciated.
  46
  47   bioperl-l@bioperl.org                  - General discussion
  48   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  49
  50 =head2 Support
  51
  52 Please direct usage questions or support issues to the mailing list:
  53
  54 I<bioperl-l@bioperl.org>
  55
  56 rather than to the module maintainer directly. Many experienced and
  57 reponsive experts will be able look at the problem and quickly
  58 address it. Please include a thorough description of the problem
  59 with code and data examples if at all possible.
  60
  61 =head2 Reporting Bugs
  62
  63 Report bugs to the Bioperl bug tracking system to help us keep track
  64 of the bugs and their resolution. Bug reports can be submitted via the
  65 web:
  66
  67   https://github.com/bioperl/bioperl-live/issues
  68
  69 =head1 AUTHOR - Jason Stajich
  70
  71 Email jason@bioperl.org
  72
  73 =head1 APPENDIX
  74
  75 The rest of the documentation details each of the object methods.
  76 Internal methods are usually preceded with a _
  77
  78 =cut
  79
  80
  81 # Let the code begin...
  82
  83
  84 package Bio::SeqFeature::CollectionI;
  85 use strict;
  86 use Carp;
  87
  88 use base qw(Bio::Root::RootI);
  89
  90
  91 =head2 add_features
  92
  93  Title   : add_features
  94  Usage   : $collection->add_features(\@features);
  95  Function:
  96  Returns : number of features added
  97  Args    : arrayref of Bio::SeqFeatureI objects to index
  98
  99 =cut
 100
 101 sub add_features{
 102     shift->throw_not_implemented();
 103 }
 104
 105
 106 =head2 features
 107
 108  Title   : features
 109  Usage   : my @f = $collection->features(@args);
 110  Returns : a list of Bio::SeqFeatureI objects
 111  Args    : see below
 112  Status  : public
 113
 114 This routine will retrieve features associated with this collection
 115 object.  It can be used to return all features, or a subset based on
 116 their type, location, or attributes.
 117
 118   -types     List of feature types to return.  Argument is an array
 119              of Bio::Das::FeatureTypeI objects or a set of strings
 120              that can be converted into FeatureTypeI objects.
 121
 122   -callback   A callback to invoke on each feature.  The subroutine
 123               will be passed to each Bio::SeqFeatureI object in turn.
 124
 125   -attributes A hash reference containing attributes to match.
 126
 127 The -attributes argument is a hashref containing one or more attributes
 128 to match against:
 129
 130   -attributes => { Gene => 'abc-1',
 131                    Note => 'confirmed' }
 132
 133 Attribute matching is simple exact string matching, and multiple
 134 attributes are ANDed together.  See L<Bio::DB::ConstraintsI> for a
 135 more sophisticated take on this.
 136
 137 If one provides a callback, it will be invoked on each feature in
 138 turn.  If the callback returns a false value, iteration will be
 139 interrupted.  When a callback is provided, the method returns undef.
 140
 141 =cut
 142
 143 sub features{
 144     shift->throw_not_implemented();
 145 }
 146
 147 1;