Bio/LocationI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::LocationI
   4 # Cared for by Jason Stajich <jason@bioperl.org>
   5 #
   6 # Copyright Jason Stajich
   7 #
   8 # You may distribute this module under the same terms as perl itself
   9 # POD documentation - main docs before the code
  10
  11 =head1 NAME
  12
  13 Bio::LocationI - Abstract interface of a Location on a Sequence
  14
  15 =head1 SYNOPSIS
  16
  17     # get a LocationI somehow
  18     printf( "start = %d, end = %d, strand = %s, seq_id = %s\n",
  19             $location->start, $location->end, $location->strand,
  20             $location->seq_id);
  21     print "location str is ", $location->to_FTstring(), "\n";
  22
  23
  24 =head1 DESCRIPTION
  25
  26 This Interface defines the methods for a Bio::LocationI, an object
  27 which encapsulates a location on a biological sequence.  Locations
  28 need not be attached to actual sequences as they are stand alone
  29 objects.  LocationI objects are used by L<Bio::SeqFeatureI> objects to
  30 manage and represent locations for a Sequence Feature.
  31
  32 =head1 FEEDBACK
  33
  34 User feedback is an integral part of the evolution of this and other
  35 Bioperl modules. Send your comments and suggestions preferably to one
  36 of the Bioperl mailing lists.  Your participation is much appreciated.
  37
  38   bioperl-l@bioperl.org                  - General discussion
  39   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  40
  41 =head2 Reporting Bugs
  42
  43 Report bugs to the Bioperl bug tracking system to help us keep track
  44 the bugs and their resolution.  Bug reports can be submitted via the
  45 web:
  46
  47   http://bugzilla.open-bio.org/
  48
  49 =head1 AUTHOR - Jason Stajich
  50
  51 Email jason-at-bioperl-dot-org
  52
  53 =head1 APPENDIX
  54
  55 The rest of the documentation details each of the object
  56 methods. Internal methods are usually preceded with a _
  57
  58 =cut
  59
  60 # Let the code begin...
  61
  62 package Bio::LocationI;
  63 use strict;
  64
  65 use Carp;
  66
  67 use base qw(Bio::RangeI);
  68
  69 =head2 location_type
  70
  71   Title   : location_type
  72   Usage   : my $location_type = $location->location_type();
  73   Function: Get location type encoded as text
  74   Returns : string ('EXACT', 'WITHIN', 'IN-BETWEEN')
  75   Args    : none
  76
  77 =cut
  78
  79 sub location_type {
  80     my ($self,@args) = @_;
  81     $self->throw_not_implemented();
  82 }
  83
  84 =head2 start
  85
  86   Title   : start
  87   Usage   : $start = $location->start();
  88   Function: Get the start coordinate of this location as defined by
  89             the currently active coordinate computation policy. In
  90             simple cases, this will return the same number as
  91             min_start() and max_start(), in more ambiguous cases like
  92             fuzzy locations the number may be equal to one or neither
  93             of both.
  94
  95             We override this here from RangeI in order to delegate
  96             'get' to a L<Bio::Location::CoordinatePolicy> implementing
  97             object.  Implementing classes may also wish to provide
  98             'set' functionality, in which case they *must* override
  99             this method. The implementation provided here will throw
 100             an exception if called with arguments.
 101
 102   Returns : A positive integer value.
 103   Args    : none
 104
 105 See L<Bio::Location::CoordinatePolicy> for more information
 106
 107 =cut
 108
 109 sub start {
 110     my ($self,@args) = @_;
 111
 112     # throw if @args means that we don't support updating information
 113     # in the interface but will delegate to the coordinate policy object
 114     # for interpreting the 'start' value
 115
 116     $self->throw_not_implemented if @args;
 117     return $self->coordinate_policy()->start($self);
 118 }
 119
 120 =head2 end
 121
 122   Title   : end
 123   Usage   : $end = $location->end();
 124   Function: Get the end coordinate of this location as defined by the
 125             currently active coordinate computation policy. In simple
 126             cases, this will return the same number as min_end() and
 127             max_end(), in more ambiguous cases like fuzzy locations
 128             the number may be equal to one or neither of both.
 129
 130             We override this here from Bio::RangeI in order to delegate
 131             'get' to a L<Bio::Location::CoordinatePolicy> implementing
 132             object. Implementing classes may also wish to provide
 133             'set' functionality, in which case they *must* override
 134             this method. The implementation provided here will throw
 135             an exception if called with arguments.
 136
 137   Returns : A positive integer value.
 138   Args    : none
 139
 140 See L<Bio::Location::CoordinatePolicy> and L<Bio::RangeI> for more
 141 information
 142
 143 =cut
 144
 145 sub end {
 146     my ($self,@args) = @_;
 147
 148     # throw if @args means that we don't support updating information
 149     # in the interface but will delegate to the coordinate policy object
 150     # for interpreting the 'end' value
 151     $self->throw_not_implemented if @args;
 152     return $self->coordinate_policy()->end($self);
 153 }
 154
 155 =head2 min_start
 156
 157   Title   : min_start
 158   Usage   : my $minstart = $location->min_start();
 159   Function: Get minimum starting point of feature.
 160
 161             Note that an implementation must not call start() in this method.
 162
 163   Returns : integer or undef if no minimum starting point.
 164   Args    : none
 165
 166 =cut
 167
 168 sub min_start {
 169     my($self) = @_;
 170     $self->throw_not_implemented();
 171 }
 172
 173 =head2 max_start
 174
 175   Title   : max_start
 176   Usage   : my $maxstart = $location->max_start();
 177   Function: Get maximum starting point of feature.
 178
 179             Note that an implementation must not call start() in this method
 180             unless start() is overridden such as not to delegate to the
 181             coordinate computation policy object.
 182
 183   Returns : integer or undef if no maximum starting point.
 184   Args    : none
 185
 186 =cut
 187
 188 sub max_start {
 189     my($self) = @_;
 190     $self->throw_not_implemented();
 191 }
 192
 193 =head2 start_pos_type
 194
 195   Title   : start_pos_type
 196   Usage   : my $start_pos_type = $location->start_pos_type();
 197   Function: Get start position type encoded as text
 198
 199             Known valid values are 'BEFORE' (<5..100), 'AFTER' (>5..100),
 200             'EXACT' (5..100), 'WITHIN' ((5.10)..100), 'BETWEEN', (5^6), with
 201             their meaning best explained by their GenBank/EMBL location string
 202             encoding in brackets.
 203
 204   Returns : string ('BEFORE', 'AFTER', 'EXACT','WITHIN', 'BETWEEN')
 205   Args    : none
 206
 207 =cut
 208
 209 sub start_pos_type {
 210     my($self) = @_;
 211     $self->throw_not_implemented();
 212 }
 213
 214
 215 =head2 flip_strand
 216
 217   Title   : flip_strand
 218   Usage   : $location->flip_strand();
 219   Function: Flip-flop a strand to the opposite
 220   Returns : None
 221   Args    : None
 222
 223 =cut
 224
 225
 226 sub flip_strand {
 227     my $self= shift;
 228     $self->strand($self->strand * -1);
 229 }
 230
 231 =head2 min_end
 232
 233   Title   : min_end
 234   Usage   : my $minend = $location->min_end();
 235   Function: Get minimum ending point of feature.
 236
 237             Note that an implementation must not call end() in this method
 238             unless end() is overridden such as not to delegate to the
 239             coordinate computation policy object.
 240
 241   Returns : integer or undef if no minimum ending point.
 242   Args    : none
 243
 244 =cut
 245
 246 sub min_end {
 247     my($self) = @_;
 248     $self->throw_not_implemented();
 249 }
 250
 251 =head2 max_end
 252
 253   Title   : max_end
 254   Usage   : my $maxend = $location->max_end();
 255   Function: Get maximum ending point of feature.
 256
 257             Note that an implementation must not call end() in this method
 258             unless end() is overridden such as not to delegate to the
 259             coordinate computation policy object.
 260
 261   Returns : integer or undef if no maximum ending point.
 262   Args    : none
 263
 264 =cut
 265
 266 sub max_end {
 267     my($self) = @_;
 268     $self->throw_not_implemented();
 269 }
 270
 271 =head2 end_pos_type
 272
 273   Title   : end_pos_type
 274   Usage   : my $end_pos_type = $location->end_pos_type();
 275   Function: Get end position encoded as text.
 276
 277             Known valid values are 'BEFORE' (5..<100), 'AFTER' (5..>100),
 278             'EXACT' (5..100), 'WITHIN' (5..(90.100)), 'BETWEEN', (5^6), with
 279             their meaning best explained by their GenBank/EMBL location string
 280             encoding in brackets.
 281
 282   Returns : string ('BEFORE', 'AFTER', 'EXACT','WITHIN', 'BETWEEN')
 283   Args    : none
 284
 285 =cut
 286
 287 sub end_pos_type {
 288     my($self) = @_;
 289     $self->throw_not_implemented();
 290 }
 291
 292 =head2 seq_id
 293
 294   Title   : seq_id
 295   Usage   : my $seqid = $location->seq_id();
 296   Function: Get/Set seq_id that location refers to
 297   Returns : seq_id (a string)
 298   Args    : [optional] seq_id value to set
 299
 300 =cut
 301
 302 sub seq_id {
 303     my($self) = @_;
 304     $self->throw_not_implemented();
 305 }
 306
 307 =head2 is_remote
 308
 309  Title   : is_remote
 310  Usage   : $is_remote_loc = $loc->is_remote()
 311  Function: Whether or not a location is a remote location.
 312
 313            A location is said to be remote if it is on a different
 314            'object' than the object which 'has' this
 315            location. Typically, features on a sequence will sometimes
 316            have a remote location, which means that the location of
 317            the feature is on a different sequence than the one that is
 318            attached to the feature. In such a case, $loc->seq_id will
 319            be different from $feat->seq_id (usually they will be the
 320            same).
 321
 322            While this may sound weird, it reflects the location of the
 323            kind of AB18375:450-900 which can be found in GenBank/EMBL
 324            feature tables.
 325
 326  Example :
 327  Returns : TRUE if the location is a remote location, and FALSE otherwise
 328  Args    :
 329
 330
 331 =cut
 332
 333 sub is_remote{
 334     shift->throw_not_implemented();
 335 }
 336
 337 =head2 coordinate_policy
 338
 339   Title   : coordinate_policy
 340   Usage   : $policy = $location->coordinate_policy();
 341             $location->coordinate_policy($mypolicy); # set may not be possible
 342   Function: Get the coordinate computing policy employed by this object.
 343
 344             See L<Bio::Location::CoordinatePolicyI> for documentation
 345             about the policy object and its use.
 346
 347             The interface *does not* require implementing classes to
 348             accept setting of a different policy. The implementation
 349             provided here does, however, allow to do so.
 350
 351             Implementors of this interface are expected to initialize
 352             every new instance with a
 353             L<Bio::Location::CoordinatePolicyI> object. The
 354             implementation provided here will return a default policy
 355             object if none has been set yet. To change this default
 356             policy object call this method as a class method with an
 357             appropriate argument. Note that in this case only
 358             subsequently created Location objects will be affected.
 359
 360   Returns : A L<Bio::Location::CoordinatePolicyI> implementing object.
 361   Args    : On set, a L<Bio::Location::CoordinatePolicyI> implementing object.
 362
 363 See L<Bio::Location::CoordinatePolicyI> for more information
 364
 365
 366 =cut
 367
 368 sub coordinate_policy {
 369     shift->throw_not_implemented();
 370 }
 371
 372 =head2 to_FTstring
 373
 374   Title   : to_FTstring
 375   Usage   : my $locstr = $location->to_FTstring()
 376   Function: returns the FeatureTable string of this location
 377   Returns : string
 378   Args    : none
 379
 380 =cut
 381
 382 sub to_FTstring {
 383     my($self) = @_;
 384     $self->throw_not_implemented();
 385 }
 386
 387 =head2 each_Location
 388
 389  Title   : each_Location
 390  Usage   : @locations = $locObject->each_Location($order);
 391  Function: Conserved function call across Location:: modules - will
 392            return an array containing the component Location(s) in
 393            that object, regardless if the calling object is itself a
 394            single location or one containing sublocations.
 395  Returns : an array of Bio::LocationI implementing objects
 396  Args    : Optional sort order to be passed to sub_Location() for Splits
 397
 398 =cut
 399
 400 sub each_Location {
 401     my ($self,@args) = @_;
 402     $self->throw_not_implemented();
 403 }
 404
 405
 406 =head2 valid_Location
 407
 408  Title   : valid_Location
 409  Usage   : if ($location->valid_location) {...};
 410  Function: boolean method to determine whether location is considered valid
 411            (has minimum requirements for a specific LocationI implementation)
 412  Returns : Boolean value: true if location is valid, false otherwise
 413  Args    : none
 414
 415 =cut
 416
 417 sub valid_Location {
 418     my ($self,@args) = @_;
 419     $self->throw_not_implemented();
 420 }
 421
 422 1;
 423