Bio/Das/SegmentI.pm

filter: Statementstmt 25.0% 9 / 36 Branchbran 0.0% 0 / 8 Conditioncond 0.0% 0 / 3 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 9.5% 2 / 21 Podpod 84.2% 16 / 19 totaltotal 30.3% 27 / 89 CC 6 SCAR 13.9
CC
6
Cov
19%
get_feature_stream
12.0
overlapping_features
6.0
contained_features
6.0
CRAP 4.0
« Bio/Tools/Genomewise.pm ↑ Summary Bio/Tools/Match.pm »
1 #
2 # BioPerl module for Bio::Das::SegmentI
3 #
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
5 #
6 # Cared for by Lincoln Stein <lstein@cshl.org>
7 #
8 # Copyright Lincoln Stein
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::Das::SegmentI - DAS-style access to a feature database
17  
18 =head1 SYNOPSIS
19  
20 # Get a Bio::Das::SegmentI object from a Bio::DasI database...
21  
22 $segment = $das->segment(-name=>'Landmark',
23 -start=>$start,
24 -end => $end);
25  
26 @features = $segment->overlapping_features(-type=>['type1','type2']);
27 # each feature is a Bio::SeqFeatureI-compliant object
28  
29 @features = $segment->contained_features(-type=>['type1','type2']);
30  
31 @features = $segment->contained_in(-type=>['type1','type2']);
32  
33 $stream = $segment->get_feature_stream(-type=>['type1','type2','type3'];
34 while (my $feature = $stream->next_seq) {
35 # do something with feature
36 }
37  
38 $count = $segment->features_callback(-type=>['type1','type2','type3'],
39 -callback => sub { ... { }
40 );
41  
42 =head1 DESCRIPTION
43  
44 Bio::Das::SegmentI is a simplified alternative interface to sequence
45 annotation databases used by the distributed annotation system. In
46 this scheme, the genome is represented as a series of landmarks. Each
47 Bio::Das::SegmentI object ("segment") corresponds to a genomic region
48 defined by a landmark and a start and end position relative to that
49 landmark. A segment is created using the Bio::DasI segment() method.
50  
51 Features can be filtered by the following attributes:
52  
53 1) their location relative to the segment (whether overlapping,
54 contained within, or completely containing)
55  
56 2) their type
57  
58 3) other attributes using tag/value semantics
59  
60 Access to the feature list uses three distinct APIs:
61  
62 1) fetching entire list of features at a time
63  
64 2) fetching an iterator across features
65  
66 3) a callback
67  
68 =head1 FEEDBACK
69  
70 =head2 Mailing Lists
71  
72 User feedback is an integral part of the evolution of this and other
73 Bioperl modules. Send your comments and suggestions preferably to one
74 of the Bioperl mailing lists. Your participation is much appreciated.
75  
76 bioperl-l@bio.perl.org
77  
78 =head2 Support
79  
80 Please direct usage questions or support issues to the mailing list:
81  
82 I<bioperl-l@bioperl.org>
83  
84 rather than to the module maintainer directly. Many experienced and
85 reponsive experts will be able look at the problem and quickly
86 address it. Please include a thorough description of the problem
87 with code and data examples if at all possible.
88  
89 =head2 Reporting Bugs
90  
91 Report bugs to the Bioperl bug tracking system to help us keep track
92 the bugs and their resolution. Bug reports can be submitted via the
93 web:
94  
95 https://github.com/bioperl/bioperl-live/issues
96  
97 =head1 AUTHOR - Lincoln Stein
98  
99 Email lstein@cshl.org
100  
101 =head1 APPENDIX
102  
103 The rest of the documentation details each of the object
104 methods. Internal methods are usually preceded with a _
105  
106 =cut
107  
108 #'
109 # Let the code begin...
110  
111 package Bio::Das::SegmentI;
112 2 $Bio::Das::SegmentI::VERSION = '1.7.8';
113 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
114  
115  
116 # Object preamble - inherits from Bio::Root::RootI;
117 2 ▶use base qw(Bio::Root::RootI);
Subroutine BEGIN: called CC=1 SCAR=0.0
118  
119 =head2 seq_id
120  
121 Title : seq_id
122 Usage : $ref = $s->seq_id
123 Function: return the ID of the landmark
124 Returns : a string
125 Args : none
126 Status : Public
127  
128 =cut
129  
130 0 ▶sub seq_id { shift->throw_not_implemented }
Subroutine seq_id: not called CC=1 SCAR=6.9
Pod documented
131  
132 =head2 display_name
133  
134 Title : seq_name
135 Usage : $ref = $s->seq_name
136 Function: return the human-readable name for the landmark
137 Returns : a string
138 Args : none
139 Status : Public
140  
141 This defaults to the same as seq_id.
142  
143 =cut
144  
145 0 ▶sub display_name { shift->seq_id }
Subroutine display_name: not called CC=1 SCAR=6.9
Pod documented
146  
147 =head2 start
148  
149 Title : start
150 Usage : $s->start
151 Function: start of segment
152 Returns : integer
153 Args : none
154 Status : Public
155  
156 This is a read-only accessor for the start of the segment. Alias
157 to low() for Gadfly compatibility.
158  
159 =cut
160  
161 0 ▶sub start { shift->throw_not_implemented }
Subroutine start: not called CC=1 SCAR=6.9
Pod documented
162 0 ▶sub low { shift->start }
Subroutine low: not called CC=1 SCAR=6.9
Pod undocumented
163  
164 =head2 end
165  
166 Title : end
167 Usage : $s->end
168 Function: end of segment
169 Returns : integer
170 Args : none
171 Status : Public
172  
173 This is a read-only accessor for the end of the segment. Alias to
174 high() for Gadfly compatibility.
175  
176 =cut
177  
178 0 ▶sub end { shift->throw_not_implemented }
Subroutine end: not called CC=1 SCAR=6.9
Pod documented
179 0 ▶sub stop { shift->end }
Subroutine stop: not called CC=1 SCAR=6.9
Pod undocumented
180 0 ▶sub high { shift->end }
Subroutine high: not called CC=1 SCAR=6.9
Pod undocumented
181  
182 =head2 length
183  
184 Title : length
185 Usage : $s->length
186 Function: length of segment
187 Returns : integer
188 Args : none
189 Status : Public
190  
191 Returns the length of the segment. Always a positive number.
192  
193 =cut
194  
195 0 ▶sub length { shift->throw_not_implemented; }
Subroutine length: not called CC=1 SCAR=6.9
Pod documented
196  
197 =head2 seq
198  
199 Title : seq
200 Usage : $s->seq
201 Function: get the sequence string for this segment
202 Returns : a string
203 Args : none
204 Status : Public
205  
206 Returns the sequence for this segment as a simple string.
207  
208 =cut
209  
210 0 ▶sub seq {shift->throw_not_implemented}
Subroutine seq: not called CC=1 SCAR=6.9
Pod documented
211  
212 =head2 ref
213  
214 Title : ref
215 Usage : $ref = $s->ref([$newlandmark])
216 Function: get/set the reference landmark for addressing
217 Returns : a string
218 Args : none
219 Status : Public
220  
221 This method is used to examine/change the reference landmark used to
222 establish the coordinate system. By default, the landmark cannot be
223 changed and therefore this has the same effect as seq_id(). The new
224 landmark might be an ID, or another Das::SegmentI object.
225  
226 =cut
227  
228 0 ▶sub ref { shift->seq_id }
Subroutine ref: not called CC=1 SCAR=6.9
Pod documented
229 2 *refseq = \&ref;
230  
231 =head2 absolute
232  
233 Title : absolute
234 Usage : $s->absolute([$new_value])
235 Function: get/set absolute addressing mode
236 Returns : flag
237 Args : new flag (optional)
238 Status : Public
239  
240 Turn on and off absolute-addressing mode. In absolute addressing
241 mode, coordinates are relative to some underlying "top level"
242 coordinate system (such as a chromosome). ref() returns the identity
243 of the top level landmark, and start() and end() return locations
244 relative to that landmark. In relative addressing mode, coordinates
245 are relative to the landmark sequence specified at the time of segment
246 creation or later modified by the ref() method.
247  
248 The default is to return false and to do nothing in response to
249 attempts to set absolute addressing mode.
250  
251 =cut
252  
253 0 ▶sub absolute { return }
Subroutine absolute: not called CC=1 SCAR=6.9
Pod documented
254  
255 =head2 features
256  
257 Title : features
258 Usage : @features = $s->features(@args)
259 Function: get features that overlap this segment
260 Returns : a list of Bio::SeqFeatureI objects
261 Args : see below
262 Status : Public
263  
264 This method will find all features that intersect the segment in a
265 variety of ways and return a list of Bio::SeqFeatureI objects. The
266 feature locations will use coordinates relative to the reference
267 sequence in effect at the time that features() was called.
268  
269 The returned list can be limited to certain types, attributes or
270 range intersection modes. Types of range intersection are one of:
271  
272 "overlaps" the default
273 "contains" return features completely contained within the segment
274 "contained_in" return features that completely contain the segment
275  
276 Two types of argument lists are accepted. In the positional argument
277 form, the arguments are treated as a list of feature types. In the
278 named parameter form, the arguments are a series of -name=E<gt>value
279 pairs.
280  
281 Argument Description
282 -------- ------------
283  
284 -types An array reference to type names in the format
285 "method:source"
286  
287 -attributes A hashref containing a set of attributes to match
288  
289 -rangetype One of "overlaps", "contains", or "contained_in".
290  
291 -iterator Return an iterator across the features.
292  
293 -callback A callback to invoke on each feature
294  
295 The -attributes argument is a hashref containing one or more
296 attributes to match against:
297  
298 -attributes => { Gene => 'abc-1',
299 Note => 'confirmed' }
300  
301 Attribute matching is simple string matching, and multiple attributes
302 are ANDed together. More complex filtering can be performed using the
303 -callback option (see below).
304  
305 If -iterator is true, then the method returns an object reference that
306 implements the next_seq() method. Each call to next_seq() returns a
307 new Bio::SeqFeatureI object.
308  
309 If -callback is passed a code reference, the code reference will be
310 invoked on each feature returned. The code will be passed two
311 arguments consisting of the current feature and the segment object
312 itself, and must return a true value. If the code returns a false
313 value, feature retrieval will be aborted.
314  
315 -callback and -iterator are mutually exclusive options. If -iterator
316 is defined, then -callback is ignored.
317  
318 NOTE: the following methods all build on top of features(), and do not
319 need to be explicitly implemented.
320  
321 overlapping_features()
322 contained_features()
323 contained_in()
324 get_feature_stream()
325  
326 =cut
327  
328 0 ▶sub features {shift->throw_not_implemented}
Subroutine features: not called CC=1 SCAR=6.9
Pod documented
329  
330 =head2 overlapping_features
331  
332 Title : overlapping_features
333 Usage : @features = $s->overlapping_features(@args)
334 Function: get features that overlap this segment
335 Returns : a list of Bio::SeqFeatureI objects
336 Args : see below
337 Status : Public
338  
339 This method is identical to features() except that it defaults to
340 finding overlapping features.
341  
342 =cut
343  
344 0 ▶sub overlapping_features {
Subroutine overlapping_features: not called CC=2 SCAR=17.9
Pod documented
345 0 my $self = shift;
346 0 ▶ my @args = $_[0] =~ /^-/ ? (@_, -rangetype=>'overlaps')
Branch: 1 branch
BranchTrueFalseTotal
$_[0] =~ /^-/ ? : 0 0 0
347 : (-types=>\@_,-rangetype=>'overlaps');
348 0 $self->features(@args);
349 }
350  
351 =head2 contained_features
352  
353 Title : contained_features
354 Usage : @features = $s->contained_features(@args)
355 Function: get features that are contained in this segment
356 Returns : a list of Bio::SeqFeatureI objects
357 Args : see below
358 Status : Public
359  
360 This method is identical to features() except that it defaults to
361 a range type of 'contained'.
362  
363 =cut
364  
365 0 ▶sub contained_features {
Subroutine contained_features: not called CC=2 SCAR=17.9
Pod documented
366 0 my $self = shift;
367 0 ▶ my @args = $_[0] =~ /^-/ ? (@_, -rangetype=>'contained')
Branch: 1 branch
BranchTrueFalseTotal
$_[0] =~ /^-/ ? : 0 0 0
368 : (-types=>\@_,-rangetype=>'contained');
369 0 $self->features(@args);
370 }
371  
372 =head2 contained_in
373  
374 Title : contained_in
375 Usage : @features = $s->contained_in(@args)
376 Function: get features that contain this segment
377 Returns : a list of Bio::SeqFeatureI objects
378 Args : see below
379 Status : Public
380  
381 This method is identical to features() except that it defaults to
382 a range type of 'contained_in'.
383  
384 =cut
385  
386 0 ▶sub contained_in {
Subroutine contained_in: not called CC=2 SCAR=17.9
Pod documented
387 0 my $self = shift;
388 0 ▶ my @args = $_[0] =~ /^-/ ? (@_, -rangetype=>'contained_in')
Branch: 1 branch
BranchTrueFalseTotal
$_[0] =~ /^-/ ? : 0 0 0
389 : (-types=>\@_,-rangetype=>'contained_in');
390 0 $self->features(@args);
391 }
392  
393 =head2 get_feature_stream
394  
395 Title : get_feature_stream
396 Usage : $iterator = $s->get_feature_stream(@args)
397 Function: get an iterator across the segment
398 Returns : an object that implements next_seq()
399 Args : see below
400 Status : Public
401  
402 This method is identical to features() except that it always generates
403 an iterator.
404  
405 NOTE: This is defined in the interface in terms of features(). You do not
406 have to implement it.
407  
408 =cut
409  
410 0 ▶sub get_feature_stream {
Subroutine get_feature_stream: not called CC=3 SCAR=24.8
Pod documented
411 0 my $self = shift;
412 0 ▶ my @args = defined $_[0] && $_[0] =~ /^-/ ? (@_, -iterator=>1)
Branch: 1 branch
BranchTrueFalseTotal
defined $_[0] && $_[0] =~ /^-/ ? : 0 0 0
Condition0%0/3
defined $_[0] and $_[0] =~ /^-/
!ll&&!rl&&r
000
MC/DC0%0/2
defined $_[0] and $_[0] =~ /^-/
defined $_[0] $_[0] =~ /^-/
Truth table0%0/3
A and B
A= defined $_[0]B= $_[0] =~ /^-/
ABresult
0X0
100
111
413 : (-types=>\@_,-iterator=>1);
414 0 $self->features(@args);
415 }
416  
417 =head2 factory
418  
419 Title : factory
420 Usage : $factory = $s->factory
421 Function: return the segment factory
422 Returns : a Bio::DasI object
423 Args : see below
424 Status : Public
425  
426 This method returns a Bio::DasI object that can be used to fetch
427 more segments. This is typically the Bio::DasI object from which
428 the segment was originally generated.
429  
430 =cut
431  
432 #'
433  
434 0 ▶sub factory {shift->throw_not_implemented}
Subroutine factory: not called CC=1 SCAR=6.9
Pod documented
435  
436 =head2 primary_tag
437  
438 Title : primary_tag
439 Usage : $tag = $s->primary_tag
440 Function: identifies the segment as type "DasSegment"
441 Returns : a string named "DasSegment"
442 Args : none
443 Status : Public, but see below
444  
445 This method provides Bio::Das::Segment objects with a primary_tag()
446 field that identifies them as being of type "DasSegment". This allows
447 the Bio::Graphics engine to render segments just like a feature in order
448 nis way useful.
449  
450 This does not need to be implemented. It is defined by the interface.
451  
452 =cut
453  
454 #'
455  
456 0 ▶sub primary_tag {"DasSegment"}
Subroutine primary_tag: not called CC=1 SCAR=6.9
Pod documented
457  
458 =head2 strand
459  
460 Title : strand
461 Usage : $strand = $s->strand
462 Function: identifies the segment strand as 0
463 Returns : the number 0
464 Args : none
465 Status : Public, but see below
466  
467 This method provides Bio::Das::Segment objects with a strand() field
468 that identifies it as being strandless. This allows the Bio::Graphics
469 engine to render segments just like a feature in order nis way useful.
470  
471 This does not need to be implemented. It is defined by the interface.
472  
473 =cut
474  
475 0 ▶sub strand { 0 }
Subroutine strand: not called CC=1 SCAR=6.9
Pod documented
476  
477 2 1;
« Bio/Tools/Genomewise.pm ↑ Summary Bio/Tools/Match.pm »