Bio/DB/SeqI.pm

   1
   2 #
   3 #
   4 # BioPerl module for Bio::DB::SeqI.pm
   5 #
   6 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   7 #
   8 # Cared for by Ewan Birney <birney@ebi.ac.uk>
   9 #
  10 # Copyright Ewan Birney
  11 #
  12 # You may distribute this module under the same terms as perl itself
  13
  14 # POD documentation - main docs before the code
  15
  16 =head1 NAME
  17
  18 Bio::DB::SeqI - Abstract Interface for Sequence databases
  19
  20 =head1 SYNOPSIS
  21
  22    # get a Bio::DB::SeqI somehow
  23
  24    $seq = $seqdb->get_Seq_by_id('some-id');
  25    $seq = $seqdb->get_Seq_by_acc('some-accession-number');
  26
  27    @ids = $seqdb->get_all_ids();
  28    $stream = $seqdb->get_PrimarySeq_stream();
  29    while((my $seq = $stream->next_seq()) {
  30       # $seq is a PrimarySeqI compliant object
  31    }
  32
  33
  34 =head1 DESCRIPTION
  35
  36 Abstract interface for a sequence database
  37
  38 =head1 FEEDBACK
  39
  40 =head2 Mailing Lists
  41
  42 User feedback is an integral part of the evolution of this and other
  43 Bioperl modules. Send your comments and suggestions preferably to one
  44 of the Bioperl mailing lists. Your participation is much appreciated.
  45
  46   bioperl-l@bioperl.org                  - General discussion
  47   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  48
  49 =head2 Support
  50
  51 Please direct usage questions or support issues to the mailing list:
  52
  53 I<bioperl-l@bioperl.org>
  54
  55 rather than to the module maintainer directly. Many experienced and
  56 reponsive experts will be able look at the problem and quickly
  57 address it. Please include a thorough description of the problem
  58 with code and data examples if at all possible.
  59
  60 =head2 Reporting Bugs
  61
  62 Report bugs to the Bioperl bug tracking system to help us keep track
  63 the bugs and their resolution.  Bug reports can be submitted via the
  64 web:
  65
  66   http://bugzilla.open-bio.org/
  67
  68 =head1 AUTHOR - Ewan Birney
  69
  70 Email birney@ebi.ac.uk
  71
  72 =head1 APPENDIX
  73
  74 The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
  75
  76 =cut
  77
  78
  79 # Let the code begin...
  80
  81
  82 package Bio::DB::SeqI;
  83 use strict;
  84
  85
  86 use base qw(Bio::DB::RandomAccessI);
  87
  88 =head1 Methods inherieted from Bio::DB::RandomAccessI
  89
  90 =head2 get_Seq_by_id
  91
  92  Title   : get_Seq_by_id
  93  Usage   : $seq = $db->get_Seq_by_id('ROA1_HUMAN')
  94  Function: Gets a Bio::Seq object by its name
  95  Returns : a Bio::Seq object
  96  Args    : the id (as a string) of a sequence
  97  Throws  : "id does not exist" exception
  98
  99
 100 =cut
 101
 102 =head2 get_Seq_by_acc
 103
 104  Title   : get_Seq_by_acc
 105  Usage   : $seq = $db->get_Seq_by_acc('X77802');
 106  Function: Gets a Bio::Seq object by accession number
 107  Returns : A Bio::Seq object
 108  Args    : accession number (as a string)
 109  Throws  : "acc does not exist" exception
 110
 111
 112 =cut
 113
 114 =head1 Methods [that were] specific for Bio::DB::SeqI
 115
 116 =head2 get_PrimarySeq_stream
 117
 118  Title   : get_PrimarySeq_stream
 119  Usage   : $stream = get_PrimarySeq_stream
 120  Function: Makes a Bio::SeqIO compliant object
 121            which provides a single method, next_seq
 122  Returns : Bio::SeqIO
 123  Args    : none
 124
 125 =cut
 126
 127 sub get_PrimarySeq_stream{
 128    my ($self,@args) = @_;
 129
 130    $self->throw("Object did not provide a PrimarySeq stream object");
 131 }
 132
 133 =head2 get_all_primary_ids
 134
 135  Title   : get_all_ids
 136  Usage   : @ids = $seqdb->get_all_primary_ids()
 137  Function: gives an array of all the primary_ids of the
 138            sequence objects in the database. These
 139            maybe ids (display style) or accession numbers
 140            or something else completely different - they
 141            *are not* meaningful outside of this database
 142            implementation.
 143  Example :
 144  Returns : an array of strings
 145  Args    : none
 146
 147
 148 =cut
 149
 150 sub get_all_primary_ids{
 151    my ($self,@args) = @_;
 152    $self->throw("Object did not provide a get_all_ids method");
 153 }
 154
 155
 156 =head2 get_Seq_by_primary_id
 157
 158  Title   : get_Seq_by_primary_id
 159  Usage   : $seq = $db->get_Seq_by_primary_id($primary_id_string);
 160  Function: Gets a Bio::Seq object by the primary id. The primary
 161            id in these cases has to come from $db->get_all_primary_ids.
 162            There is no other way to get (or guess) the primary_ids
 163            in a database.
 164
 165            The other possibility is to get Bio::PrimarySeqI objects
 166            via the get_PrimarySeq_stream and the primary_id field
 167            on these objects are specified as the ids to use here.
 168  Returns : A Bio::Seq object
 169  Args    : accession number (as a string)
 170  Throws  : "acc does not exist" exception
 171
 172
 173 =cut
 174
 175 sub get_Seq_by_primary_id {
 176    my ($self,@args) = @_;
 177
 178    $self->throw("Abstract database call of get_Seq_by_primary_id. Your database has not implemented this method!");
 179
 180 }
 181
 182 1;
 183
 184
 185