Bio/SeqI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::SeqI
   4 #
   5 # Cared for by Ewan Birney <birney@ebi.ac.uk>
   6 #
   7 # Copyright Ewan Birney
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10
  11 # POD documentation - main docs before the code
  12
  13 =head1 NAME
  14
  15 Bio::SeqI [Developers] - Abstract Interface of Sequence (with features)
  16
  17 =head1 SYNOPSIS
  18
  19     # Bio::SeqI is the interface class for sequences.
  20
  21     # If you are a newcomer to bioperl, you should
  22     # start with Bio::Seq documentation. This
  23     # documentation is mainly for developers using
  24     # Bioperl.
  25
  26     # Bio::SeqI implements Bio::PrimarySeqI
  27     $seq      = $seqobj->seq(); # actual sequence as a string
  28     $seqstr   = $seqobj->subseq(10,50);
  29
  30     # Bio::SeqI has annotationcollections
  31
  32     $ann      = $seqobj->annotation(); # annotation object
  33
  34     # Bio::SeqI has sequence features
  35     # features must implement Bio::SeqFeatureI
  36
  37     @features = $seqobj->get_SeqFeatures(); # just top level
  38     @features = $seqobj->get_all_SeqFeatures(); # descend into sub features
  39
  40
  41
  42 =head1 DESCRIPTION
  43
  44 Bio::SeqI is the abstract interface of annotated Sequences. These
  45 methods are those which you can be guarenteed to get for any Bio::SeqI
  46 - for most users of the package the documentation (and methods) in
  47 this class are not at useful - this is a developers only class which
  48 defines what methods have to be implmented by other Perl objects to
  49 comply to the Bio::SeqI interface. Go "perldoc Bio::Seq" or "man
  50 Bio::Seq" for more information.
  51
  52
  53 There aren't many here, because too many complicated functions here
  54 prevent implementations which are just wrappers around a database or
  55 similar delayed mechanisms.
  56
  57 Most of the clever stuff happens inside the SeqFeatureI system.
  58
  59 A good reference implementation is Bio::Seq which is a pure perl
  60 implementation of this class with alot of extra pieces for extra
  61 manipulation.  However, if you want to be able to use any sequence
  62 object in your analysis, if you can do it just using these methods,
  63 then you know you will be future proof and compatible with other
  64 implementations of Seq.
  65
  66 =head1 FEEDBACK
  67
  68 =head2 Mailing Lists
  69
  70 User feedback is an integral part of the evolution of this and other
  71 Bioperl modules. Send your comments and suggestions preferably to one
  72 of the Bioperl mailing lists.  Your participation is much appreciated.
  73
  74   bioperl-l@bioperl.org                  - General discussion
  75   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  76
  77 =head2 Reporting Bugs
  78
  79 Report bugs to the Bioperl bug tracking system to help us keep track
  80 the bugs and their resolution.  Bug reports can be submitted via the
  81 web:
  82
  83   http://bugzilla.open-bio.org/
  84
  85 =head1 AUTHOR - Ewan Birney
  86
  87 Email birney@ebi.ac.uk
  88
  89
  90 =head1 APPENDIX
  91
  92 The rest of the documentation details each of the object
  93 methods. Internal methods are usually preceded with a _
  94
  95 =cut
  96
  97 #'
  98 # Let the code begin...
  99
 100
 101 package Bio::SeqI;
 102 use strict;
 103
 104
 105 # Object preamble - inheriets from Bio::PrimarySeqI
 106
 107 use base qw(Bio::PrimarySeqI Bio::AnnotatableI Bio::FeatureHolderI);
 108
 109 =head2 get_SeqFeatures
 110
 111  Title   : get_SeqFeatures
 112  Usage   : my @feats = $seq->get_SeqFeatures();
 113  Function: retrieve just the toplevel sequence features attached to this seq
 114  Returns : array of Bio::SeqFeatureI objects
 115  Args    : none
 116
 117 This method comes through extension of Bio::FeatureHolderI. See
 118 L<Bio::FeatureHolderI> and L<Bio::SeqFeatureI> for more information.
 119
 120 =cut
 121
 122 =head2 get_all_SeqFeatures
 123
 124  Title   : get_all_SeqFeatures
 125  Usage   : @features = $annseq->get_all_SeqFeatures()
 126  Function: returns all SeqFeatures, included sub SeqFeatures
 127  Returns : an array of Bio::SeqFeatureI objects
 128  Args    : none
 129
 130 This method comes through extension of Bio::FeatureHolderI. See
 131 L<Bio::FeatureHolderI> and L<Bio::SeqFeatureI> for more information.
 132
 133 =cut
 134
 135 =head2 feature_count
 136
 137  Title   : feature_count
 138  Usage   : $seq->feature_count()
 139  Function: Return the number of SeqFeatures attached to a sequence
 140  Returns : integer representing the number of SeqFeatures
 141  Args    : none
 142
 143 This method comes through extension of Bio::FeatureHolderI. See
 144 L<Bio::FeatureHolderI> for more information.
 145
 146 =cut
 147
 148 =head2 seq
 149
 150  Title   : seq
 151  Usage   : my $string = $seq->seq();
 152  Function: Retrieves the sequence string for the sequence object
 153  Returns : string
 154  Args    : none
 155
 156
 157 =cut
 158
 159 sub seq{
 160    my ($self) = @_;
 161    $self->throw_not_implemented();
 162 }
 163
 164 =head2 write_GFF
 165
 166  Title   : write_GFF
 167  Usage   : $seq->write_GFF(\*FILEHANDLE);
 168  Function: Convience method to write out all the sequence features
 169            in GFF format to the provided filehandle (STDOUT by default)
 170  Returns : none
 171  Args    : [optional] filehandle to write to (default is STDOUT)
 172
 173
 174 =cut
 175
 176 sub write_GFF{
 177    my ($self,$fh) = @_;
 178
 179    $fh || do { $fh = \*STDOUT; };
 180
 181    foreach my $sf ( $self->get_all_SeqFeatures() ) {
 182        print $fh $sf->gff_string, "\n";
 183    }
 184
 185 }
 186
 187 =head2 annotation
 188
 189  Title   : annotation
 190  Usage   : $obj->annotation($seq_obj)
 191  Function: retrieve the attached annotation object
 192  Returns : Bio::AnnotationCollectionI or none;
 193
 194 See L<Bio::AnnotationCollectionI> and L<Bio::Annotation::Collection>
 195 for more information. This method comes through extension from
 196 L<Bio::AnnotatableI>.
 197
 198 =cut
 199
 200 =head2 species
 201
 202  Title   : species
 203  Usage   :
 204  Function: Gets or sets the species
 205  Example : $species = $self->species();
 206  Returns : Bio::Species object
 207  Args    : Bio::Species object or none;
 208
 209 See L<Bio::Species> for more information
 210
 211 =cut
 212
 213 sub species {
 214     my ($self) = @_;
 215     $self->throw_not_implemented();
 216 }
 217
 218 =head2 primary_seq
 219
 220  Title   : primary_seq
 221  Usage   : $obj->primary_seq($newval)
 222  Function: Retrieve the underlying Bio::PrimarySeqI object if available.
 223            This is in the event one has a sequence with lots of features
 224            but want to be able to narrow the object to just one with
 225            the basics of a sequence (no features or annotations).
 226  Returns : Bio::PrimarySeqI
 227  Args    : Bio::PrimarySeqI or none;
 228
 229 See L<Bio::PrimarySeqI> for more information
 230
 231 =cut
 232
 233 sub primary_seq {
 234     my ($self) = @_;
 235     $self->throw_not_implemented;
 236 }
 237
 238 1;