Bio/Seq/QualI.pm

filter: Statementstmt 13.7% 12 / 87 Branchbran 0.0% 0 / 34 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 23.5% 4 / 17 Podpod 100% 13 / 13 totaltotal 19.2% 29 / 151 CC 18 SCAR 25.8
CC
18
Cov
10%
trunc
42.0
_attempt_to_load_Seq
20.0
qual
6.0
CRAP 13.2
« Bio/DB/Qual.pm ↑ Summary Bio/OntologyIO/obo.pm »
1 #
2 # BioPerl module for Bio::Seq::QualI
3 #
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
5 #
6 # Cared for by Chad Matsalla <bioinformatics@dieselwurks.com
7 #
8 # Copyright Chad Matsalla
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::Seq::QualI - Interface definition for a Bio::Seq::Qual
17  
18 =head1 SYNOPSIS
19  
20 # get a Bio::Seq::Qual compliant object somehow
21  
22 # to test this is a seq object
23  
24 $obj->isa("Bio::Seq::QualI")
25 || $obj->throw("$obj does not implement the Bio::Seq::QualI interface");
26  
27 # accessors
28  
29 $string = $obj->qual();
30 $substring = $obj->subqual(12,50);
31 $display = $obj->display_id(); # for human display
32 $id = $obj->primary_id(); # unique id for this object,
33 # implementation defined
34 $unique_key= $obj->accession_number();
35 # unique biological id
36  
37  
38  
39 =head1 DESCRIPTION
40  
41 This object defines an abstract interface to basic quality
42 information. PrimaryQual is an object just for the quality and its
43 name(s), nothing more. There is a pure perl implementation of this in
44 Bio::Seq::PrimaryQual. If you just want to use Bio::Seq::PrimaryQual
45 objects, then please read that module first. This module defines the
46 interface, and is of more interest to people who want to wrap their
47 own Perl Objects/RDBs/FileSystems etc in way that they "are" bioperl
48 quality objects, even though it is not using Perl to store the
49 sequence etc.
50  
51 This interface defines what bioperl consideres necessary to "be" a
52 sequence of qualities, without providing an implementation of
53 this. (An implementation is provided in Bio::Seq::PrimaryQual). If you
54 want to provide a Bio::Seq::PrimaryQual 'compliant' object which in
55 fact wraps another object/database/out-of-perl experience, then this
56 is the correct thing to wrap, generally by providing a wrapper class
57 which would inherit from your object and this Bio::Seq::QualI
58 interface. The wrapper class then would have methods lists in the
59 "Implementation Specific Functions" which would provide these methods
60 for your object.
61  
62  
63 =head1 FEEDBACK
64  
65 =head2 Mailing Lists
66  
67 User feedback is an integral part of the evolution of this and other
68 Bioperl modules. Send your comments and suggestions preferably to one
69 of the Bioperl mailing lists. Your participation is much appreciated.
70  
71 bioperl-l@bioperl.org - General discussion
72 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
73  
74 =head2 Support
75  
76 Please direct usage questions or support issues to the mailing list:
77  
78 I<bioperl-l@bioperl.org>
79  
80 rather than to the module maintainer directly. Many experienced and
81 reponsive experts will be able look at the problem and quickly
82 address it. Please include a thorough description of the problem
83 with code and data examples if at all possible.
84  
85 =head2 Reporting Bugs
86  
87 Report bugs to the Bioperl bug tracking system to help us keep track
88 the bugs and their resolution. Bug reports can be submitted via the
89 web:
90  
91 https://github.com/bioperl/bioperl-live/issues
92  
93 =head1 AUTHOR - Chad Matsalla
94  
95 This module is heavily based on Bio::Seq::PrimarySeq and is modeled after
96 or outright copies sections of it. Thanks Ewan!
97  
98 Email bioinformatics@dieselwurks.com
99  
100 =head1 APPENDIX
101  
102 The rest of the documentation details each of the object methods.
103 Internal methods are usually preceded with a _
104  
105 =cut
106  
107  
108 # Let the code begin...
109  
110  
111 package Bio::Seq::QualI;
112 9 $Bio::Seq::QualI::VERSION = '1.7.8';
113 9 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
114 9 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
115  
116 9 ▶use base qw(Bio::Root::RootI);
Subroutine BEGIN: called CC=1 SCAR=0.0
117  
118 =head1 Implementation Specific Functions
119  
120 These functions are the ones that a specific implementation must
121 define.
122  
123 =head2 qual()
124  
125 Title : qual()
126 Usage : @quality_values = @{$obj->qual()};
127 Function: Returns the quality as a reference to an array containing the
128 quality values. The individual elements of the quality array are
129 not validated and can be any numeric value.
130 Returns : A reference to an array.
131 Status :
132  
133 =cut
134  
135 0 ▶sub qual {
Subroutine qual: not called CC=2 SCAR=17.9
Pod documented
136 0 my ($self) = @_;
137 0 ▶ if( $self->can('throw') ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->can('throw')) { } 0 0 0
138 0 $self->throw("Bio::Seq::QualI definition of qual - implementing class did not provide this method");
139 } else {
140 0 confess("Bio::Seq::QualI definition of qual - implementing class did not provide this method");
141 }
142 }
143  
144 =head2 subqual($start,$end)
145  
146 Title : subqual($start,$end)
147 Usage : @subset_of_quality_values = @{$obj->subseq(10,40)};
148 Function: returns the quality values from $start to $end, where the
149 first value is 1 and the number is inclusive, ie 1-2 are the first
150 two bases of the sequence. Start cannot be larger than end but can
151 be equal.
152 Returns : A reference to an array.
153 Args : a start position and an end position
154  
155  
156 =cut
157  
158 0 ▶sub subqual {
Subroutine subqual: not called CC=2 SCAR=17.9
Pod documented
159 0 my ($self) = @_;
160  
161 0 ▶ if( $self->can('throw') ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->can('throw')) { } 0 0 0
162 0 $self->throw("Bio::Seq::QualI definition of subqual - implementing class did not provide this method");
163 } else {
164 0 confess("Bio::Seq::QualI definition of subqual - implementing class did not provide this method");
165 }
166  
167 }
168  
169 =head2 display_id()
170  
171 Title : display_id()
172 Usage : $id_string = $obj->display_id() _or_
173 $id_string = $obj->display_id($new_display_id);
174 Function: Returns the display id, aka the common name of the Quality
175 object.
176 The semantics of this is that it is the most likely string to be
177 used as an identifier of the quality sequence, and likely to have
178 "human" readability. The id is equivalent to the ID field of the
179 GenBank/EMBL databanks and the id field of the Swissprot/sptrembl
180 database. In fasta format, the >(\S+) is presumed to be the id,
181 though some people overload the id to embed other information.
182 Bioperl does not use any embedded information in the ID field,
183 and people are encouraged to use other mechanisms (accession field
184 for example, or extending the sequence object) to solve this.
185 Notice that $seq->id() maps to this function, mainly for
186 legacy/convience issues
187 Returns : A string
188 Args : If an arg is provided, it will replace the existing display_id
189 in the object.
190  
191  
192 =cut
193  
194 0 ▶sub display_id {
Subroutine display_id: not called CC=2 SCAR=17.9
Pod documented
195 0 my ($self) = @_;
196  
197 0 ▶ if( $self->can('throw') ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->can('throw')) { } 0 0 0
198 0 $self->throw("Bio::Seq::QualI definition of id - implementing class did not provide this method");
199 } else {
200 0 confess("Bio::Seq::QualI definition of id - implementing class did not provide this method");
201 }
202  
203 }
204  
205  
206 =head2 accession_number()
207  
208 Title : accession_number()
209 Usage : $unique_biological_key = $obj->accession_number(); _or_
210 $unique_biological_key = $obj->accession_number($new_acc_num);
211 Function: Returns the unique biological id for a sequence, commonly
212 called the accession_number. For sequences from established
213 databases, the implementors should try to use the correct
214 accession number. Notice that primary_id() provides the unique id
215 for the implementation, allowing multiple objects to have the same
216 accession number in a particular implementation. For sequences
217 with no accession number, this method should return "unknown".
218 Returns : A string.
219 Args : If an arg is provided, it will replace the existing
220 accession_number in the object.
221  
222 =cut
223  
224 0 ▶sub accession_number {
Subroutine accession_number: not called CC=2 SCAR=17.9
Pod documented
225 0 my ($self,@args) = @_;
226  
227 0 ▶ if( $self->can('throw') ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->can('throw')) { } 0 0 0
228 0 $self->throw("Bio::Seq::QualI definition of seq - implementing class did not provide this method");
229 } else {
230 0 confess("Bio::Seq::QualI definition of seq - implementing class did not provide this method");
231 }
232  
233 }
234  
235  
236  
237 =head2 primary_id()
238  
239 Title : primary_id()
240 Usage : $unique_implementation_key = $obj->primary_id(); _or_
241 $unique_implementation_key = $obj->primary_id($new_prim_id);
242 Function: Returns the unique id for this object in this implementation.
243 This allows implementations to manage their own object ids in a
244 way the implementation can control clients can expect one id to
245 map to one object. For sequences with no accession number, this
246 method should return a stringified memory location.
247 Returns : A string
248 Args : If an arg is provided, it will replace the existing
249 primary_id in the object.
250  
251 =cut
252  
253 0 ▶sub primary_id {
Subroutine primary_id: not called CC=2 SCAR=17.9
Pod documented
254 0 my ($self,@args) = @_;
255  
256 0 ▶ if( $self->can('throw') ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->can('throw')) { } 0 0 0
257 0 $self->throw("Bio::Seq::QualI definition of qual - implementing class did not provide this method");
258 } else {
259 0 confess("Bio::Seq::QualI definition of qual - implementing class did not provide this method");
260 }
261  
262 }
263  
264  
265 =head2 can_call_new()
266  
267 Title : can_call_new()
268 Usage : if( $obj->can_call_new ) {
269 $newobj = $obj->new( %param );
270 }
271 Function: can_call_new returns 1 or 0 depending on whether an
272 implementation allows new constructor to be called. If a new
273 constructor is allowed, then it should take the followed hashed
274 constructor list.
275 $myobject->new( -qual => $quality_as_string,
276 -display_id => $id,
277 -accession_number => $accession,
278 );
279 Example :
280 Returns : 1 or 0
281 Args :
282  
283  
284 =cut
285  
286 0 ▶sub can_call_new{
Subroutine can_call_new: not called CC=1 SCAR=6.9
Pod documented
287 0 my ($self,@args) = @_;
288 # we default to 0 here
289 0 return 0;
290 }
291  
292 =head2 qualat($position)
293  
294 Title : qualat($position)
295 Usage : $quality = $obj->qualat(10);
296 Function: Return the quality value at the given location, where the
297 first value is 1 and the number is inclusive, ie 1-2 are the first
298 two bases of the sequence. Start cannot be larger than end but can
299 be equal.
300 Returns : A scalar.
301 Args : A position.
302  
303 =cut
304  
305 0 ▶sub qualat {
Subroutine qualat: not called CC=2 SCAR=17.9
Pod documented
306 0 my ($self,$value) = @_;
307 0 ▶ if( $self->can('warn') ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->can('warn')) { } 0 0 0
308 0 $self->warn("Bio::Seq::QualI definition of qualat - implementing class did not provide this method");
309 } else {
310 0 warn("Bio::Seq::QualI definition of qualat - implementing class did not provide this method");
311 }
312 0 return '';
313 }
314  
315 =head1 Optional Implementation Functions
316  
317 The following functions rely on the above functions. A implementing
318 class does not need to provide these functions, as they will be
319 provided by this class, but is free to override these functions.
320  
321 All of revcom(), trunc(), and translate() create new sequence
322 objects. They will call new() on the class of the sequence object
323 instance passed as argument, unless can_call_new() returns FALSE. In
324 the latter case a Bio::PrimarySeq object will be created. Implementors
325 which really want to control how objects are created (eg, for object
326 persistence over a database, or objects in a CORBA framework), they
327 are encouraged to override these methods
328  
329 =head2 revcom
330  
331 Title : revcom
332 Usage : @rev = @{$qual->revcom()};
333 Function: Produces a new Bio::Seq::QualI implementing object which
334 is reversed from the original quality array.
335 The id is the same id as the original sequence, and the accession number
336 is also identical. If someone wants to track that this sequence has
337 been reversed, it needs to define its own extensions
338  
339 To do an inplace edit of an object you can go:
340  
341 $qual = $qual->revcom();
342  
343 This of course, causes Perl to handle the garbage collection of the old
344 object, but it is roughly speaking as efficient as an inplace edit.
345 Returns : A new (fresh) Bio::Seq::PrimaryQualI object
346 Args : none
347  
348 =cut
349  
350 0 ▶sub revcom{
Subroutine revcom: not called CC=2 SCAR=17.9
Pod documented
351 0 my ($self) = @_;
352 # this is the cleanest way
353 0 my @qualities = @{$self->qual()};
354 0 my @reversed_qualities = reverse(@qualities);
355 0 my $seqclass;
356 0 ▶ if($self->can_call_new()) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->can_call_new) { } 0 0 0
357 0 $seqclass = ref($self);
358 } else {
359 0 $seqclass = 'Bio::Seq::PrimaryQual';
360 # Wassat?
361 # $self->_attempt_to_load_Seq();
362 }
363 # the \@reverse_qualities thing works simply because I will it to work.
364 0 my $out = $seqclass->new( '-qual' => \@reversed_qualities,
365 '-display_id' => $self->display_id,
366 '-accession_number' => $self->accession_number,
367 '-desc' => $self->desc()
368 );
369 0 return $out;
370 }
371  
372 =head2 trunc()
373  
374 Title : trunc
375 Usage : $subseq = $myseq->trunc(10,100);
376 Function: Provides a truncation of a sequence,
377 Returns : a fresh Bio::Seq::QualI implementing object
378 Args : Two integers denoting first and last base of the sub-sequence.
379  
380  
381 =cut
382  
383 0 ▶sub trunc {
Subroutine trunc: not called CC=6 SCAR=37.4
Pod documented
384 0 my ($self,$start,$end) = @_;
385  
386 0 ▶ if( !$end ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($end) 0 0 0
387 0 ▶ if( $self->can('throw') ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->can('throw')) { } 0 0 0
388 0 $self->throw("trunc start,end");
389 } else {
390 0 confess("[$self] trunc start,end");
391 }
392 }
393  
394 0 ▶ if( $end < $start ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($end < $start) 0 0 0
395 0 ▶ if( $self->can('throw') ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->can('throw')) { } 0 0 0
396 0 $self->throw("$end is smaller than $start. if you want to truncated and reverse complement, you must call trunc followed by revcom. Sorry.");
397 } else {
398 0 confess("[$self] $end is smaller than $start. If you want to truncated and reverse complement, you must call trunc followed by revcom. Sorry.");
399 }
400 }
401  
402 0 my $r_qual = $self->subqual($start,$end);
403  
404 0 my $seqclass;
405 0 ▶ if($self->can_call_new()) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->can_call_new) { } 0 0 0
406 0 $seqclass = ref($self);
407 } else {
408 0 $seqclass = 'Bio::Seq::PrimaryQual';
409 # wassat?
410 # $self->_attempt_to_load_Seq();
411 }
412 0 my $out = $seqclass->new( '-qual' => $r_qual,
413 '-display_id' => $self->display_id,
414 '-accession_number' => $self->accession_number,
415 '-desc' => $self->desc()
416 );
417 0 return $out;
418 }
419  
420  
421 =head2 translate()
422  
423 Title : translate()
424 Usage : $protein_seq_obj = $dna_seq_obj->translate
425 #if full CDS expected:
426 $protein_seq_obj = $cds_seq_obj->translate(undef,undef,undef,undef,1);
427 Function: Completely useless in this interface.
428 Returns : Nothing.
429 Args : Nothing.
430  
431 =cut
432  
433  
434 1 ▶sub translate {
Subroutine translate: called CC=1 SCAR=0.0
Pod documented
435 1 return 0;
436 }
437  
438  
439 =head2 id()
440  
441 Title : id()
442 Usage : $id = $qual->id()
443 Function: ID of the quality. This should normally be (and actually is in
444 the implementation provided here) just a synonym for display_id().
445 Example :
446 Returns : A string.
447 Args :
448  
449  
450 =cut
451  
452 0 ▶sub id {
Subroutine id: not called CC=1 SCAR=6.9
Pod documented
453 0 my ($self)= @_;
454 0 return $self->display_id();
455 }
456  
457 =head2 length()
458  
459 Title : length()
460 Usage : $length = $qual->length();
461 Function: Return the length of the array holding the quality values.
462 Under most circumstances, this should match the number of quality
463 values but no validation is done when the PrimaryQual object is
464 constructed and non-digits could be put into this array. Is this a
465 bug? Just enough rope...
466 Returns : A scalar (the number of elements in the quality array).
467 Args : None.
468  
469 =cut
470  
471 0 ▶sub length {
Subroutine length: not called CC=2 SCAR=17.9
Pod documented
472 0 my ($self)= @_;
473 0 ▶ if( $self->can('throw') ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->can('throw')) { } 0 0 0
474 0 $self->throw("Bio::Seq::QualI definition of length - implementing class did not provide this method");
475 } else {
476 0 confess("Bio::Seq::QualI definition of length - implementing class did not provide this method");
477 }
478 }
479  
480  
481 =head2 desc()
482  
483 Title : desc()
484 Usage : $qual->desc($newval);
485 $description = $seq->desc();
486 Function: Get/set description text for a qual object
487 Example :
488 Returns : value of desc
489 Args : newvalue (optional)
490  
491 =cut
492  
493 0 ▶sub desc {
Subroutine desc: not called CC=2 SCAR=17.9
Pod documented
494 0 my ($self,$value) = @_;
495 0 ▶ if( $self->can('warn') ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->can('warn')) { } 0 0 0
496 0 $self->warn("Bio::Seq::QualI definition of desc - implementing class did not provide this method");
497 } else {
498 0 warn("Bio::Seq::QualI definition of desc - implementing class did not provide this method");
499 }
500 0 return '';
501 }
502  
503 # These methods are here for backward compatibility with the old, 0.5
504 # Seq objects. They all throw warnings that someone is using a
505 # deprecated method, and may eventually be removed completely from
506 # this object. However, they are important to ease the transition from
507 # the old system.
508  
509 =head1 Private functions
510  
511 These are some private functions for the PrimarySeqI interface. You do not
512 need to implement these functions
513  
514 =head2 _attempt_to_load_Seq
515  
516 Title : _attempt_to_load_Seq
517 Usage :
518 Function:
519 Example :
520 Returns :
521 Args :
522  
523  
524 =cut
525  
526 0 ▶sub _attempt_to_load_Seq{
Subroutine _attempt_to_load_Seq: not called CC=4 SCAR=30.0
527 0 my ($self) = @_;
528  
529 0 ▶ if( $main::{'Bio::Seq::PrimaryQual'} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($main::main::{'Bio::Seq::PrimaryQual'}) { } 0 0 0
530 0 return 1;
531 } else {
532 0 eval {
533 0 require Bio::Seq::PrimaryQual;
534 };
535 0 ▶ if( $@ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 0 0
536 0 ▶ if( $self->can('throw') ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->can('throw')) { } 0 0 0
537 0 $self->throw("Bio::Seq::PrimaryQual could not be loaded for $self\nThis indicates that you are using Bio::Seq::PrimaryQualI without Bio::Seq::PrimaryQual loaded and without providing a complete solution\nThe most likely problem is that there has been a misconfiguration of the bioperl environment\nActual exception\n\n$@\n");
538 } else {
539 0 confess("Bio::Seq::PrimarySeq could not be loaded for $self\nThis indicates that you are usnig Bio::Seq::PrimaryQualI without Bio::Seq::PrimaryQual loaded and without providing a complete solution\nThe most likely problem is that there has been a misconfiguration of the bioperl environment\nActual exception\n\n$@\n");
540 }
541 0 return 0;
542 }
543 0 return 1;
544 }
545  
546 }
547  
548 9 1;
« Bio/DB/Qual.pm ↑ Summary Bio/OntologyIO/obo.pm »