lib/Bio/Map/MapI.pm

   1 #
   2 # BioPerl module for Bio::Map::MapI
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Sendu Bala <bix@sendu.me.uk>
   7 #
   8 # Copyright Jason Stajich
   9 #
  10 # You may distribute this module under the same terms as perl itself
  11
  12 # POD documentation - main docs before the code
  13
  14 =head1 NAME
  15
  16 Bio::Map::MapI - Interface for describing Map objects in bioperl
  17
  18 =head1 SYNOPSIS
  19
  20     # get a MapI somehow
  21     my $name   = $map->name();     # string
  22     my $length = $map->length();   # integer
  23     my $species= $map->species;    # Bio::Species
  24     my $type   = $map->type();     # genetic/sts/rh/
  25
  26 =head1 DESCRIPTION
  27
  28 This object describes the basic functionality of a Map in bioperl.
  29 Maps are anything from Genetic Map to Sequence Map to Assembly Map
  30 to Restriction Enzyme to FPC.
  31
  32 =head1 FEEDBACK
  33
  34 =head2 Mailing Lists
  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
  38 the Bioperl mailing list.  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 I<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 of the bugs and their resolution. Bug reports can be submitted via the
  58 web:
  59
  60   https://github.com/bioperl/bioperl-live/issues
  61
  62 =head1 AUTHOR - Jason Stajich
  63
  64 Email jason@bioperl.org
  65
  66 =head1 CONTRIBUTORS
  67
  68 Lincoln Stein, lstein@cshl.org
  69 Heikki Lehvaslaiho, heikki-at-bioperl-dot-org
  70 Sendu Bala, bix@sendu.me.uk
  71
  72 =head1 APPENDIX
  73
  74 The rest of the documentation details each of the object methods.
  75 Internal methods are usually preceded with a _
  76
  77 =cut
  78
  79 # Let the code begin...
  80
  81 package Bio::Map::MapI;
  82 use strict;
  83 use Bio::Map::PositionHandler;
  84
  85 use base qw(Bio::Map::EntityI Bio::AnnotatableI);
  86
  87 =head2 EntityI methods
  88
  89  These are fundamental to coordination of Maps and other entities, so are
  90  implemented at the interface level
  91
  92 =cut
  93
  94 =head2 get_position_handler
  95
  96  Title   : get_position_handler
  97  Usage   : my $position_handler = $entity->get_position_handler();
  98  Function: Gets a PositionHandlerI that $entity is registered with.
  99  Returns : Bio::Map::PositionHandlerI object
 100  Args    : none
 101
 102 =cut
 103
 104 sub get_position_handler {
 105     my $self = shift;
 106     unless (defined $self->{_eh}) {
 107         my $ph = Bio::Map::PositionHandler->new(-self => $self);
 108         $self->{_eh} = $ph;
 109         $ph->register;
 110     }
 111     return $self->{_eh};
 112 }
 113
 114 =head2 PositionHandlerI-related methods
 115
 116  These are fundamental to coordination of Maps and other entities, so are
 117  implemented at the interface level
 118
 119 =cut
 120
 121 =head2 get_positions
 122
 123  Title   : get_positions
 124  Usage   : my @positions = $mappable->get_positions();
 125  Function: Get all the Positions on this Map (sorted).
 126  Returns : Array of L<Bio::Map::PositionI> objects
 127  Args    : none for all, OR
 128            L<Bio::Map::MappableI> object for positions of the given Mappable
 129
 130 =cut
 131
 132 sub get_positions {
 133     my ($self, $mappable) = @_;
 134         my @positions = $self->get_position_handler->get_positions($mappable);
 135     # precompute sortable for effieciency and to avoid bugs
 136     @positions = map { $_->[1] }
 137                  sort { $a->[0] <=> $b->[0] }
 138                  map { [$_->sortable, $_] }
 139                  @positions;
 140     return @positions;
 141 }
 142
 143 =head2 each_position
 144
 145  Title   : each_position
 146  Function: Synonym of the get_positions() method.
 147  Status  : deprecated, will be removed in next version
 148
 149 =cut
 150
 151 *each_position = \&get_positions;
 152
 153 =head2 purge_positions
 154
 155  Title   : purge_positions
 156  Usage   : $map->purge_position();
 157  Function: Remove all positions from this map. Notifies the positions they are
 158            no longer on this map.
 159  Returns : n/a
 160  Args    : none to remove all positions, OR
 161            L<Bio::Map::PositionI> object to remove just that Position, OR
 162                    L<Bio::Map::MappableI> object to remove only those positions of the
 163            given mappable
 164
 165 =cut
 166
 167 sub purge_positions {
 168     my ($self, $thing) = @_;
 169     $self->get_position_handler->purge_positions($thing);
 170 }
 171
 172 =head2 get_elements
 173
 174  Title   : get_elements
 175  Usage   : my @elements = $map->get_elements;
 176  Function: Retrieves all the elements on a map (unordered)
 177  Returns : Array of Map elements (L<Bio::Map::MappableI>)
 178  Args    : none
 179
 180 =cut
 181
 182 sub get_elements {
 183     my $self = shift;
 184     return $self->get_position_handler->get_other_entities;
 185 }
 186
 187 =head2 each_element
 188
 189  Title   : each_element
 190  Function: Synonym of the get_elements() method.
 191  Status  : deprecated, will be removed in the next version
 192
 193 =cut
 194
 195 =head2 common_elements
 196
 197  Title   : common_elements
 198  Usage   : my @common_elements = $map->common_elements(\@other_maps);
 199            my @common_elements = Bio::Map::SimpleMap->common_elements(\@maps);
 200  Function: Find the elements that are common to multiple maps.
 201  Returns : array of Bio::Map::MappableI
 202  Args    : arg #1 = L<Bio::Map::MapI> to compare this one to, or an array ref
 203                     of such objects (mandatory)
 204            arg #2 = optionally, one or more of the key => value pairs below
 205            -min_num => int        : the minimum number of input maps an element
 206                                     must be found on before before returned
 207                                     [default is 1]
 208            -min_percent => number : as above, but the minimum percentage of
 209                                     input maps [default is 100 - note that this
 210                                     will effectively override all other options]
 211            -require_self => 1|0   : require that all output elements at least
 212                                     be on the calling map [default is 1, has no
 213                                     effect when the second usage form is used]
 214            -required => \@maps    : require that all output elements be on at
 215                                     least all the maps supplied here
 216
 217 =cut
 218
 219 sub common_elements {
 220     my ($self, $maps_ref, @extra_args) = @_;
 221     $self->throw("Must supply a reference first argument") unless ref($maps_ref);
 222     my @maps;
 223     if (ref($maps_ref) eq 'ARRAY') {
 224         @maps = @{$maps_ref};
 225     }
 226     elsif ($maps_ref->isa('Bio::Map::MapI')) {
 227         @maps = ($maps_ref);
 228     }
 229     if (ref($self)) {
 230         unshift(@maps, $self);
 231     }
 232     $self->throw("Need at least 2 maps") unless @maps >= 2;
 233
 234     my %args = (-min_num => 1, -min_percent => 100, -require_self => 1, -required => undef, @extra_args);
 235     my $min_num = $args{-min_num};
 236     if ($args{-min_percent}) {
 237         my $mn = @maps / 100 * $args{-min_percent};
 238         if ($mn > $min_num) {
 239             $min_num = $mn;
 240         }
 241     }
 242     my %required = map { $_ => 1 } $args{-required} ? @{$args{-required}} : ();
 243     $required{$self} = 1 if ref($self) && $args{-require_self};
 244     my @required = keys %required;
 245
 246     my %map_elements;
 247     my %elements;
 248     my %count;
 249     foreach my $map (@maps) {
 250         $map_elements{$map} = {};
 251         foreach my $element ($map->get_elements) {
 252             $map_elements{$map}->{$element} = 1;
 253             $elements{$element} = $element;
 254             $count{$element}++;
 255         }
 256     }
 257
 258     my @elements;
 259     ELEMENT: while (my ($key, $value) = each %elements) {
 260         $count{$key} >= $min_num or next;
 261         foreach my $required (@required) {
 262             exists $map_elements{$required}->{$key} or next ELEMENT;
 263         }
 264
 265         push(@elements, $value);
 266     }
 267     return @elements;
 268 }
 269
 270 =head2 MapI-specific methods
 271
 272 =cut
 273
 274 =head2 species
 275
 276  Title   : species
 277  Usage   : my $species = $map->species;
 278  Function: Get/Set Species for a map
 279  Returns : L<Bio::Species> object
 280  Args    : (optional) Bio::Species
 281
 282 =cut
 283
 284 sub species{
 285     my $self = shift;
 286     $self->throw_not_implemented();
 287 }
 288
 289 =head2 units
 290
 291  Title   : units
 292  Usage   : $map->units('cM');
 293  Function: Get/Set units for a map
 294  Returns : units for a map
 295  Args    : units for a map (string)
 296
 297 =cut
 298
 299 sub units{
 300     my $self = shift;
 301     $self->throw_not_implemented();
 302 }
 303
 304 =head2 type
 305
 306  Title   : type
 307  Usage   : my $type = $map->type
 308  Function: Get/Set Map type
 309  Returns : String coding map type
 310  Args    : (optional) string
 311
 312 =cut
 313
 314 sub type {
 315     my $self = shift;
 316     $self->throw_not_implemented();
 317 }
 318
 319 =head2 name
 320
 321  Title   : name
 322  Usage   : my $name = $map->name
 323  Function: Get/Set Map name
 324  Returns : Map name
 325  Args    : (optional) string
 326
 327 =cut
 328
 329 sub name {
 330     my $self = shift;
 331     $self->throw_not_implemented();
 332 }
 333
 334 =head2 length
 335
 336  Title   : length
 337  Usage   : my $length = $map->length();
 338  Function: Retrieves the length of the map.
 339            It is possible for the length to be unknown for maps such as
 340            Restriction Enzyme, will return 0 in that case
 341  Returns : integer representing length of map in current units
 342            will return undef if length is not calculateable
 343  Args    : none
 344
 345 =cut
 346
 347 sub length {
 348     my $self = shift;
 349     $self->throw_not_implemented();
 350 }
 351
 352 1;