Bio/Location/SplitLocationI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Location::SplitLocationI
   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 # POD documentation - main docs before the code
  12
  13 =head1 NAME
  14
  15 Bio::Location::SplitLocationI - Abstract interface of a Location on a Sequence
  16 which has multiple locations (start/end points)
  17
  18 =head1 SYNOPSIS
  19
  20   # get a SplitLocationI somehow
  21     print $splitlocation->start, "..", $splitlocation->end, "\n";
  22     my @sublocs = $splitlocation->sub_Location();
  23
  24     my $count = 1;
  25     # print the start/end points of the sub locations
  26     foreach my $location ( sort { $a->start <=> $b->start }  @sublocs ) {
  27                 printf "sub feature %d [%d..%d]\n", $location->start,$location->end;
  28         $count++;
  29     }
  30
  31 =head1 DESCRIPTION
  32
  33 This interface encapsulates the necessary methods for representing the
  34 location of a sequence feature that has more that just a single
  35 start/end pair.  Some examples of this are the annotated exons in a
  36 gene or the annotated CDS in a sequence file.
  37
  38 =head1 FEEDBACK
  39
  40 User feedback is an integral part of the evolution of this and other
  41 Bioperl modules. Send your comments and suggestions preferably to one
  42 of the Bioperl mailing lists.  Your participation is much appreciated.
  43
  44   bioperl-l@bioperl.org                  - General discussion
  45   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  46
  47 =head2 Support
  48
  49 Please direct usage questions or support issues to the mailing list:
  50
  51 I<bioperl-l@bioperl.org>
  52
  53 rather than to the module maintainer directly. Many experienced and
  54 reponsive experts will be able look at the problem and quickly
  55 address it. Please include a thorough description of the problem
  56 with code and data examples if at all possible.
  57
  58 =head2 Reporting Bugs
  59
  60 Report bugs to the Bioperl bug tracking system to help us keep track
  61 the bugs and their resolution.  Bug reports can be submitted via the
  62 web:
  63
  64   http://bugzilla.open-bio.org/
  65
  66 =head1 AUTHOR - Jason Stajich
  67
  68 Email jason-at-bioperl-dot-org
  69
  70 =head1 APPENDIX
  71
  72 The rest of the documentation details each of the object
  73 methods. Internal methods are usually preceded with a _
  74
  75 =cut
  76
  77 # Let the code begin...
  78
  79
  80 package Bio::Location::SplitLocationI;
  81 use strict;
  82
  83 use Carp;
  84
  85 use base qw(Bio::LocationI);
  86
  87
  88 =head2 sub_Location
  89
  90  Title   : sub_Location
  91  Usage   : @locations = $feat->sub_Location();
  92  Function: Returns an array of LocationI objects
  93  Returns : An array
  94  Args    : none
  95
  96 =cut
  97
  98 sub sub_Location {
  99     my ($self,@args) = @_;
 100     $self->throw_not_implemented();
 101 }
 102
 103 =head2 splittype
 104
 105   Title   : splittype
 106   Usage   : $splittype = $fuzzy->splittype();
 107   Function: get/set the split splittype
 108   Returns : the splittype of split feature (join, order)
 109   Args    : splittype to set
 110
 111 =cut
 112
 113 sub splittype {
 114     my($self) = @_;
 115     $self->throw_not_implemented();
 116 }
 117
 118
 119 =head2 is_single_sequence
 120
 121   Title   : is_single_sequence
 122   Usage   : if($splitloc->is_single_sequence()) {
 123                 print "Location object $splitloc is split ".
 124                       "but only across a single sequence\n";
 125             }
 126   Function: Determine whether this location is split across a single or
 127             multiple sequences.
 128   Returns : TRUE if all sublocations lie on the same sequence as the root
 129             location (feature), and FALSE otherwise.
 130   Args    : none
 131
 132 =cut
 133
 134 sub is_single_sequence {
 135     my ($self) = @_;
 136     $self->throw_not_implemented();
 137 }
 138
 139 =head1 Bio::LocationI methods
 140
 141 Bio::LocationI inherited methods follow
 142
 143 =head2 min_start
 144
 145   Title   : min_start
 146   Usage   : my $minstart = $location->min_start();
 147   Function: Get minimum starting location of feature startpoint
 148   Returns : integer or undef if no maximum starting point.
 149   Args    : none
 150
 151 =cut
 152
 153 =head2 max_start
 154
 155   Title   : max_start
 156   Usage   : my $maxstart = $location->max_start();
 157   Function: Get maximum starting location of feature startpoint
 158   Returns : integer or undef if no maximum starting point.
 159   Args    : none
 160
 161 =cut
 162
 163 =head2 start_pos_type
 164
 165   Title   : start_pos_type
 166   Usage   : my $start_pos_type = $location->start_pos_type();
 167   Function: Get start position type (ie <,>, ^)
 168   Returns : type of position coded as text
 169             ('BEFORE', 'AFTER', 'EXACT','WITHIN', 'BETWEEN')
 170   Args    : none
 171
 172 =cut
 173
 174 =head2 min_end
 175
 176   Title   : min_end
 177   Usage   : my $minend = $location->min_end();
 178   Function: Get minimum ending location of feature endpoint
 179   Returns : integer or undef if no minimum ending point.
 180   Args    : none
 181
 182 =cut
 183
 184 =head2 max_end
 185
 186   Title   : max_end
 187   Usage   : my $maxend = $location->max_end();
 188   Function: Get maximum ending location of feature endpoint
 189   Returns : integer or undef if no maximum ending point.
 190   Args    : none
 191
 192 =cut
 193
 194 =head2 end_pos_type
 195
 196   Title   : end_pos_type
 197   Usage   : my $end_pos_type = $location->end_pos_type();
 198   Function: Get end position type (ie <,>, ^)
 199   Returns : type of position coded as text
 200             ('BEFORE', 'AFTER', 'EXACT','WITHIN', 'BETWEEN')
 201   Args    : none
 202
 203 =cut
 204
 205 =head2 seq_id
 206
 207   Title   : seq_id
 208   Usage   : my $seqid = $location->seq_id();
 209   Function: Get/Set seq_id that location refers to
 210   Returns : seq_id
 211   Args    : [optional] seq_id value to set
 212
 213 =cut
 214
 215 =head2 coordinate_policy
 216
 217   Title   : coordinate_policy
 218   Usage   : $policy = $location->coordinate_policy();
 219             $location->coordinate_policy($mypolicy); # set may not be possible
 220   Function: Get the coordinate computing policy employed by this object.
 221
 222             See Bio::Location::CoordinatePolicyI for documentation about
 223             the policy object and its use.
 224
 225             The interface *does not* require implementing classes to accept
 226             setting of a different policy. The implementation provided here
 227             does, however, allow to do so.
 228
 229             Implementors of this interface are expected to initialize every
 230             new instance with a CoordinatePolicyI object. The implementation
 231             provided here will return a default policy object if none has
 232             been set yet. To change this default policy object call this
 233             method as a class method with an appropriate argument. Note that
 234             in this case only subsequently created Location objects will be
 235             affected.
 236
 237   Returns : A Bio::Location::CoordinatePolicyI implementing object.
 238   Args    : On set, a Bio::Location::CoordinatePolicyI implementing object.
 239
 240 =cut
 241
 242 =head2 to_FTstring
 243
 244   Title   : to_FTstring
 245   Usage   : my $locstr = $location->to_FTstring()
 246   Function: returns the FeatureTable string of this location
 247   Returns : string
 248   Args    : none
 249
 250 =cut
 251
 252 1;
 253