Bio/LocationI.pm

filter: Statementstmt 39.5% 17 / 43 Branchbran 50.0% 2 / 4 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 26.3% 5 / 19 Podpod 100% 16 / 16 totaltotal 48.7% 40 / 82 CC 3 SCAR 6.2
CC
3
Cov
40%
start
2.0
end
2.0
location_type
2.0
CRAP 1.9
« Bio/Matrix/MatrixI.pm ↑ Summary Bio/Tools/Seg.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 331 $Bio::LocationI::VERSION = '1.7.8';
76 331 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
77  
78 331 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
79  
80 331 ▶use base qw(Bio::RangeI);
Subroutine BEGIN: called CC=1 SCAR=0.0
81  
82 =head2 location_type
83  
84 Title : location_type
85 Usage : my $location_type = $location->location_type();
86 Function: Get location type encoded as text
87 Returns : string ('EXACT', 'WITHIN', 'IN-BETWEEN')
88 Args : none
89  
90 =cut
91  
92 0 ▶sub location_type {
Subroutine location_type: not called CC=1 SCAR=6.9
Pod documented
93 0 my ($self,@args) = @_;
94 0 $self->throw_not_implemented();
95 }
96  
97 =head2 start
98  
99 Title : start
100 Usage : $start = $location->start();
101 Function: Get the start coordinate of this location as defined by
102 the currently active coordinate computation policy. In
103 simple cases, this will return the same number as
104 min_start() and max_start(), in more ambiguous cases like
105 fuzzy locations the number may be equal to one or neither
106 of both.
107  
108 We override this here from RangeI in order to delegate
109 'get' to a L<Bio::Location::CoordinatePolicy> implementing
110 object. Implementing classes may also wish to provide
111 'set' functionality, in which case they *must* override
112 this method. The implementation provided here will throw
113 an exception if called with arguments.
114  
115 Returns : A positive integer value.
116 Args : none
117  
118 See L<Bio::Location::CoordinatePolicy> for more information
119  
120 =cut
121  
122 38895 ▶sub start {
Subroutine start: called CC=2 SCAR=7.1
Pod documented
123 38895 my ($self,@args) = @_;
124  
125 # throw if @args means that we don't support updating information
126 # in the interface but will delegate to the coordinate policy object
127 # for interpreting the 'start' value
128  
129 38895 ▶ $self->throw_not_implemented if @args;
Branch: 1 branch
BranchTrueFalseTotal
if @args 0 38895 38895
130 38895 return $self->coordinate_policy()->start($self);
131 }
132  
133 =head2 end
134  
135 Title : end
136 Usage : $end = $location->end();
137 Function: Get the end coordinate of this location as defined by the
138 currently active coordinate computation policy. In simple
139 cases, this will return the same number as min_end() and
140 max_end(), in more ambiguous cases like fuzzy locations
141 the number may be equal to one or neither of both.
142  
143 We override this here from Bio::RangeI in order to delegate
144 'get' to a L<Bio::Location::CoordinatePolicy> implementing
145 object. Implementing classes may also wish to provide
146 'set' functionality, in which case they *must* override
147 this method. The implementation provided here will throw
148 an exception if called with arguments.
149  
150 Returns : A positive integer value.
151 Args : none
152  
153 See L<Bio::Location::CoordinatePolicy> and L<Bio::RangeI> for more
154 information
155  
156 =cut
157  
158 35230 ▶sub end {
Subroutine end: called CC=2 SCAR=7.1
Pod documented
159 35230 my ($self,@args) = @_;
160  
161 # throw if @args means that we don't support updating information
162 # in the interface but will delegate to the coordinate policy object
163 # for interpreting the 'end' value
164 35230 ▶ $self->throw_not_implemented if @args;
Branch: 1 branch
BranchTrueFalseTotal
if @args 0 35230 35230
165 35230 return $self->coordinate_policy()->end($self);
166 }
167  
168 =head2 min_start
169  
170 Title : min_start
171 Usage : my $minstart = $location->min_start();
172 Function: Get minimum starting point of feature.
173  
174 Note that an implementation must not call start() in this method.
175  
176 Returns : integer or undef if no minimum starting point.
177 Args : none
178  
179 =cut
180  
181 0 ▶sub min_start {
Subroutine min_start: not called CC=1 SCAR=6.9
Pod documented
182 0 my($self) = @_;
183 0 $self->throw_not_implemented();
184 }
185  
186 =head2 max_start
187  
188 Title : max_start
189 Usage : my $maxstart = $location->max_start();
190 Function: Get maximum starting point of feature.
191  
192 Note that an implementation must not call start() in this method
193 unless start() is overridden such as not to delegate to the
194 coordinate computation policy object.
195  
196 Returns : integer or undef if no maximum starting point.
197 Args : none
198  
199 =cut
200  
201 0 ▶sub max_start {
Subroutine max_start: not called CC=1 SCAR=6.9
Pod documented
202 0 my($self) = @_;
203 0 $self->throw_not_implemented();
204 }
205  
206 =head2 start_pos_type
207  
208 Title : start_pos_type
209 Usage : my $start_pos_type = $location->start_pos_type();
210 Function: Get start position type encoded as text
211  
212 Known valid values are 'BEFORE' (<5..100), 'AFTER' (>5..100),
213 'EXACT' (5..100), 'WITHIN' ((5.10)..100), 'BETWEEN', (5^6), with
214 their meaning best explained by their GenBank/EMBL location string
215 encoding in brackets.
216  
217 Returns : string ('BEFORE', 'AFTER', 'EXACT','WITHIN', 'BETWEEN')
218 Args : none
219  
220 =cut
221  
222 0 ▶sub start_pos_type {
Subroutine start_pos_type: not called CC=1 SCAR=6.9
Pod documented
223 0 my($self) = @_;
224 0 $self->throw_not_implemented();
225 }
226  
227  
228 =head2 flip_strand
229  
230 Title : flip_strand
231 Usage : $location->flip_strand();
232 Function: Flip-flop a strand to the opposite
233 Returns : None
234 Args : None
235  
236 =cut
237  
238  
239 0 ▶sub flip_strand {
Subroutine flip_strand: not called CC=1 SCAR=6.9
Pod documented
240 0 my $self= shift;
241 0 $self->strand($self->strand * -1);
242 }
243  
244 =head2 min_end
245  
246 Title : min_end
247 Usage : my $minend = $location->min_end();
248 Function: Get minimum ending point of feature.
249  
250 Note that an implementation must not call end() in this method
251 unless end() is overridden such as not to delegate to the
252 coordinate computation policy object.
253  
254 Returns : integer or undef if no minimum ending point.
255 Args : none
256  
257 =cut
258  
259 0 ▶sub min_end {
Subroutine min_end: not called CC=1 SCAR=6.9
Pod documented
260 0 my($self) = @_;
261 0 $self->throw_not_implemented();
262 }
263  
264 =head2 max_end
265  
266 Title : max_end
267 Usage : my $maxend = $location->max_end();
268 Function: Get maximum ending point of feature.
269  
270 Note that an implementation must not call end() in this method
271 unless end() is overridden such as not to delegate to the
272 coordinate computation policy object.
273  
274 Returns : integer or undef if no maximum ending point.
275 Args : none
276  
277 =cut
278  
279 0 ▶sub max_end {
Subroutine max_end: not called CC=1 SCAR=6.9
Pod documented
280 0 my($self) = @_;
281 0 $self->throw_not_implemented();
282 }
283  
284 =head2 end_pos_type
285  
286 Title : end_pos_type
287 Usage : my $end_pos_type = $location->end_pos_type();
288 Function: Get end position encoded as text.
289  
290 Known valid values are 'BEFORE' (5..<100), 'AFTER' (5..>100),
291 'EXACT' (5..100), 'WITHIN' (5..(90.100)), 'BETWEEN', (5^6), with
292 their meaning best explained by their GenBank/EMBL location string
293 encoding in brackets.
294  
295 Returns : string ('BEFORE', 'AFTER', 'EXACT','WITHIN', 'BETWEEN')
296 Args : none
297  
298 =cut
299  
300 0 ▶sub end_pos_type {
Subroutine end_pos_type: not called CC=1 SCAR=6.9
Pod documented
301 0 my($self) = @_;
302 0 $self->throw_not_implemented();
303 }
304  
305 =head2 seq_id
306  
307 Title : seq_id
308 Usage : my $seqid = $location->seq_id();
309 Function: Get/Set seq_id that location refers to
310 Returns : seq_id (a string)
311 Args : [optional] seq_id value to set
312  
313 =cut
314  
315 0 ▶sub seq_id {
Subroutine seq_id: not called CC=1 SCAR=6.9
Pod documented
316 0 my($self) = @_;
317 0 $self->throw_not_implemented();
318 }
319  
320 =head2 is_remote
321  
322 Title : is_remote
323 Usage : $is_remote_loc = $loc->is_remote()
324 Function: Whether or not a location is a remote location.
325  
326 A location is said to be remote if it is on a different
327 'object' than the object which 'has' this
328 location. Typically, features on a sequence will sometimes
329 have a remote location, which means that the location of
330 the feature is on a different sequence than the one that is
331 attached to the feature. In such a case, $loc->seq_id will
332 be different from $feat->seq_id (usually they will be the
333 same).
334  
335 While this may sound weird, it reflects the location of the
336 kind of AL445212.9:83662..166657 which can be found in GenBank/EMBL
337 feature tables.
338  
339 Example :
340 Returns : TRUE if the location is a remote location, and FALSE otherwise
341 Args : Value to set to
342  
343  
344 =cut
345  
346 0 ▶sub is_remote{
Subroutine is_remote: not called CC=1 SCAR=6.9
Pod documented
347 0 shift->throw_not_implemented();
348 }
349  
350 =head2 coordinate_policy
351  
352 Title : coordinate_policy
353 Usage : $policy = $location->coordinate_policy();
354 $location->coordinate_policy($mypolicy); # set may not be possible
355 Function: Get the coordinate computing policy employed by this object.
356  
357 See L<Bio::Location::CoordinatePolicyI> for documentation
358 about the policy object and its use.
359  
360 The interface *does not* require implementing classes to
361 accept setting of a different policy. The implementation
362 provided here does, however, allow one to do so.
363  
364 Implementors of this interface are expected to initialize
365 every new instance with a
366 L<Bio::Location::CoordinatePolicyI> object. The
367 implementation provided here will return a default policy
368 object if none has been set yet. To change this default
369 policy object call this method as a class method with an
370 appropriate argument. Note that in this case only
371 subsequently created Location objects will be affected.
372  
373 Returns : A L<Bio::Location::CoordinatePolicyI> implementing object.
374 Args : On set, a L<Bio::Location::CoordinatePolicyI> implementing object.
375  
376 See L<Bio::Location::CoordinatePolicyI> for more information
377  
378  
379 =cut
380  
381 0 ▶sub coordinate_policy {
Subroutine coordinate_policy: not called CC=1 SCAR=6.9
Pod documented
382 0 shift->throw_not_implemented();
383 }
384  
385 =head2 to_FTstring
386  
387 Title : to_FTstring
388 Usage : my $locstr = $location->to_FTstring()
389 Function: returns the FeatureTable string of this location
390 Returns : string
391 Args : none
392  
393 =cut
394  
395 0 ▶sub to_FTstring {
Subroutine to_FTstring: not called CC=1 SCAR=6.9
Pod documented
396 0 my($self) = @_;
397 0 $self->throw_not_implemented();
398 }
399  
400 =head2 each_Location
401  
402 Title : each_Location
403 Usage : @locations = $locObject->each_Location($order);
404 Function: Conserved function call across Location:: modules - will
405 return an array containing the component Location(s) in
406 that object, regardless if the calling object is itself a
407 single location or one containing sublocations.
408 Returns : an array of Bio::LocationI implementing objects
409 Args : Optional sort order to be passed to sub_Location() for Splits
410  
411 =cut
412  
413 0 ▶sub each_Location {
Subroutine each_Location: not called CC=1 SCAR=6.9
Pod documented
414 0 my ($self,@args) = @_;
415 0 $self->throw_not_implemented();
416 }
417  
418  
419 =head2 valid_Location
420  
421 Title : valid_Location
422 Usage : if ($location->valid_location) {...};
423 Function: boolean method to determine whether location is considered valid
424 (has minimum requirements for a specific LocationI implementation)
425 Returns : Boolean value: true if location is valid, false otherwise
426 Args : none
427  
428 =cut
429  
430 0 ▶sub valid_Location {
Subroutine valid_Location: not called CC=1 SCAR=6.9
Pod documented
431 0 my ($self,@args) = @_;
432 0 $self->throw_not_implemented();
433 }
434  
435 331 1;
436  
« Bio/Matrix/MatrixI.pm ↑ Summary Bio/Tools/Seg.pm »