Bio/LocationI.pm

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