| 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; | |