File Coverage

Bio/Map/MappableI.pm
Criterion Covered Total %
statement 34 50 68.0
branch 8 8 100.0
condition 2 3 66.6
subroutine 8 16 50.0
pod 13 13 100.0
total 65 90 72.2


line stmt bran cond sub pod time code
1             #
2             # BioPerl module for Bio::Map::MappableI
3             #
4             # Please direct questions and support issues to
5             #
6             # Cared for by Sendu Bala
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::MappableI - An object that can be placed in a map
17              
18             =head1 SYNOPSIS
19              
20             # do not use this module directly
21             # See Bio::Map::Mappable for an example of
22             # implementation.
23              
24             =head1 DESCRIPTION
25              
26             This object handles the generic notion of an element placed on a
27             (linear) Map. A Mappable can have multiple positions in multiple maps, such as
28             is the case of Restriction enzyme cut sites on sequence maps. For exact
29             information about a mappable's position in a map one must query the associate
30             PositionI objects which are accessible through the get_positions() method.
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
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             Heikki Lehvaslaiho heikki-at-bioperl-dot-org
69             Lincoln Stein lstein@cshl.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::MappableI;
82 9     9   41 use strict;
  9         11  
  9         196  
83 9     9   29 use Bio::Map::PositionHandler;
  9         103  
  9         160  
84              
85 9     9   123 use base qw(Bio::Map::EntityI Bio::AnnotatableI);
  9         9  
  9         3059  
86              
87             =head2 EntityI methods
88              
89             These are fundamental to coordination of Mappables 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 2215     2215 1 1787 my $self = shift;
106 2215 100       3145 unless (defined $self->{_eh}) {
107 113         272 my $ph = Bio::Map::PositionHandler->new(-self => $self);
108 113         166 $self->{_eh} = $ph;
109 113         159 $ph->register;
110             }
111 2215         4058 return $self->{_eh};
112             }
113              
114             =head2 PositionHandlerI-related methods
115              
116             These are fundamental to coordination of Mappables and other entities, so are
117             implemented at the interface level
118              
119             =cut
120              
121             =head2 add_position
122              
123             Title : add_position
124             Usage : $mappable->add_position($position);
125             Function: Add a position to this mappable (defining where on which map it is).
126             Returns : n/a
127             Args : L object
128              
129             =cut
130              
131             sub add_position {
132 101     101 1 113 my $self = shift;
133             # actually, we allow multiple positions to be set at once
134 101         133 $self->get_position_handler->add_positions(@_);
135             }
136              
137             =head2 get_positions
138              
139             Title : get_positions
140             Usage : my @positions = $mappable->get_positions();
141             Function: Get all the Positions of this Mappable (sorted).
142             Returns : Array of L objects
143             Args : none for all, OR
144             L object for positions on the given map, AND/OR some
145             other true value to avoid sorting
146              
147             =cut
148              
149             sub get_positions {
150 1559     1559 1 1356 my ($self, $thing, $no_sort) = @_;
151 1559         1060 my $map;
152 1559 100 66     5139 if (ref($thing) && $thing->isa('Bio::Map::MapI')) {
153 1330         1097 $map = $thing;
154             }
155             else {
156 229         187 $no_sort = $thing;
157             }
158 1559         1914 my @positions = $self->get_position_handler->get_positions($map);
159 1559 100       3669 return @positions if @positions == 1;
160            
161 472 100       667 unless ($no_sort) {
162             # don't do
163             # @positions = sort { $a->sortable <=> $b->sortable } @positions;
164             # directly since sortable() can result in the call of another sort
165             # routine and cause problems; pre-compute sortable values instead
166             # (which is also more efficient)
167 114         122 @positions = map { $_->[1] }
168 155         152 sort { $a->[0] <=> $b->[0] }
169 31         41 map { [$_->sortable, $_] }
  114         201  
170             @positions;
171             }
172 472         954 return @positions;
173             }
174              
175             =head2 each_position
176              
177             Title : each_position
178             Function: Synonym of the get_positions() method.
179             Status : deprecated, will be removed in next version
180              
181             =cut
182              
183             *each_position = \&get_positions;
184              
185             =head2 purge_positions
186              
187             Title : purge_positions
188             Usage : $mappable->purge_positions();
189             Function: Remove positions from this mappable.
190             Returns : n/a
191             Args : none to remove all positions, OR
192             L object to remove just that Position, OR
193             L object to remove only those positions on the given
194             map
195              
196             =cut
197              
198             sub purge_positions {
199 46     46 1 1902 my ($self, $thing) = @_;
200 46         81 $self->get_position_handler->purge_positions($thing);
201             }
202              
203             =head2 known_maps
204              
205             Title : known_maps
206             Usage : my @maps = $marker->known_maps()
207             Function: Returns the maps that this mappable is found on
208             Returns : Array of L objects
209             Args : none
210              
211             =cut
212              
213             sub known_maps {
214 340     340 1 786 my $self = shift;
215 340         460 return $self->get_position_handler->get_other_entities;
216             }
217              
218             =head2 MappableI-specific methods
219              
220             =cut
221              
222             =head2 name
223              
224             Title : name
225             Usage : my $name = $marker->name();
226             $marker->name($new_name);
227             Function: Get/Set the name for this Mappable.
228             Returns : A scalar representing the current name of this Mappable
229             Args : none to get
230             string to set
231              
232             =cut
233              
234             sub name {
235 0     0 1   my $self = shift;
236 0           $self->throw_not_implemented();
237             }
238              
239             =head2 id
240              
241             Title : id
242             Usage : my $id = $marker->id();
243             $marker->id($new_id);
244             Function: Get/Set the id for this Mappable.
245             Returns : A scalar representing the current id of this Mappable
246             Args : none to get
247             string to set
248              
249             =cut
250              
251             sub id {
252 0     0 1   my $self = shift;
253 0           $self->throw_not_implemented();
254             }
255              
256             =head2 in_map
257              
258             Title : in_map
259             Usage : if ($marker->in_map($map)) {...}
260             Function: Tests if this mappable is found on a specific map
261             Returns : boolean
262             Args : L
263              
264             =cut
265              
266             sub in_map {
267 0     0 1   my $self = shift;
268 0           $self->throw_not_implemented();
269             }
270              
271             =head1 RangeI-related Methods
272              
273             They throw an error if start and end are not defined in the Positions of the
274             Mappables supplied.
275              
276             =cut
277              
278             =head2 equals
279              
280             Title : equals
281             Usage : if ($mappable->equals($other_mappable)) {...}
282             my @equal_positions = $mappable->equals($other_mappable);
283             Function: Finds the positions in this mappable that are equal to any
284             comparison positions.
285             Returns : array of L objects
286             Args : arg #1 = L OR L to compare
287             this one to (mandatory)
288             arg #2 = optionally, the key => value pairs below
289             -map => Bio::Map::MapI : optionally a Map to only consider
290             positions on the given map
291             -relative => Bio::Map::RelativeI : optionally a Relative to ask if
292             the Positions equal in terms of
293             their relative position to the
294             thing described by that Relative
295              
296             =cut
297              
298             sub equals {
299 0     0 1   my $self = shift;
300 0           $self->throw_not_implemented();
301             }
302              
303             =head2 overlaps
304              
305             Title : overlaps
306             Usage : if ($mappable->overlaps($other_mappable)) {...}
307             my @overlapping_positions = $mappable->overlaps($other_mappable);
308             Function: Finds the positions in this mappable that overlap with any
309             comparison positions.
310             Returns : array of L objects
311             Args : arg #1 = L OR L to compare
312             this one to (mandatory)
313             arg #2 = optionally, the key => value pairs below
314             -map => Bio::Map::MapI : optionally a Map to only consider
315             positions on the given map
316             -relative => Bio::Map::RelativeI : optionally a Relative to ask if
317             the Positions overlap in terms of
318             their relative position to the
319             thing described by that Relative
320              
321             =cut
322              
323             sub overlaps {
324 0     0 1   my $self = shift;
325 0           $self->throw_not_implemented();
326             }
327              
328             =head2 contains
329              
330             Title : contains
331             Usage : if ($mappable->contains($other_mappable)) {...}
332             my @container_positions = $mappable->contains($other_mappable);
333             Function: Finds the positions in this mappable that contain any comparison
334             positions.
335             Returns : array of L objects
336             Args : arg #1 = L OR L to compare
337             this one to (mandatory)
338             arg #2 = optionally, the key => value pairs below
339             -map => Bio::Map::MapI : optionally a Map to only consider
340             positions on the given map
341             -relative => Bio::Map::RelativeI : optionally a Relative to ask if
342             the Positions contains in terms of
343             their relative position to the
344             thing described by that Relative
345              
346             =cut
347              
348             sub contains {
349 0     0 1   my $self = shift;
350 0           $self->throw_not_implemented();
351             }
352              
353             =head2 intersection
354              
355             Title : intersection
356             Usage : my $position = $mappable->intersection($other_mappable);
357             my $position = Bio::Map::Mappable->intersection(\@mappables);
358             Function: Make the position that is at the intersection of all positions of all
359             supplied mappables.
360             Returns : L object or undef (if not all positions overlap)
361             Args : arg #1 = L OR L to compare
362             this one to, or an array ref of such objects (mandatory)
363             arg #2 = optionally, the key => value pairs below
364             -map => Bio::Map::MapI : optionally a Map to only consider
365             positions on the given map
366             -relative => Bio::Map::RelativeI : optionally a Relative to to ask
367             how the Positions intersect in
368             terms of their relative position
369             to the thing described by that
370             Relative
371              
372             =cut
373              
374             sub intersection {
375 0     0 1   my $self = shift;
376 0           $self->throw_not_implemented();
377             }
378              
379             =head2 union
380              
381             Title : union
382             Usage : my $position = $mappable->union($other_mappable);
383             my $position = Bio::Map::Mappable->union(@mappables);
384             Function: Make the minimal position that contains all of the positions of all
385             supplied mappables.
386             Returns : L object or undef (if not all positions overlap)
387             Args : arg #1 = L OR L to compare
388             this one to, or an array ref of such objects (mandatory)
389             arg #2 = optionally, the key => value pairs below
390             -map => Bio::Map::MapI : optionally a Map to only consider
391             positions on the given map
392             -relative => Bio::Map::RelativeI : optionally a Relative to to ask
393             if the union of the Positions in
394             terms of their relative position
395             to the thing described by that
396             Relative
397              
398             =cut
399              
400             sub union {
401 0     0 1   my $self = shift;
402 0           $self->throw_not_implemented();
403             }
404              
405             1;