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 use strict;
 112
 113
 114 # Object preamble - inherits from Bio::PrimarySeqI
 115
 116 use base qw(Bio::PrimarySeqI Bio::AnnotatableI Bio::FeatureHolderI);
 117
 118 =head2 get_SeqFeatures
 119
 120  Title   : get_SeqFeatures
 121  Usage   : my @feats = $seq->get_SeqFeatures();
 122  Function: retrieve just the toplevel sequence features attached to this seq
 123  Returns : array of Bio::SeqFeatureI objects
 124  Args    : none
 125
 126 This method comes through extension of Bio::FeatureHolderI. See
 127 L<Bio::FeatureHolderI> and L<Bio::SeqFeatureI> for more information.
 128
 129 =head2 get_all_SeqFeatures
 130
 131  Title   : get_all_SeqFeatures
 132  Usage   : my @feats = $seq->get_all_SeqFeatures();
 133  Function: returns all SeqFeatures, including sub SeqFeatures
 134  Returns : an array of Bio::SeqFeatureI objects
 135  Args    : none
 136
 137 This method comes through extension of Bio::FeatureHolderI. See
 138 L<Bio::FeatureHolderI> and L<Bio::SeqFeatureI> for more information.
 139
 140 =head2 feature_count
 141
 142  Title   : feature_count
 143  Usage   : my $count = $seq->feature_count();
 144  Function: Return the number of SeqFeatures attached to a sequence
 145  Returns : integer representing the number of SeqFeatures
 146  Args    : none
 147
 148 This method comes through extension of Bio::FeatureHolderI. See
 149 L<Bio::FeatureHolderI> for more information.
 150
 151 =head2 seq
 152
 153  Title   : seq
 154  Usage   : my $string = $seq->seq();
 155  Function: Retrieves the sequence string for the sequence object
 156  Returns : string
 157  Args    : none
 158
 159
 160 =cut
 161
 162 sub seq {
 163    my ($self) = @_;
 164    $self->throw_not_implemented();
 165 }
 166
 167 =head2 write_GFF
 168
 169  Title   : write_GFF
 170  Usage   : $seq->write_GFF(\*FILEHANDLE);
 171  Function: Convenience method to write out all the sequence features
 172            in GFF format to the provided filehandle (STDOUT by default)
 173  Returns : none
 174  Args    : [optional] filehandle to write to (default is STDOUT)
 175
 176
 177 =cut
 178
 179 sub write_GFF {
 180    my ($self,$fh) = @_;
 181
 182    $fh || do { $fh = \*STDOUT; };
 183
 184    foreach my $sf ( $self->get_all_SeqFeatures() ) {
 185        print $fh $sf->gff_string, "\n";
 186    }
 187
 188 }
 189
 190 =head2 annotation
 191
 192  Title   : annotation
 193  Usage   : my $ann = $seq->annotation($seq_obj);
 194  Function: retrieve the attached annotation object
 195  Returns : Bio::AnnotationCollectionI or none;
 196
 197 See L<Bio::AnnotationCollectionI> and L<Bio::Annotation::Collection>
 198 for more information. This method comes through extension from
 199 L<Bio::AnnotatableI>.
 200
 201 =head2 species
 202
 203  Title   : species
 204  Usage   :
 205  Function: Gets or sets the species
 206  Example : my $species = $seq->species();
 207  Returns : Bio::Species object
 208  Args    : Bio::Species object or none;
 209
 210 See L<Bio::Species> for more information
 211
 212 =cut
 213
 214 sub species {
 215     my ($self) = @_;
 216     $self->throw_not_implemented();
 217 }
 218
 219 =head2 primary_seq
 220
 221  Title   : primary_seq
 222  Usage   : my $primaryseq = $seq->primary_seq($newval)
 223  Function: Retrieve the underlying Bio::PrimarySeqI object if available.
 224            This is in the event one has a sequence with lots of features
 225            but want to be able to narrow the object to just one with
 226            the basics of a sequence (no features or annotations).
 227  Returns : Bio::PrimarySeqI
 228  Args    : Bio::PrimarySeqI or none;
 229
 230 See L<Bio::PrimarySeqI> for more information
 231
 232 =cut
 233
 234 sub primary_seq {
 235     my ($self) = @_;
 236     $self->throw_not_implemented;
 237 }
 238
 239 1;