File Coverage

Bio/LocationI.pm
Criterion Covered Total %
statement 15 41 36.5
branch 2 4 50.0
condition n/a
subroutine 5 19 26.3
pod 16 16 100.0
total 38 80 47.5


line stmt bran cond sub pod time code
1             #
2             # BioPerl module for Bio::LocationI
3             # Please direct questions and support issues to
4             #
5             # Cared for by Jason Stajich
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 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
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 195     195   1227 use strict;
  195         319  
  195         4838  
76              
77 195     195   839 use Carp;
  195         330  
  195         10724  
78              
79 195     195   928 use base qw(Bio::RangeI);
  195         315  
  195         64967  
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 0     0 1 0 my ($self,@args) = @_;
93 0         0 $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 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 for more information
118              
119             =cut
120              
121             sub start {
122 39335     39335 1 43010 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 39335 50       49143 $self->throw_not_implemented if @args;
129 39335         57231 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 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 and L for more
153             information
154              
155             =cut
156              
157             sub end {
158 35596     35596 1 39257 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 35596 50       47049 $self->throw_not_implemented if @args;
164 35596         48665 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 0     0 1   my($self) = @_;
182 0           $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 0     0 1   my($self) = @_;
202 0           $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 0     0 1   my($self) = @_;
223 0           $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 0     0 1   my $self= shift;
240 0           $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 0     0 1   my($self) = @_;
260 0           $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 0     0 1   my($self) = @_;
280 0           $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 0     0 1   my($self) = @_;
301 0           $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 0     0 1   my($self) = @_;
316 0           $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 0     0 1   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 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 one to do so.
362              
363             Implementors of this interface are expected to initialize
364             every new instance with a
365             L 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 implementing object.
373             Args : On set, a L implementing object.
374              
375             See L for more information
376              
377              
378             =cut
379              
380             sub coordinate_policy {
381 0     0 1   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 0     0 1   my($self) = @_;
396 0           $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 0     0 1   my ($self,@args) = @_;
414 0           $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 0     0 1   my ($self,@args) = @_;
431 0           $self->throw_not_implemented();
432             }
433              
434             1;
435