lib/Bio/SeqI.pm

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