Bio/Map/MappableI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Map::MappableI
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Sendu Bala <bix@sendu.me.uk>
   8 #
   9 # Copyright Jason Stajich
  10 #
  11 # You may distribute this module under the same terms as perl itself
  12
  13 # POD documentation - main docs before the code
  14
  15 =head1 NAME
  16
  17 Bio::Map::MappableI - An object that can be placed in a map
  18
  19 =head1 SYNOPSIS
  20
  21     # do not use this module directly
  22     # See Bio::Map::Mappable for an example of
  23     # implementation.
  24
  25 =head1 DESCRIPTION
  26
  27 This object handles the generic notion of an element placed on a
  28 (linear) Map. A Mappable can have multiple positions in multiple maps, such as
  29 is the case of Restriction enzyme cut sites on sequence maps. For exact
  30 information about a mappable's position in a map one must query the associate
  31 PositionI objects which are accessible through the get_positions() method.
  32
  33 =head1 FEEDBACK
  34
  35 =head2 Mailing Lists
  36
  37 User feedback is an integral part of the evolution of this and other
  38 Bioperl modules. Send your comments and suggestions preferably to
  39 the Bioperl mailing list.  Your participation is much appreciated.
  40
  41   bioperl-l@bioperl.org                  - General discussion
  42   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  43
  44 =head2 Support
  45
  46 Please direct usage questions or support issues to the mailing list:
  47
  48 L<bioperl-l@bioperl.org>
  49
  50 rather than to the module maintainer directly. Many experienced and
  51 reponsive experts will be able look at the problem and quickly
  52 address it. Please include a thorough description of the problem
  53 with code and data examples if at all possible.
  54
  55 =head2 Reporting Bugs
  56
  57 Report bugs to the Bioperl bug tracking system to help us keep track
  58 of the bugs and their resolution. Bug reports can be submitted via the
  59 web:
  60
  61   http://bugzilla.open-bio.org/
  62
  63 =head1 AUTHOR - Jason Stajich
  64
  65 Email jason@bioperl.org
  66
  67 =head1 CONTRIBUTORS
  68
  69 Heikki Lehvaslaiho heikki-at-bioperl-dot-org
  70 Lincoln Stein      lstein@cshl.org
  71 Sendu Bala         bix@sendu.me.uk
  72
  73 =head1 APPENDIX
  74
  75 The rest of the documentation details each of the object methods.
  76 Internal methods are usually preceded with a _
  77
  78 =cut
  79
  80 # Let the code begin...
  81
  82 package Bio::Map::MappableI;
  83 use strict;
  84 use Bio::Map::PositionHandler;
  85
  86 use base qw(Bio::Map::EntityI Bio::AnnotatableI);
  87
  88 =head2 EntityI methods
  89
  90  These are fundamental to coordination of Mappables and other entities, so are
  91  implemented at the interface level
  92
  93 =cut
  94
  95 =head2 get_position_handler
  96
  97  Title   : get_position_handler
  98  Usage   : my $position_handler = $entity->get_position_handler();
  99  Function: Gets a PositionHandlerI that $entity is registered with.
 100  Returns : Bio::Map::PositionHandlerI object
 101  Args    : none
 102
 103 =cut
 104
 105 sub get_position_handler {
 106     my $self = shift;
 107     unless (defined $self->{_eh}) {
 108         my $ph = Bio::Map::PositionHandler->new(-self => $self);
 109         $self->{_eh} = $ph;
 110         $ph->register;
 111     }
 112     return $self->{_eh};
 113 }
 114
 115 =head2 PositionHandlerI-related methods
 116
 117  These are fundamental to coordination of Mappables and other entities, so are
 118  implemented at the interface level
 119
 120 =cut
 121
 122 =head2 add_position
 123
 124  Title   : add_position
 125  Usage   : $mappable->add_position($position);
 126  Function: Add a position to this mappable (defining where on which map it is).
 127  Returns : n/a
 128  Args    : L<Bio::Map::PositionI> object
 129
 130 =cut
 131
 132 sub add_position {
 133     my $self = shift;
 134         # actually, we allow multiple positions to be set at once
 135     $self->get_position_handler->add_positions(@_);
 136 }
 137
 138 =head2 get_positions
 139
 140  Title   : get_positions
 141  Usage   : my @positions = $mappable->get_positions();
 142  Function: Get all the Positions of this Mappable (sorted).
 143  Returns : Array of L<Bio::Map::PositionI> objects
 144  Args    : none for all, OR
 145            L<Bio::Map::MapI> object for positions on the given map, AND/OR some
 146            other true value to avoid sorting
 147
 148 =cut
 149
 150 sub get_positions {
 151     my ($self, $thing, $no_sort) = @_;
 152     my $map;
 153     if (ref($thing) && $thing->isa('Bio::Map::MapI')) {
 154         $map = $thing;
 155     }
 156     else {
 157         $no_sort = $thing;
 158     }
 159     my @positions = $self->get_position_handler->get_positions($map);
 160     return @positions if @positions == 1;
 161
 162     unless ($no_sort) {
 163         # don't do
 164         # @positions = sort { $a->sortable <=> $b->sortable } @positions;
 165         # directly since sortable() can result in the call of another sort
 166         # routine and cause problems; pre-compute sortable values instead
 167         # (which is also more efficient)
 168         @positions = map { $_->[1] }
 169                      sort { $a->[0] <=> $b->[0] }
 170                      map  { [$_->sortable, $_] }
 171                      @positions;
 172     }
 173     return @positions;
 174 }
 175
 176 =head2 each_position
 177
 178  Title   : each_position
 179  Function: Synonym of the get_positions() method.
 180  Status  : deprecated, will be removed in next version
 181
 182 =cut
 183
 184 *each_position = \&get_positions;
 185
 186 =head2 purge_positions
 187
 188  Title   : purge_positions
 189  Usage   : $mappable->purge_positions();
 190  Function: Remove positions from this mappable.
 191  Returns : n/a
 192  Args    : none to remove all positions, OR
 193            L<Bio::Map::PositionI> object to remove just that Position, OR
 194                    L<Bio::Map::MapI> object to remove only those positions on the given
 195                    map
 196
 197 =cut
 198
 199 sub purge_positions {
 200     my ($self, $thing) = @_;
 201     $self->get_position_handler->purge_positions($thing);
 202 }
 203
 204 =head2 known_maps
 205
 206  Title   : known_maps
 207  Usage   : my @maps = $marker->known_maps()
 208  Function: Returns the maps that this mappable is found on
 209  Returns : Array of L<Bio::Map::MapI> objects
 210  Args    : none
 211
 212 =cut
 213
 214 sub known_maps {
 215         my $self = shift;
 216         return $self->get_position_handler->get_other_entities;
 217 }
 218
 219 =head2 MappableI-specific methods
 220
 221 =cut
 222
 223 =head2 name
 224
 225  Title   : name
 226  Usage   : my $name = $marker->name();
 227            $marker->name($new_name);
 228  Function: Get/Set the name for this Mappable.
 229  Returns : A scalar representing the current name of this Mappable
 230  Args    : none to get
 231            string to set
 232
 233 =cut
 234
 235 sub name {
 236     my $self = shift;
 237     $self->throw_not_implemented();
 238 }
 239
 240 =head2 id
 241
 242  Title   : id
 243  Usage   : my $id = $marker->id();
 244            $marker->id($new_id);
 245  Function: Get/Set the id for this Mappable.
 246  Returns : A scalar representing the current id of this Mappable
 247  Args    : none to get
 248            string to set
 249
 250 =cut
 251
 252 sub id {
 253     my $self = shift;
 254     $self->throw_not_implemented();
 255 }
 256
 257 =head2 in_map
 258
 259  Title   : in_map
 260  Usage   : if ($marker->in_map($map)) {...}
 261  Function: Tests if this mappable is found on a specific map
 262  Returns : boolean
 263  Args    : L<Bio::Map::MapI>
 264
 265 =cut
 266
 267 sub in_map {
 268         my $self = shift;
 269         $self->throw_not_implemented();
 270 }
 271
 272 =head1 RangeI-related Methods
 273
 274 They throw an error if start and end are not defined in the Positions of the
 275 Mappables supplied.
 276
 277 =cut
 278
 279 =head2 equals
 280
 281  Title   : equals
 282  Usage   : if ($mappable->equals($other_mappable)) {...}
 283            my @equal_positions = $mappable->equals($other_mappable);
 284  Function: Finds the positions in this mappable that are equal to any
 285            comparison positions.
 286  Returns : array of L<Bio::Map::PositionI> objects
 287  Args    : arg #1 = L<Bio::Map::MappableI> OR L<Bio::Map::PositionI> to compare
 288                     this one to (mandatory)
 289            arg #2 = optionally, the key => value pairs below
 290                    -map => Bio::Map::MapI           : optionally a Map to only consider
 291                                                       positions on the given map
 292                    -relative => Bio::Map::RelativeI : optionally a Relative to ask if
 293                                                                                           the Positions equal in terms of
 294                                                                                           their relative position to the
 295                                                                                           thing described by that Relative
 296
 297 =cut
 298
 299 sub equals {
 300     my $self = shift;
 301     $self->throw_not_implemented();
 302 }
 303
 304 =head2 overlaps
 305
 306  Title   : overlaps
 307  Usage   : if ($mappable->overlaps($other_mappable)) {...}
 308            my @overlapping_positions = $mappable->overlaps($other_mappable);
 309  Function: Finds the positions in this mappable that overlap with any
 310            comparison positions.
 311  Returns : array of L<Bio::Map::PositionI> objects
 312  Args    : arg #1 = L<Bio::Map::MappableI> OR L<Bio::Map::PositionI> to compare
 313                     this one to (mandatory)
 314            arg #2 = optionally, the key => value pairs below
 315                    -map => Bio::Map::MapI           : optionally a Map to only consider
 316                                                       positions on the given map
 317                    -relative => Bio::Map::RelativeI : optionally a Relative to ask if
 318                                               the Positions overlap in terms of
 319                                               their relative position to the
 320                                               thing described by that Relative
 321
 322 =cut
 323
 324 sub overlaps {
 325     my $self = shift;
 326     $self->throw_not_implemented();
 327 }
 328
 329 =head2 contains
 330
 331  Title   : contains
 332  Usage   : if ($mappable->contains($other_mappable)) {...}
 333            my @container_positions = $mappable->contains($other_mappable);
 334  Function: Finds the positions in this mappable that contain any comparison
 335            positions.
 336  Returns : array of L<Bio::Map::PositionI> objects
 337  Args    : arg #1 = L<Bio::Map::MappableI> OR L<Bio::Map::PositionI> to compare
 338                     this one to (mandatory)
 339            arg #2 = optionally, the key => value pairs below
 340                    -map => Bio::Map::MapI           : optionally a Map to only consider
 341                                                       positions on the given map
 342                    -relative => Bio::Map::RelativeI : optionally a Relative to ask if
 343                                               the Positions contains in terms of
 344                                               their relative position to the
 345                                               thing described by that Relative
 346
 347 =cut
 348
 349 sub contains {
 350     my $self = shift;
 351     $self->throw_not_implemented();
 352 }
 353
 354 =head2 intersection
 355
 356  Title   : intersection
 357  Usage   : my $position = $mappable->intersection($other_mappable);
 358            my $position = Bio::Map::Mappable->intersection(\@mappables);
 359  Function: Make the position that is at the intersection of all positions of all
 360            supplied mappables.
 361  Returns : L<Bio::Map::PositionI> object or undef (if not all positions overlap)
 362  Args    : arg #1 = L<Bio::Map::MappableI> OR L<Bio::Map::PositionI> to  compare
 363                     this one to, or an array ref of such objects (mandatory)
 364            arg #2 = optionally, the key => value pairs below
 365                    -map => Bio::Map::MapI           : optionally a Map to only consider
 366                                                       positions on the given map
 367                    -relative => Bio::Map::RelativeI : optionally a Relative to to ask
 368                                                                                           how the Positions intersect in
 369                                                                                           terms of their relative position
 370                                                                                           to the thing described by that
 371                                                                                           Relative
 372
 373 =cut
 374
 375 sub intersection {
 376     my $self = shift;
 377     $self->throw_not_implemented();
 378 }
 379
 380 =head2 union
 381
 382  Title   : union
 383  Usage   : my $position = $mappable->union($other_mappable);
 384            my $position = Bio::Map::Mappable->union(@mappables);
 385  Function: Make the minimal position that contains all of the positions of all
 386            supplied mappables.
 387  Returns : L<Bio::Map::PositionI> object or undef (if not all positions overlap)
 388  Args    : arg #1 = L<Bio::Map::MappableI> OR L<Bio::Map::PositionI> to  compare
 389                     this one to, or an array ref of such objects (mandatory)
 390            arg #2 = optionally, the key => value pairs below
 391                    -map => Bio::Map::MapI           : optionally a Map to only consider
 392                                                       positions on the given map
 393                    -relative => Bio::Map::RelativeI : optionally a Relative to to ask
 394                                                                                           if the union of the Positions in
 395                                                                                           terms of their relative position
 396                                                                                           to the thing described by that
 397                                                                                           Relative
 398
 399 =cut
 400
 401 sub union {
 402     my $self = shift;
 403     $self->throw_not_implemented();
 404 }
 405
 406 1;