Bio/Tools/SeqWords.pm

filter: Statementstmt 81.9% 50 / 61 Branchbran 55.8% 19 / 34 Conditioncond 33.3% 4 / 12 MC/DCmcdc 0.0% 0 / 7 Subroutinesub 100% 6 / 6 Podpod 100% 3 / 3 totaltotal 66.6% 82 / 123 CC 22 SCAR 22.4
CC
22
Cov
68%
count_words
16.7
new
6.9
count_overlap_words
6.2
CRAP 9.4
« Bio/SearchIO.pm ↑ Summary Bio/Tools/SeqStats.pm »
1 #---------------------------------------------------------------------------
2 # PACKAGE : Bio::Tools::SeqWords
3 # PURPOSE : To count n-mers in any sequence of characters
4 # AUTHOR : Derek Gatherer (d.gatherer@vir.gla.ac.uk)
5 # SOURCE :
6 # CREATED : 21st March 2000
7 # MODIFIED : 11th November 2003 (DG - new method, count_overlap_words)
8 # LICENCE : You may distribute this module under the same terms
9 # : as the rest of BioPerl.
10 #---------------------------------------------------------------------------
11  
12 =head1 NAME
13  
14 Bio::Tools::SeqWords - Object holding n-mer statistics for a sequence
15  
16 =head1 SYNOPSIS
17  
18 # Create the SeqWords object, e.g.:
19  
20 my $inputstream = Bio::SeqIO->new(-file => "seqfile",
21 -format => 'Fasta');
22 my $seqobj = $inputstream->next_seq();
23 my $seq_word = Bio::Tools::SeqWords->new(-seq => $seqobj);
24  
25 # Or:
26 my $seqobj = Bio::PrimarySeq->new(-seq => "agggtttccc",
27 -alphabet => 'dna',
28 -id => 'test');
29 my $seq_word = Bio::Tools::SeqWords->new(-seq => $seqobj);
30  
31 # obtain a hash of word counts, eg:
32 my $hash_ref = $seq_stats->count_words($word_length);
33  
34 # display hash table, eg:
35 my %hash = %$hash_ref;
36 foreach my $key(sort keys %hash)
37 {
38 print "\n$key\t$hash{$key}";
39 }
40  
41 # Or:
42  
43 my $hash_ref =
44 Bio::Tools::SeqWords->count_words($seqobj,$word_length);
45  
46 =head1 DESCRIPTION
47  
48 L<Bio::Tools::SeqWords> is a featherweight object for the calculation
49 of n-mer word occurrences in a single sequence. It is envisaged that
50 the object will be useful for construction of scripts which use n-mer
51 word tables as the raw material for statistical calculations; for
52 instance, hexamer frequency for the calculation of coding protential,
53 or the calculation of periodicity in repetitive DNA. Triplet
54 frequency is already handled by L<Bio::Tools::SeqStats> (author: Peter
55 Schattner).
56  
57 There are a few possible applications for protein, e.g. hypothesised
58 amino acid 7-mers in heat shock proteins, or proteins with multiple
59 simple motifs. Sometimes these protein periodicities are best seen
60 when the amino acid alphabet is truncated, e.g. Shulman alphabet.
61 Since there are quite a few of these shortened alphabets, this module
62 does not specify any particular alphabet.
63  
64 See Synopsis above for object creation code.
65  
66 =head2 Rationale
67  
68 Take a sequence object and create an object for the purposes of
69 holding n-mer word statistics about that sequence. The sequence can be
70 nucleic acid or protein.
71  
72 In count_words() the words are counted in a non-overlapping manner,
73 ie. in the style of a codon table, but with any word length.
74  
75 In count_overlap_words() the words are counted in an overlapping
76 manner.
77  
78 For counts on opposite strand (DNA/RNA), a reverse complement method
79 should be performed, and then the count repeated.
80  
81 =head1 FEEDBACK
82  
83 =head2 Mailing Lists
84  
85 User feedback is an integral part of the evolution of this and other
86 Bioperl modules. Send your comments and suggestions preferably to one
87 of the Bioperl mailing lists. Your participation is much appreciated.
88  
89 bioperl-l@bioperl.org - General discussion
90 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
91  
92 =head2 Support
93  
94 Please direct usage questions or support issues to the mailing list:
95  
96 I<bioperl-l@bioperl.org>
97  
98 rather than to the module maintainer directly. Many experienced and
99 reponsive experts will be able look at the problem and quickly
100 address it. Please include a thorough description of the problem
101 with code and data examples if at all possible.
102  
103 =head2 Reporting Bugs
104  
105 Report bugs to the Bioperl bug tracking system to help us keep track
106 the bugs and their resolution. Bug reports can be submitted via the
107 web:
108  
109 https://github.com/bioperl/bioperl-live/issues
110  
111 =head1 AUTHOR
112  
113 Derek Gatherer, in the loosest sense of the word 'author'. The
114 general shape of the module is lifted directly from the SeqStat module
115 of Peter Schattner. The central subroutine to count the words is
116 adapted from original code provided by Dave Shivak, in response to a
117 query on the bioperl mailing list. At least 2 other people provided
118 alternative means (equally good but not used in the end) of performing
119 the same calculation. Thanks to all for your assistance.
120  
121 =head1 CONTRIBUTORS
122  
123 Jason Stajich, jason-at-bioperl.org
124  
125 =head1 APPENDIX
126  
127 The rest of the documentation details each of the object methods.
128 Internal methods are usually preceded with a _
129  
130 =cut
131  
132 package Bio::Tools::SeqWords;
133 2 $Bio::Tools::SeqWords::VERSION = '1.7.8';
134 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
135  
136  
137 2 ▶use base qw(Bio::Root::Root);
Subroutine BEGIN: called CC=1 SCAR=0.0
138  
139 3 ▶sub new {
Subroutine new: called CC=5 SCAR=19.3
Pod documented
140 3 my($class,@args) = @_;
141 # our new standard way of instantiation
142 3 my $self = $class->SUPER::new(@args);
143  
144 3 my ($seqobj) = $self->_rearrange([qw(SEQ)],@args);
145 3 ▶ if((! defined($seqobj)) && @args && ref($args[0])) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $seqobj and @args and ref $args[0]) 0 3 3
Condition33%2/6
not defined $seqobj and @args and ref $args[0]
!ll&&!rl&&r
300
not defined $seqobj and @args
!ll&&!rl&&r
300
MC/DC0%0/3
not defined $seqobj and @args and ref $args[0]
not defined $seqobj @args ref $args[0]
Truth table25%1/4
not(A) and B and C
A= not defined $seqobjB= @argsC= ref $args[0]
ABCresult
0XX0
10X0
1100
1111
146 # parameter not passed as named parameter?
147 0 $seqobj = $args[0];
148 }
149
150 3 ▶ if(! $seqobj->isa("Bio::PrimarySeqI")) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($seqobj->isa("Bio::PrimarySeqI")) 0 3 3
151 0 $self->throw(ref($self) . " works only on PrimarySeqI objects\n");
152 }
153
154 3 $self->{'_seqref'} = $seqobj;
155 3 return $self;
156 }
157  
158  
159 =head2 count_words
160  
161 Title : count_words
162 Usage : $word_count = $seq_stats->count_words($word_length)
163 or
164 $word_count = $seq_stats->Bio::Tools::SeqWords->($seqobj,$word_length);
165 Function: Counts non-overlapping words within a string, any alphabet is
166 used
167 Example : a sequence ACCGTCCGT, counted at word length 4, will give the hash
168 {ACCG => 1, TCCG => 1}
169 Returns : Reference to a hash in which keys are words (any length) of the
170 alphabet used and values are number of occurrences of the word
171 in the sequence.
172 Args : Word length as scalar and, reference to sequence object if
173 required
174  
175 Throws an exception word length is not a positive integer
176 or if word length is longer than the sequence.
177  
178 =cut
179  
180 sub count_words
181 3 ▶{
Subroutine count_words: called CC=9 SCAR=28.2
Pod documented
182 3 my ($self,$seqobj,$word_length) = @_;
183  
184 # check how we were called, and if necessary rearrange arguments
185 3 ▶ if(ref($seqobj)) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $seqobj) { } 0 3 3
186 # call as SeqWords->count_words($seq, $wordlen)
187 0 ▶ if(! $seqobj->isa("Bio::PrimarySeqI")) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($seqobj->isa("Bio::PrimarySeqI")) 0 0 0
188 0 $self->throw("SeqWords works only on PrimarySeqI objects\n");
189 }
190 } else {
191 # call as $obj->count_words($wordlen)
192 3 $word_length = $seqobj;
193 3 $seqobj = undef;
194 }
195  
196 3 ▶ if(! defined($seqobj)){
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $seqobj) 3 0 3
197 3 $seqobj = $self->{'_seqref'};
198 }
199
200 3 ▶ if($word_length eq "" || $word_length =~ /[a-z]/i){
Branch: 2 branches
BranchTrueFalseTotal
if ($word_length eq '' or $word_length =~ /[a-z]/i) { } 0 3 3
elsif ($word_length < 1 or $word_length - int($word_length) > 0) { } 0 3 3
Condition33%1/3
$word_length eq "" or $word_length =~ /[a-z]/i
l!l&&r!l&&!r
003
MC/DC0%0/2
$word_length eq "" or $word_length =~ /[a-z]/i
$word_length eq "" $word_length =~ /[a-z]/i
Truth table33%1/3
A or B
A= $word_length eq ""B= $word_length =~ /[a-z]/i
ABresult
1X1
011
000
201 0 $self->throw("SeqWords cannot accept non-numeric characters".
202 " or a null value in the \$word_length variable\n");
203 ▶ }elsif ($word_length <1 || ($word_length - int($word_length)) >0){
Condition33%1/3
$word_length < 1 or $word_length - int($word_length) > 0
l!l&&r!l&&!r
003
MC/DC0%0/2
$word_length < 1 or $word_length - int($word_length) > 0
$word_length < 1 $word_length - int($word_length) > 0
Truth table33%1/3
A or B
A= $word_length < 1B= $word_length - int($word_length) > 0
ABresult
1X1
011
000
204 0 $self->throw("SeqWords requires the word length to be a ".
205 "positive integer\n");
206 }
207  
208 3 my $seqstring = uc $seqobj->seq();
209  
210 3 ▶ if($word_length > length($seqstring)){
Branch: 1 branch
BranchTrueFalseTotal
if ($word_length > length $seqstring) 0 3 3
211 0 $self->throw("die in _count, \$word_length is bigger ".
212 "than sequence length\n");
213 }
214  
215 3 my $type = "non-overlap";
216 3 my $words = _count($seqobj, $word_length, $type);
217 3 return $words; # ref. to a hash
218 }
219  
220 =head2 count_overlap_words
221  
222 Title : count_overlap_words
223 Usage : $word_count = $word_obj->count_overlap_words($word_length);
224 Function: Counts overlapping words within a string, any alphabet is used
225 Example : A sequence ACCAACCA, counted at word length 4, will give the hash
226 {ACCA=>2, CCAA=>1, CAAC=>1, AACC=>1}
227 Returns : Reference to a hash in which keys are words (any length) of the
228 alphabet used and values are number of occurrences of the word in
229 the sequence.
230 Args : Word length as scalar
231  
232 Throws an exception if word length is not a positive integer
233 or if word length is longer than the sequence.
234  
235 =cut
236  
237 sub count_overlap_words
238 2 ▶{
Subroutine count_overlap_words: called CC=5 SCAR=18.2
Pod documented
239 2 my ($self,$seqobj,$word_length) = @_;
240 # check how we were called, and if necessary rearrange arguments
241 2 ▶ if(ref($seqobj)){
Branch: 1 branch
BranchTrueFalseTotal
if (ref $seqobj) { } 0 2 2
242 # call as SeqWords->count_words($seq, $wordlen)
243 0 ▶ if(! $seqobj->isa("Bio::PrimarySeqI")){
Branch: 1 branch
BranchTrueFalseTotal
unless ($seqobj->isa("Bio::PrimarySeqI")) 0 0 0
244 0 $self->throw("SeqWords works only on PrimarySeqI objects\n");
245 }
246 }else{
247 # call as $obj->count_words($wordlen)
248 2 $word_length = $seqobj;
249 2 $seqobj = undef;
250 }
251  
252 2 ▶ if(! defined($seqobj)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $seqobj) 2 0 2
253 2 $seqobj = $self->{'_seqref'};
254 }
255 2 my $seqstring = uc $seqobj->seq();
256  
257 2 ▶ if($word_length > length($seqstring)){
Branch: 1 branch
BranchTrueFalseTotal
if ($word_length > length $seqstring) 0 2 2
258 0 $self->throw("die in _count, \$word_length is bigger ".
259 "than sequence length\n");
260 }
261
262 2 my $type = "overlap";
263 2 my $words = _count($seqobj, $word_length, $type);
264 2 return $words; # ref. to a hash
265 }
266  
267 # the actual counting routine
268 # used by both count_words and count_overlap_words
269 5 ▶sub _count {
Subroutine _count: called CC=6 SCAR=18.0
270 5 my ($seqobj, $word_length, $type) = @_;
271 5 my %codon = ();
272  
273 # now the real business
274 # JS - remove DNA assumption
275  
276 5 my $seqstring = uc $seqobj->seq();
277 5 ▶ if($type eq "non-overlap")
Branch: 2 branches
BranchTrueFalseTotal
if ($type eq 'non-overlap') { } 3 2 5
elsif ($type eq 'overlap') { } 2 0 2
278 {
279 3 ▶ while($seqstring =~ /((\w){$word_length})/gim){
Branch: 1 branch
BranchTrueFalseTotal
if ($seqstring =~ /((\w){$word_length})/mig) 66 3 69
280 66 $codon{uc($1)}++;
281 }
282 } elsif($type eq "overlap"){
283 2 my $seqlen = $seqobj->length(); # measure length
284 2 ▶ for (my $frame = 1; $frame <= $word_length; $frame++) {
Branch: 1 branch
BranchTrueFalseTotal
if ($frame <= $word_length) 8 2 10
285 # run through frames
286 8 my $seqstring = uc($seqobj->subseq($frame,$seqlen));
287 # take the relevant substring
288 8 ▶ while($seqstring =~ /((\w){$word_length})/gim){
Branch: 1 branch
BranchTrueFalseTotal
if ($seqstring =~ /((\w){$word_length})/mig) 49 8 57
289 49 $codon{uc($1)}++; # keep adding to hash
290 }
291 }
292 } else {
293 0 Bio::Root::Root->throw("\nSomething badly wrong here. \$type: $type can only be overlap or non-overlap");
294 }
295 5 return \%codon;
296 }
297  
298 2 1;
« Bio/SearchIO.pm ↑ Summary Bio/Tools/SeqStats.pm »