Bio/Search/Tiling/TilingI.pm

filter: Statementstmt 34.8% 15 / 43 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 23.8% 5 / 21 Podpod 70.5% 12 / 17 totaltotal 39.5% 32 / 81 CC 1 SCAR 5.7
CC
1
Cov
35%
identities
2.0
num_identical
2.0
conserved
2.0
CRAP 1.8
« Bio/SeqFeature/Gene/NC_Feature.pm ↑ Summary Bio/SearchIO/EventHandlerI.pm »
1 #
2 # BioPerl module for Bio::Search::Tiling::TilingI
3 #
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
5 #
6 # Cared for by Mark A. Jensen <maj@fortinbras.us>
7 #
8 # Copyright Mark A. Jensen
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::Search::Tiling::TilingI - Abstract interface for an HSP tiling module
17  
18 =head1 SYNOPSIS
19  
20 Not used directly. Useful POD here for developers, however.
21  
22 The interface is designed to make the following code conversion as
23 simple as possible:
24  
25 From:
26  
27 # Bio::Search::SearchUtils-based
28 while ( local $_ = $result->next_hit ) {
29 printf( "E-value: %g; Fraction aligned: %f; Number identical: %d\n",
30 $hit->significance, $hit->frac_aligned_query, $hit->num_identical);
31 }
32  
33 To:
34  
35 # TilingI-based
36 while ( local $_ = $result->next_hit ) {
37 my $tiling = Bio::Search::Tiling::MyTiling($_);
38 printf( "E-value: %g; Fraction aligned: %f; Number identical: %d\n",
39 $hit->significance, $tiling->frac_aligned_query, $tiling->num_identical);
40 }
41  
42  
43  
44 =head1 DESCRIPTION
45  
46 This module provides strong suggestions for any intended HSP tiling
47 object implementation. An object subclassing TilingI should override
48 the methods defined here according to their descriptions below.
49  
50 See the section STATISTICS METHODS for hints on implementing methods
51 that are valid across different algorithms and report types.
52  
53 =head1 FEEDBACK
54  
55 =head2 Mailing Lists
56  
57 User feedback is an integral part of the evolution of this and other
58 Bioperl modules. Send your comments and suggestions preferably to
59 the Bioperl mailing list. Your participation is much appreciated.
60  
61 bioperl-l@bioperl.org - General discussion
62 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
63  
64 =head2 Support
65  
66 Please direct usage questions or support issues to the mailing list:
67  
68 I<bioperl-l@bioperl.org>
69  
70 rather than to the module maintainer directly. Many experienced and
71 reponsive experts will be able look at the problem and quickly
72 address it. Please include a thorough description of the problem
73 with code and data examples if at all possible.
74  
75 =head2 Reporting Bugs
76  
77 Report bugs to the Bioperl bug tracking system to help us keep track
78 of the bugs and their resolution. Bug reports can be submitted via
79 the web:
80  
81 https://github.com/bioperl/bioperl-live/issues
82  
83 =head1 AUTHOR - Mark A. Jensen
84  
85 Email maj@fortinbras.us
86  
87 =head1 APPENDIX
88  
89 The rest of the documentation details each of the object methods.
90 Internal methods are usually preceded with a _
91  
92 =cut
93  
94 # Let the code begin...
95  
96 package Bio::Search::Tiling::TilingI;
97 3 $Bio::Search::Tiling::TilingI::VERSION = '1.7.8';
98 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
99 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
100  
101 # Object preamble - inherits from Bio::Root::Root
102  
103 3 ▶use Bio::Root::Root;
Subroutine BEGIN: called CC=1 SCAR=0.0
104  
105 3 ▶use base qw(Bio::Root::Root);
Subroutine BEGIN: called CC=1 SCAR=0.0
106  
107 =head2 STATISTICS METHODS
108  
109 The tiling statistics can be thought of as global counterparts to
110 similar statistics defined for the individual HSPs. We therefore
111 prescribe definitions for many of the synonymous methods defined in
112 L<Bio::Search::HSP::HSPI>.
113  
114 The tiling statistics must be able to keep track of the coordinate
115 systems in which both the query and subject sequences exist; i.e.,
116 either nucleotide or amino acid. This information is typically
117 inferred from the name of the algorithm used to perform the original
118 search (contained in C<$hit_object-E<gt>algorithm>). Here is a table
119 of algorithm information that may be useful (if you trust us).
120  
121 algorithm query on hit coordinates(q/h)
122 --------- ------------ ---------------
123 blastn dna on dna dna/dna
124 blastp aa on aa aa/aa
125 blastx xna on aa dna/aa
126 tblastn aa on xna aa/dna
127 tblastx xna on xna dna/dna
128 fasta dna on dna dna/dna
129 fasta aa on aa aa/aa
130 fastx xna on aa dna/aa
131 fasty xna on aa dna/aa
132 tfasta aa on xna aa/dna
133 tfasty aa on xna aa/dna
134 megablast dna on dna dna/dna
135  
136 xna: translated nucleotide data
137  
138 Statistics methods must also be aware of differences in reporting
139 among the algorithms. Hit attributes are not necessarily normalized
140 over all algorithms. Devs, please feel free to add examples to the
141 list below.
142  
143 =over
144  
145 =item NCBI BLAST vs WU-BLAST (AB-BLAST) lengths
146  
147 The total length of the alignment is reported differently between these two flavors. C<$hit_object-E<gt>length()> will contain the number in the denominator of the stats line; i.e., 120 in
148  
149 Identical = 34/120 Positives = 67/120
150  
151 NCBI BLAST uses the total length of the query sequence as input by the user (a.k.a. "with gaps"). WU-BLAST uses the length of the query sequence actually aligned by the algorithm (a.k.a. "without gaps").
152  
153 =back
154  
155 Finally, developers should remember that sequence data may or may not
156 be associated with the HSPs contained in the hit object. This will
157 typically depend on whether a full report (e.g, C<blastall -m0>) or a
158 summary (e.g., C<blastall -m8>) was parsed. Statistics methods that
159 depend directly on the sequence data will need to check that
160 that data is present.
161  
162 =head2 identities
163  
164 Title : identities
165 Alias : num_identical
166 Usage : $num_identities = $tiling->identities()
167 Function: Return the estimated or exact number of identities in the
168 tiling, accounting for overlapping HSPs
169 Example :
170 Returns : number of identical residue pairs
171 Args :
172  
173 =cut
174  
175 0 ▶sub identities{
Subroutine identities: not called CC=1 SCAR=6.9
Pod documented
176 0 my ($self,@args) = @_;
177 0 $self->throw_not_implemented;
178 }
179  
180 #HSPI synonym
181 0 ▶sub num_identical { shift->identities( @_ ) }
Subroutine num_identical: not called CC=1 SCAR=6.9
Pod undocumented
182  
183 =head2 conserved
184  
185 Title : conserved
186 Alias : num_conserved
187 Usage : $num_conserved = $tiling->conserved()
188 Function: Return the estimated or exact number of conserved sites in the
189 tiling, accounting for overlapping HSPs
190 Example :
191 Returns : number of conserved residue pairs
192 Args :
193  
194 =cut
195  
196 0 ▶sub conserved{
Subroutine conserved: not called CC=1 SCAR=6.9
Pod documented
197 0 my ($self,@args) = @_;
198 0 $self->throw_not_implemented;
199 }
200  
201 #HSPI synonym
202 0 ▶sub num_conserved { shift->conserved( @_ ) }
Subroutine num_conserved: not called CC=1 SCAR=6.9
Pod undocumented
203  
204 =head2 length
205  
206 Title : length
207 Usage : $max_length = $tiling->length($type)
208 Function: Return the total number of residues of the subject or query
209 sequence covered by the tiling
210 Returns : number of "logical" residues covered
211 Args : scalar $type, one of 'hit', 'subject', 'query'
212  
213 =cut
214  
215 0 ▶sub length{
Subroutine length: not called CC=1 SCAR=6.9
Pod documented
216 0 my ($self, $type, @args) = @_;
217 0 $self->throw_not_implemented;
218 }
219  
220 =head2 frac_identical
221  
222 Title : frac_identical
223 Usage : $tiling->frac_identical($type)
224 Function: Return the fraction of sequence length consisting
225 of identical pairs
226 Returns : scalar float
227 Args : scalar $type, one of 'hit', 'subject', 'query'
228 Note : This method must take account of the $type coordinate
229 system and the length reporting method (see STATISTICS
230 METHODS above)
231  
232 =cut
233  
234 0 ▶sub frac_identical {
Subroutine frac_identical: not called CC=1 SCAR=6.9
Pod documented
235 0 my ($self, $type, @args) = @_;
236 0 $self->throw_not_implemented;
237 }
238  
239 =head2 percent_identity
240  
241 Title : percent_identity
242 Usage : $tiling->percent_identity($type)
243 Function: Return the fraction of sequence length consisting
244 of identical pairs as a percentage
245 Returns : scalar float
246 Args : scalar $type, one of 'hit', 'subject', 'query'
247  
248 =cut
249  
250 0 ▶sub percent_identity {
Subroutine percent_identity: not called CC=1 SCAR=6.9
Pod documented
251 0 my ($self, $type, @args) = @_;
252 0 return $self->frac_identical($type, @args) * 100;
253 }
254  
255 =head2 frac_conserved
256  
257 Title : frac_conserved
258 Usage : $tiling->frac_conserved($type)
259 Function: Return the fraction of sequence length consisting
260 of conserved pairs
261 Returns : scalar float
262 Args : scalar $type, one of 'hit', 'subject', 'query'
263 Note : This method must take account of the $type coordinate
264 system and the length reporting method (see STATISTICS
265 METHODS above)
266  
267 =cut
268  
269 0 ▶sub frac_conserved{
Subroutine frac_conserved: not called CC=1 SCAR=6.9
Pod documented
270 0 my ($self, $type, @args) = @_;
271 0 $self->throw_not_implemented;
272 }
273  
274 =head2 percent_conserved
275  
276 Title : percent_conserved
277 Usage : $tiling->percent_conserved($type)
278 Function: Return the fraction of sequence length consisting
279 of conserved pairs as a percentage
280 Returns : scalar float
281 Args : scalar $type, one of 'hit', 'subject', 'query'
282  
283 =cut
284  
285 0 ▶sub percent_conserved {
Subroutine percent_conserved: not called CC=1 SCAR=6.9
Pod documented
286 0 my ($self, $type, @args) = @_;
287 0 return $self->frac_conserved($type, @args) * 100;
288 }
289  
290 =head2 frac_aligned
291  
292 Title : frac_aligned
293 Usage : $tiling->frac_aligned($type)
294 Function: Return the fraction of B<input> sequence length consisting
295 that was aligned by the algorithm
296 Returns : scalar float
297 Args : scalar $type, one of 'hit', 'subject', 'query'
298 Note : This method must take account of the $type coordinate
299 system and the length reporting method (see STATISTICS
300 METHODS above)
301  
302 =cut
303  
304 0 ▶sub frac_aligned{
Subroutine frac_aligned: not called CC=1 SCAR=6.9
Pod documented
305 0 my ($self, $type, @args) = @_;
306 0 $self->throw_not_implemented;
307 }
308  
309 # aliases for back compat
310 0 ▶sub frac_aligned_query { shift->frac_aligned('query', @_) }
Subroutine frac_aligned_query: not called CC=1 SCAR=6.9
Pod undocumented
311 0 ▶sub frac_aligned_hit { shift->frac_aligned('hit', @_) }
Subroutine frac_aligned_hit: not called CC=1 SCAR=6.9
Pod undocumented
312  
313 =head2 range
314  
315 Title : range
316 Usage : $tiling->range($type)
317 Function: Returns the extent of the longest tiling
318 as ($min_coord, $max_coord)
319 Returns : array of two scalar integers
320 Args : scalar $type, one of 'hit', 'subject', 'query'
321  
322 =cut
323  
324 0 ▶sub range {
Subroutine range: not called CC=1 SCAR=6.9
Pod documented
325 0 my ($self, $type, @args) = @_;
326 0 $self->throw_not_implemented;
327 }
328  
329 =head1 TILING ITERATORS
330  
331 =head2 next_tiling
332  
333 Title : next_tiling
334 Usage : @hsps = $self->next_tiling($type);
335 Function: Obtain a tiling of HSPs over the $type ('hit', 'subject',
336 'query') sequence
337 Example :
338 Returns : an array of HSPI objects
339 Args : scalar $type: one of 'hit', 'subject', 'query', with
340 'subject' an alias for 'hit'
341  
342 =cut
343  
344 0 ▶sub next_tiling{
Subroutine next_tiling: not called CC=1 SCAR=6.9
Pod documented
345 0 my ($self,$type,@args) = @_;
346 0 $self->throw_not_implemented;
347 }
348  
349 =head2 rewind_tilings
350  
351 Title : rewind_tilings
352 Usage : $self->rewind_tilings($type)
353 Function: Reset the next_tilings($type) iterator
354 Example :
355 Returns : True on success
356 Args : scalar $type: one of 'hit', 'subject', 'query', with
357 'subject' an alias for 'hit'
358  
359 =cut
360  
361 0 ▶sub rewind_tilings{
Subroutine rewind_tilings: not called CC=1 SCAR=6.9
Pod documented
362 0 my ($self, $type, @args) = @_;
363 0 $self->throw_not_implemented;
364 }
365  
366 #alias
367 1 ▶sub rewind { shift->rewind_tilings(@_) }
Subroutine rewind: called CC=1 SCAR=0.0
Pod undocumented
368  
369 =head1 INFORMATIONAL ACCESSORS
370  
371 =head2 algorithm
372  
373 Title : algorithm
374 Usage : $tiling->algorithm
375 Function: Retrieve the algorithm name associated with the
376 invocant's hit object
377 Returns : scalar string
378 Args :
379  
380 =cut
381  
382 0 ▶sub algorithm{
Subroutine algorithm: not called CC=1 SCAR=6.9
Pod documented
383 0 my ($self, @args) = @_;
384 0 $self->throw_not_implemented;
385 }
386  
387 3 1;
« Bio/SeqFeature/Gene/NC_Feature.pm ↑ Summary Bio/SearchIO/EventHandlerI.pm »