Debian Codegraph @

blib/lib/TFBS/Word/Consensus.pm

raw
1 # TFBS module for TFBS::Word::Consensus
2 #
3 # Copyright Boris Lenhard
4 #
5 # You may distribute this module under the same terms as perl itself
6 #
7
8 # POD
9
10 =head1 NAME
11
12 TFBS::Word - IUPAC DNA consensus word-based pattern class
13 =head1 DESCRIPTION
14
15 TFBS::Word is a base class consisting of universal constructor called by
16 its subclasses (TFBS::Matrix::*), and word pattern manipulation methods that
17 are independent of the word type. It is not meant to be instantiated itself.
18
19 =head1 FEEDBACK
20
21 Please send bug reports and other comments to the author.
22
23 =head1 AUTHOR - Boris Lenhard
24
25 Boris Lenhard E<lt>[email protected]<gt>
26
27 =head1 APPENDIX
28
29 The rest of the documentation details each of the object
30 methods. Internal methods are preceded with an underscore.
31
32 =cut
33
34 package TFBS::Word::Consensus;
35
36 use vars '@ISA';
37
38 use TFBS::Word;
39 use TFBS::Matrix::PWM;
40
41 use strict;
42
43 @ISA = qw(TFBS::Word);
44
45
46 =head2 new
47
48 Title : new
49 Usage : my $pwm = TFBS::Matrix::PWM->new(%args)
50 Function: constructor for the TFBS::Matrix::PWM object
51 Returns : a new TFBS::Matrix::PWM object
52 Args : # you must specify the -word argument:
53 -word, # a strig consisting of letters in
54 # IUPAC degenerate DNA alphabet
55 # (any of ACGTSWKMPYBDHVN)
56
57 #######
58
59 -name, # string, OPTIONAL
60 -ID, # string, OPTIONAL
61 -class, # string, OPTIONAL
62 -tags # a hash reference reference, OPTIONAL
63
64 =cut
65
66 # "new" is inherited from TFBS::Word
67
68 =head2 search_seq
69
70 Title : search_seq
71 Usage : my $siteset = $pwm->search_seq(%args)
72 Function: scans a nucleotide sequence with the pattern represented
73 by the PWM
74 Returns : a TFBS::SiteSet object
75 Args : # you must specify either one of the following three:
76
77 -file, # the name od a fasta file (single sequence)
78 #or
79 -seqobj # a Bio::Seq object
80 # (more accurately, a Bio::PrimarySeqobject or a
81 # subclass thereof)
82 #or
83 -seqstring # a string containing the sequence
84
85 -max_mismatches, # number of allowed positions in the site that do
86 # not match the consensus
87 # OPTIONAL: default 0
88
89 =cut
90
91
92 sub search_seq {
93 my ($self, @args) = @_;
94 my ($max_mismatch) = $self->_rearrange([qw(MAX_MISMATCHES)], @args) or 0;
95 $max_mismatch = 0 unless defined $max_mismatch;
96 my $pwm = $self->to_PWM;
97 my $siteset = $pwm->search_seq(@args,
98 -threshold => $self->length - $max_mismatch);
99 $self->_replace_patterns_in_siteset($siteset);
100 return $siteset;
101 }
102
103
104 =head2 search_aln
105
106 Title : search_aln
107 Usage : my $site_pair_set = $pwm->search_aln(%args)
108 Function: Scans a pairwise alignment of nucleotide sequences
109 with the pattern represented by the word: it reports only
110 those hits that are present in equivalent positions of both
111 sequences and exceed a specified threshold score in both, AND
112 are found in regions of the alignment above the specified
113 conservation cutoff value.
114 Returns : a TFBS::SitePairSet object
115 Args : # you must specify either one of the following three:
116
117 -file, # the name of the alignment file in Clustal
118 format
119 #or
120 -alignobj # a Bio::SimpleAlign object
121 # (more accurately, a Bio::PrimarySeqobject or a
122 # subclass thereof)
123 #or
124 -alignstring # a multi-line string containing the alignment
125 # in clustal format
126 #############
127
128 -max_mismatches, # number of allowed positions in the site that do
129 # not match the consensus
130 # OPTIONAL: default 0
131
132 -window, # size of the sliding window (inn nucleotides)
133 # for calculating local conservation in the
134 # alignment
135 # OPTIONAL: default 50
136
137 -cutoff # conservation cutoff (%) for including the
138 # region in the results of the pattern search
139 # OPTIONAL: default "70%"
140
141 =cut
142
143
144
145
146 sub search_aln {
147 my ($self, @args) = @_;
148 my ($max_mismatch) = $self->_rearrange([qw(MAX_MISMATCHES)], @args) or 0;
149 $max_mismatch = 0 unless defined $max_mismatch;
150 my $pwm = $self->to_PWM;
151 my $sitepairset = $pwm->search_aln(@args,
152 -threshold => $self->length - $max_mismatch);
153 $self->_replace_patterns_in_sitepairset($sitepairset);
154 return $sitepairset;
155
156 }
157
158 =head2 to_PWM
159
160 =cut
161
162 sub to_PWM {
163 my ($self, @args) = @_;
164 my $pwm = TFBS::Matrix::PWM->new(-ID => $self->ID,
165 -name => $self->name,
166 -class => $self->class,
167 -matrix => _consensus2matrixref($self->word),
168 -tags => {$self->all_tags}
169 );
170 return $pwm;
171 }
172
173 =head2 validate_word
174
175 =cut
176
177
178 sub validate_word {
179 my ($self, $word) = @_;
180 $word =~ s/[ACGTSWKMRYBDHVN]//gi;
181 return ($word eq "");
182 }
183
184 =head2 length
185
186 =cut
187
188
189 sub length {
190 return length $_[0]->word;
191 }
192
193
194
195 # private methods
196
197
198 sub _replace_patterns_in_siteset {
199 my ($self, $siteset) = @_;
200 my $iter = $siteset->Iterator;
201 while (my $site = $iter->next) {
202 $site->pattern($self);
203 }
204 }
205
206
207
208 sub _replace_patterns_in_sitepairset {
209 my ($self, $sitepairset) = @_;
210 my $iter = $sitepairset->Iterator;
211 while (my $sitepair = $iter->next) {
212 $sitepair->feature1->pattern($self);
213 $sitepair->feature2->pattern($self);
214 }
215
216 }
217
218 # utility functions
219
220 sub _consensus2matrixref {
221 my ($word) = @_;
222 my %iupac = ( T => [0,0,0,1],
223 G => [0,0,1,0],
224 K => [0,0,1,1],
225 C => [0,1,0,0],
226 Y => [0,1,0,1],
227 S => [0,1,1,0],
228 B => [0,1,1,1],
229 A => [1,0,0,0],
230 W => [1,0,0,1],
231 R => [1,0,1,0],
232 D => [1,0,1,1],
233 M => [1,1,0,0],
234 H => [1,1,0,1],
235 V => [1,1,1,0],
236 N => [1,1,1,1]
237 );
238 my @vert_array;
239 foreach my $letter (split '', $word) {
240 push @vert_array,
241 ($iupac{uc($letter)}
242 or croak ("$letter is not a legal IUPAC DNA character"));
243 }
244 return _transpose_arrayref(\@vert_array);
245
246 }
247
248
249
250 sub _transpose_arrayref {
251 my $vert_arrayref = shift;
252 my $maxcol = scalar(@$vert_arrayref) - 1;
253 my @horiz_array;
254 foreach my $row (0..3) {
255 push @horiz_array, [ map { $vert_arrayref->[$_][$row] } 0..$maxcol ];
256
257 }
258 return \@horiz_array;
259 }
260
261
262
263 1;