Bio/LocationI.pm

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