← Back to branch summary

~ubuntu-branches/ubuntu/precise/bioperl/precise

« back to all changes in this revision

Viewing changes to Bio/Search/Tiling/TilingI.pm

  • Committer: Bazaar Package Importer
  • Author(s): Ilya Barygin
  • Date: 2010-01-27 22:48:22 UTC
  • mfrom: (3.1.4 squeeze)
  • Revision ID: james.westby@ubuntu.com-20100127224822-ebot4qbrjxcv38au
Tags: 1.6.1-1ubuntu1
* Merge from Debian testing, remaining changes:
  - disable tests, they produce a FTBFS trying to access the network 
    during run.

Show diffs side-by-side

added added

removed removed

Lines of Context:
Bio/Search/Tiling/TilingI.pm
 
1
# $Id: TilingI.pm 16123 2009-09-17 12:57:27Z cjfields $
 
2
#
 
3
# BioPerl module for Bio::Search::Tiling::TilingI
 
4
#
 
5
# Please direct questions and support issues to <bioperl-l@bioperl.org>
 
6
#
 
7
# Cared for by Mark A. Jensen <maj@fortinbras.us>
 
8
#
 
9
# Copyright Mark A. Jensen
 
10
#
 
11
# You may distribute this module under the same terms as perl itself
 
12
 
 
13
# POD documentation - main docs before the code
 
14
 
 
15
=head1 NAME
 
16
 
 
17
Bio::Search::Tiling::TilingI - Abstract interface for an HSP tiling module
 
18
 
 
19
=head1 SYNOPSIS
 
20
 
 
21
Not used directly. Useful POD here for developers, however.
 
22
 
 
23
The interface is desgined to make the following code conversion as
 
24
simple as possible:
 
25
 
 
26
From:
 
27
 
 
28
 # Bio::Search::SearchUtils-based
 
29
 while ( local $_ = $result->next_hit ) {
 
30
    printf( "E-value: %g; Fraction aligned: %f; Number identical: %d\n",
 
31
      $hit->significance, $hit->frac_aligned_query, $hit->num_identical);
 
32
 }
 
33
 
 
34
To:
 
35
 
 
36
 # TilingI-based
 
37
 while ( local $_ = $result->next_hit ) {
 
38
    my $tiling = Bio::Search::Tiling::MyTiling($_);
 
39
    printf( "E-value: %g; Fraction aligned: %f; Number identical: %d\n",
 
40
      $hit->significance, $tiling->frac_aligned_query, $tiling->num_identical);
 
41
 }
 
42
 
 
43
 
 
44
 
 
45
=head1 DESCRIPTION
 
46
 
 
47
This module provides strong suggestions for any intended HSP tiling
 
48
object implementation. An object subclassing TilingI should override
 
49
the methods defined here according to their descriptions below.
 
50
 
 
51
See the section STATISTICS METHODS for hints on implementing methods
 
52
that are valid across different algorithms and report types.
 
53
 
 
54
=head1 FEEDBACK
 
55
 
 
56
=head2 Mailing Lists
 
57
 
 
58
User feedback is an integral part of the evolution of this and other
 
59
Bioperl modules. Send your comments and suggestions preferably to
 
60
the Bioperl mailing list.  Your participation is much appreciated.
 
61
 
 
62
  bioperl-l@bioperl.org                  - General discussion
 
63
  http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
 
64
 
 
65
=head2 Support
 
66
 
 
67
Please direct usage questions or support issues to the mailing list:
 
68
 
 
69
I<bioperl-l@bioperl.org>
 
70
 
 
71
rather than to the module maintainer directly. Many experienced and
 
72
reponsive experts will be able look at the problem and quickly
 
73
address it. Please include a thorough description of the problem
 
74
with code and data examples if at all possible.
 
75
 
 
76
=head2 Reporting Bugs
 
77
 
 
78
Report bugs to the Bioperl bug tracking system to help us keep track
 
79
of the bugs and their resolution. Bug reports can be submitted via
 
80
the web:
 
81
 
 
82
  http://bugzilla.open-bio.org/
 
83
 
 
84
=head1 AUTHOR - Mark A. Jensen
 
85
 
 
86
Email maj@fortinbras.us
 
87
 
 
88
=head1 APPENDIX
 
89
 
 
90
The rest of the documentation details each of the object methods.
 
91
Internal methods are usually preceded with a _
 
92
 
 
93
=cut
 
94
 
 
95
# Let the code begin...
 
96
 
 
97
package Bio::Search::Tiling::TilingI;
 
98
use strict;
 
99
use warnings;
 
100
 
 
101
# Object preamble - inherits from Bio::Root::Root
 
102
 
 
103
use Bio::Root::Root;
 
104
 
 
105
use base qw(Bio::Root::Root);
 
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
sub identities{
 
176
    my ($self,@args) = @_;
 
177
    $self->throw_not_implemented;
 
178
}
 
179
 
 
180
#HSPI synonym
 
181
sub num_identical { shift->identities( @_ ) }
 
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
sub conserved{
 
197
    my ($self,@args) = @_;
 
198
    $self->throw_not_implemented;
 
199
}
 
200
 
 
201
#HSPI synonym
 
202
sub num_conserved { shift->conserved( @_ ) }
 
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
sub length{
 
216
    my ($self, $type, @args) = @_;
 
217
    $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
sub frac_identical {
 
235
    my ($self, $type, @args) = @_;
 
236
    $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
sub percent_identity {
 
251
    my ($self, $type, @args) = @_;
 
252
    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
sub frac_conserved{
 
270
    my ($self, $type, @args) = @_;
 
271
    $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
sub percent_conserved {
 
286
    my ($self, $type, @args) = @_;
 
287
    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
sub frac_aligned{
 
305
    my ($self, $type, @args) = @_;
 
306
    $self->throw_not_implemented;
 
307
}
 
308
 
 
309
# aliases for back compat
 
310
sub frac_aligned_query { shift->frac_aligned('query', @_) }
 
311
sub frac_aligned_hit { shift->frac_aligned('hit', @_) }
 
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
sub range {
 
325
    my ($self, $type, @args) = @_;
 
326
    $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
sub next_tiling{
 
345
    my ($self,$type,@args) = @_;
 
346
    $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
sub rewind_tilings{
 
362
    my ($self, $type, @args) = @_;
 
363
    $self->throw_not_implemented;
 
364
}
 
365
 
 
366
#alias
 
367
sub rewind { shift->rewind_tilings(@_) }
 
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
sub algorithm{
 
383
    my ($self, @args) = @_;
 
384
    $self->throw_not_implemented;
 
385
}
 
386
 
 
387
1;