|
0
|
1 # $Id: LocationI.pm,v 1.18 2002/12/01 00:05:19 jason Exp $
|
|
|
2 #
|
|
|
3 # BioPerl module for Bio::LocationI
|
|
|
4 # Cared for by Jason Stajich <jason@bioperl.org>
|
|
|
5 #
|
|
|
6 # Copyright Jason Stajich
|
|
|
7 #
|
|
|
8 # You may distribute this module under the same terms as perl itself
|
|
|
9 # POD documentation - main docs before the code
|
|
|
10
|
|
|
11 =head1 NAME
|
|
|
12
|
|
|
13 Bio::LocationI - Abstract interface of a Location on a Sequence
|
|
|
14
|
|
|
15 =head1 SYNOPSIS
|
|
|
16
|
|
|
17 # get a LocationI somehow
|
|
|
18 printf( "start = %d, end = %d, strand = %s, seq_id = %s\n",
|
|
|
19 $location->start, $location->end, $location->strand,
|
|
|
20 $location->seq_id);
|
|
|
21 print "location str is ", $location->to_FTstring(), "\n";
|
|
|
22
|
|
|
23
|
|
|
24 =head1 DESCRIPTION
|
|
|
25
|
|
|
26 This Interface defines the methods for a Bio::LocationI, an object
|
|
|
27 which encapsulates a location on a biological sequence. Locations
|
|
|
28 need not be attached to actual sequences as they are stand alone
|
|
|
29 objects. LocationI objects are used by L<Bio::SeqFeatureI> objects to
|
|
|
30 manage and represent locations for a Sequence Feature.
|
|
|
31
|
|
|
32 =head1 FEEDBACK
|
|
|
33
|
|
|
34 User feedback is an integral part of the evolution of this and other
|
|
|
35 Bioperl modules. Send your comments and suggestions preferably to one
|
|
|
36 of the Bioperl mailing lists. Your participation is much appreciated.
|
|
|
37
|
|
|
38 bioperl-l@bioperl.org - General discussion
|
|
|
39 http://bio.perl.org/MailList.html - About the mailing lists
|
|
|
40
|
|
|
41 =head2 Reporting Bugs
|
|
|
42
|
|
|
43 Report bugs to the Bioperl bug tracking system to help us keep track
|
|
|
44 the bugs and their resolution. Bug reports can be submitted via email
|
|
|
45 or the web:
|
|
|
46
|
|
|
47 bioperl-bugs@bio.perl.org
|
|
|
48 http://bugzilla.bioperl.org/
|
|
|
49
|
|
|
50 =head1 AUTHOR - Jason Stajich
|
|
|
51
|
|
|
52 Email jason@bioperl.org
|
|
|
53
|
|
|
54 =head1 APPENDIX
|
|
|
55
|
|
|
56 The rest of the documentation details each of the object
|
|
|
57 methods. Internal methods are usually preceded with a _
|
|
|
58
|
|
|
59 =cut
|
|
|
60
|
|
|
61 # Let the code begin...
|
|
|
62
|
|
|
63 package Bio::LocationI;
|
|
|
64 use vars qw(@ISA $coord_policy);
|
|
|
65 use strict;
|
|
|
66
|
|
|
67 use Bio::RangeI;
|
|
|
68 use Bio::Location::WidestCoordPolicy;
|
|
|
69 use Carp;
|
|
|
70
|
|
|
71 @ISA = qw(Bio::RangeI);
|
|
|
72
|
|
|
73 BEGIN {
|
|
|
74 $coord_policy = Bio::Location::WidestCoordPolicy->new();
|
|
|
75 }
|
|
|
76
|
|
|
77 =head2 location_type
|
|
|
78
|
|
|
79 Title : location_type
|
|
|
80 Usage : my $location_type = $location->location_type();
|
|
|
81 Function: Get location type encoded as text
|
|
|
82 Returns : string ('EXACT', 'WITHIN', 'BETWEEN')
|
|
|
83 Args : none
|
|
|
84
|
|
|
85 =cut
|
|
|
86
|
|
|
87 sub location_type {
|
|
|
88 my ($self,@args) = @_;
|
|
|
89 $self->throw_not_implemented();
|
|
|
90 }
|
|
|
91
|
|
|
92 =head2 start
|
|
|
93
|
|
|
94 Title : start
|
|
|
95 Usage : $start = $location->start();
|
|
|
96 Function: Get the start coordinate of this location as defined by
|
|
|
97 the currently active coordinate computation policy. In
|
|
|
98 simple cases, this will return the same number as
|
|
|
99 min_start() and max_start(), in more ambiguous cases like
|
|
|
100 fuzzy locations the number may be equal to one or neither
|
|
|
101 of both.
|
|
|
102
|
|
|
103 We override this here from RangeI in order to delegate
|
|
|
104 'get' to a L<Bio::Location::CoordinatePolicy> implementing
|
|
|
105 object. Implementing classes may also wish to provide
|
|
|
106 'set' functionality, in which case they *must* override
|
|
|
107 this method. The implementation provided here will throw
|
|
|
108 an exception if called with arguments.
|
|
|
109
|
|
|
110 Returns : A positive integer value.
|
|
|
111 Args : none
|
|
|
112
|
|
|
113 See L<Bio::Location::CoordinatePolicy> for more information
|
|
|
114
|
|
|
115 =cut
|
|
|
116
|
|
|
117 sub start {
|
|
|
118 my ($self,@args) = @_;
|
|
|
119
|
|
|
120 # throw if @args means that we don't support updating information
|
|
|
121 # in the interface but will delegate to the coordinate policy object
|
|
|
122 # for interpreting the 'start' value
|
|
|
123
|
|
|
124 $self->throw_not_implemented if @args;
|
|
|
125 return $self->coordinate_policy()->start($self);
|
|
|
126 }
|
|
|
127
|
|
|
128 =head2 end
|
|
|
129
|
|
|
130 Title : end
|
|
|
131 Usage : $end = $location->end();
|
|
|
132 Function: Get the end coordinate of this location as defined by the
|
|
|
133 currently active coordinate computation policy. In simple
|
|
|
134 cases, this will return the same number as min_end() and
|
|
|
135 max_end(), in more ambiguous cases like fuzzy locations
|
|
|
136 the number may be equal to one or neither of both.
|
|
|
137
|
|
|
138 We override this here from Bio::RangeI in order to delegate
|
|
|
139 'get' to a L<Bio::Location::CoordinatePolicy> implementing
|
|
|
140 object. Implementing classes may also wish to provide
|
|
|
141 'set' functionality, in which case they *must* override
|
|
|
142 this method. The implementation provided here will throw
|
|
|
143 an exception if called with arguments.
|
|
|
144
|
|
|
145 Returns : A positive integer value.
|
|
|
146 Args : none
|
|
|
147
|
|
|
148 See L<Bio::Location::CoordinatePolicy> and L<Bio::RangeI> for more
|
|
|
149 information
|
|
|
150
|
|
|
151 =cut
|
|
|
152
|
|
|
153 sub end {
|
|
|
154 my ($self,@args) = @_;
|
|
|
155
|
|
|
156 # throw if @args means that we don't support updating information
|
|
|
157 # in the interface but will delegate to the coordinate policy object
|
|
|
158 # for interpreting the 'end' value
|
|
|
159 $self->throw_not_implemented if @args;
|
|
|
160 return $self->coordinate_policy()->end($self);
|
|
|
161 }
|
|
|
162
|
|
|
163 =head2 min_start
|
|
|
164
|
|
|
165 Title : min_start
|
|
|
166 Usage : my $minstart = $location->min_start();
|
|
|
167 Function: Get minimum starting point of feature.
|
|
|
168
|
|
|
169 Note that an implementation must not call start() in this method.
|
|
|
170
|
|
|
171 Returns : integer or undef if no minimum starting point.
|
|
|
172 Args : none
|
|
|
173
|
|
|
174 =cut
|
|
|
175
|
|
|
176 sub min_start {
|
|
|
177 my($self) = @_;
|
|
|
178 $self->throw_not_implemented();
|
|
|
179 }
|
|
|
180
|
|
|
181 =head2 max_start
|
|
|
182
|
|
|
183 Title : max_start
|
|
|
184 Usage : my $maxstart = $location->max_start();
|
|
|
185 Function: Get maximum starting point of feature.
|
|
|
186
|
|
|
187 Note that an implementation must not call start() in this method
|
|
|
188 unless start() is overridden such as not to delegate to the
|
|
|
189 coordinate computation policy object.
|
|
|
190
|
|
|
191 Returns : integer or undef if no maximum starting point.
|
|
|
192 Args : none
|
|
|
193
|
|
|
194 =cut
|
|
|
195
|
|
|
196 sub max_start {
|
|
|
197 my($self) = @_;
|
|
|
198 $self->throw_not_implemented();
|
|
|
199 }
|
|
|
200
|
|
|
201 =head2 start_pos_type
|
|
|
202
|
|
|
203 Title : start_pos_type
|
|
|
204 Usage : my $start_pos_type = $location->start_pos_type();
|
|
|
205 Function: Get start position type encoded as text
|
|
|
206
|
|
|
207 Known valid values are 'BEFORE' (<5..100), 'AFTER' (>5..100),
|
|
|
208 'EXACT' (5..100), 'WITHIN' ((5.10)..100), 'BETWEEN', (5^6), with
|
|
|
209 their meaning best explained by their GenBank/EMBL location string
|
|
|
210 encoding in brackets.
|
|
|
211
|
|
|
212 Returns : string ('BEFORE', 'AFTER', 'EXACT','WITHIN', 'BETWEEN')
|
|
|
213 Args : none
|
|
|
214
|
|
|
215 =cut
|
|
|
216
|
|
|
217 sub start_pos_type {
|
|
|
218 my($self) = @_;
|
|
|
219 $self->throw_not_implemented();
|
|
|
220 }
|
|
|
221
|
|
|
222 =head2 min_end
|
|
|
223
|
|
|
224 Title : min_end
|
|
|
225 Usage : my $minend = $location->min_end();
|
|
|
226 Function: Get minimum ending point of feature.
|
|
|
227
|
|
|
228 Note that an implementation must not call end() in this method
|
|
|
229 unless end() is overridden such as not to delegate to the
|
|
|
230 coordinate computation policy object.
|
|
|
231
|
|
|
232 Returns : integer or undef if no minimum ending point.
|
|
|
233 Args : none
|
|
|
234
|
|
|
235 =cut
|
|
|
236
|
|
|
237 sub min_end {
|
|
|
238 my($self) = @_;
|
|
|
239 $self->throw_not_implemented();
|
|
|
240 }
|
|
|
241
|
|
|
242 =head2 max_end
|
|
|
243
|
|
|
244 Title : max_end
|
|
|
245 Usage : my $maxend = $location->max_end();
|
|
|
246 Function: Get maximum ending point of feature.
|
|
|
247
|
|
|
248 Note that an implementation must not call end() in this method
|
|
|
249 unless end() is overridden such as not to delegate to the
|
|
|
250 coordinate computation policy object.
|
|
|
251
|
|
|
252 Returns : integer or undef if no maximum ending point.
|
|
|
253 Args : none
|
|
|
254
|
|
|
255 =cut
|
|
|
256
|
|
|
257 sub max_end {
|
|
|
258 my($self) = @_;
|
|
|
259 $self->throw_not_implemented();
|
|
|
260 }
|
|
|
261
|
|
|
262 =head2 end_pos_type
|
|
|
263
|
|
|
264 Title : end_pos_type
|
|
|
265 Usage : my $end_pos_type = $location->end_pos_type();
|
|
|
266 Function: Get end position encoded as text.
|
|
|
267
|
|
|
268 Known valid values are 'BEFORE' (5..<100), 'AFTER' (5..>100),
|
|
|
269 'EXACT' (5..100), 'WITHIN' (5..(90.100)), 'BETWEEN', (5^6), with
|
|
|
270 their meaning best explained by their GenBank/EMBL location string
|
|
|
271 encoding in brackets.
|
|
|
272
|
|
|
273 Returns : string ('BEFORE', 'AFTER', 'EXACT','WITHIN', 'BETWEEN')
|
|
|
274 Args : none
|
|
|
275
|
|
|
276 =cut
|
|
|
277
|
|
|
278 sub end_pos_type {
|
|
|
279 my($self) = @_;
|
|
|
280 $self->throw_not_implemented();
|
|
|
281 }
|
|
|
282
|
|
|
283 =head2 seq_id
|
|
|
284
|
|
|
285 Title : seq_id
|
|
|
286 Usage : my $seqid = $location->seq_id();
|
|
|
287 Function: Get/Set seq_id that location refers to
|
|
|
288 Returns : seq_id (a string)
|
|
|
289 Args : [optional] seq_id value to set
|
|
|
290
|
|
|
291 =cut
|
|
|
292
|
|
|
293 sub seq_id {
|
|
|
294 my ($self, $seqid) = @_;
|
|
|
295 if( defined $seqid ) {
|
|
|
296 $self->{'_seqid'} = $seqid;
|
|
|
297 }
|
|
|
298 return $self->{'_seqid'};
|
|
|
299 }
|
|
|
300
|
|
|
301 =head2 is_remote
|
|
|
302
|
|
|
303 Title : is_remote
|
|
|
304 Usage : $is_remote_loc = $loc->is_remote()
|
|
|
305 Function: Whether or not a location is a remote location.
|
|
|
306
|
|
|
307 A location is said to be remote if it is on a different
|
|
|
308 'object' than the object which 'has' this
|
|
|
309 location. Typically, features on a sequence will sometimes
|
|
|
310 have a remote location, which means that the location of
|
|
|
311 the feature is on a different sequence than the one that is
|
|
|
312 attached to the feature. In such a case, $loc->seq_id will
|
|
|
313 be different from $feat->seq_id (usually they will be the
|
|
|
314 same).
|
|
|
315
|
|
|
316 While this may sound weird, it reflects the location of the
|
|
|
317 kind of AB18375:450-900 which can be found in GenBank/EMBL
|
|
|
318 feature tables.
|
|
|
319
|
|
|
320 Example :
|
|
|
321 Returns : TRUE if the location is a remote location, and FALSE otherwise
|
|
|
322 Args :
|
|
|
323
|
|
|
324
|
|
|
325 =cut
|
|
|
326
|
|
|
327 sub is_remote{
|
|
|
328 shift->throw_not_implemented();
|
|
|
329 }
|
|
|
330
|
|
|
331 =head2 coordinate_policy
|
|
|
332
|
|
|
333 Title : coordinate_policy
|
|
|
334 Usage : $policy = $location->coordinate_policy();
|
|
|
335 $location->coordinate_policy($mypolicy); # set may not be possible
|
|
|
336 Function: Get the coordinate computing policy employed by this object.
|
|
|
337
|
|
|
338 See L<Bio::Location::CoordinatePolicyI> for documentation
|
|
|
339 about the policy object and its use.
|
|
|
340
|
|
|
341 The interface *does not* require implementing classes to
|
|
|
342 accept setting of a different policy. The implementation
|
|
|
343 provided here does, however, allow to do so.
|
|
|
344
|
|
|
345 Implementors of this interface are expected to initialize
|
|
|
346 every new instance with a
|
|
|
347 L<Bio::Location::CoordinatePolicyI> object. The
|
|
|
348 implementation provided here will return a default policy
|
|
|
349 object if none has been set yet. To change this default
|
|
|
350 policy object call this method as a class method with an
|
|
|
351 appropriate argument. Note that in this case only
|
|
|
352 subsequently created Location objects will be affected.
|
|
|
353
|
|
|
354 Returns : A L<Bio::Location::CoordinatePolicyI> implementing object.
|
|
|
355 Args : On set, a L<Bio::Location::CoordinatePolicyI> implementing object.
|
|
|
356
|
|
|
357 See L<Bio::Location::CoordinatePolicyI> for more information
|
|
|
358
|
|
|
359
|
|
|
360 =cut
|
|
|
361
|
|
|
362 sub coordinate_policy {
|
|
|
363 my ($self, $policy) = @_;
|
|
|
364
|
|
|
365 if(defined($policy)) {
|
|
|
366 if(! $policy->isa('Bio::Location::CoordinatePolicyI')) {
|
|
|
367 $self->throw("Object of class ".ref($policy)." does not implement".
|
|
|
368 " Bio::Location::CoordinatePolicyI");
|
|
|
369 }
|
|
|
370 if(ref($self)) {
|
|
|
371 $self->{'_coordpolicy'} = $policy;
|
|
|
372 } else {
|
|
|
373 # called as class method
|
|
|
374 $coord_policy = $policy;
|
|
|
375 }
|
|
|
376 }
|
|
|
377 return (ref($self) && exists($self->{'_coordpolicy'}) ?
|
|
|
378 $self->{'_coordpolicy'} : $coord_policy);
|
|
|
379 }
|
|
|
380
|
|
|
381 =head2 to_FTstring
|
|
|
382
|
|
|
383 Title : to_FTstring
|
|
|
384 Usage : my $locstr = $location->to_FTstring()
|
|
|
385 Function: returns the FeatureTable string of this location
|
|
|
386 Returns : string
|
|
|
387 Args : none
|
|
|
388
|
|
|
389 =cut
|
|
|
390
|
|
|
391 sub to_FTstring {
|
|
|
392 my($self) = @_;
|
|
|
393 $self->throw_not_implemented();
|
|
|
394 }
|
|
|
395
|
|
|
396 =head2 each_Location
|
|
|
397
|
|
|
398 Title : each_Location
|
|
|
399 Usage : @locations = $locObject->each_Location($order);
|
|
|
400 Function: Conserved function call across Location:: modules - will
|
|
|
401 return an array containing the component Location(s) in
|
|
|
402 that object, regardless if the calling object is itself a
|
|
|
403 single location or one containing sublocations.
|
|
|
404 Returns : an array of Bio::LocationI implementing objects
|
|
|
405 Args : Optional sort order to be passed to sub_Location() for Splits
|
|
|
406
|
|
|
407 =cut
|
|
|
408
|
|
|
409 sub each_Location {
|
|
|
410 my ($self,@args) = @_;
|
|
|
411 $self->throw_not_implemented();
|
|
|
412 }
|
|
|
413
|
|
|
414 1;
|
|
|
415
|
