blib/lib/Chemistry/MidasPattern.pm

filter: Statementstmt 12.1% 18 / 148 Branchbran 0.0% 0 / 66 Conditioncond 0.0% 0 / 14 MC/DCmcdc 0.0% 0 / 8 Subroutinesub 22.7% 5 / 22 Podpod 62.5% 5 / 8 totaltotal 10.5% 28 / 266 CC 48 SCAR 57.7
CC
48
Cov
8%
match
756.0
parse_res
110.0
parse_midas_pattern
56.0
CRAP 319.5
« blib/lib/Chemistry/Ring/Find.pm ↑ Summary blib/lib/Parse/Yapp/Driver.pm »
1 package Chemistry::MidasPattern;
2  
3 9 $VERSION = '0.11';
4  
5 # $Id: MidasPattern.pm,v 1.3 2005/05/16 23:03:37 itubert Exp $
6  
7 =head1 NAME
8  
9 Chemistry::MidasPattern - Select atoms in macromolecules
10  
11 =head1 SYNOPSIS
12  
13 use Chemistry::MidasPattern;
14 use Chemistry::File::PDB;
15  
16 # read a molecule
17 my $mol = Chemistry::MacroMol->read("test.pdb");
18  
19 # define a pattern matching carbons alpha and beta
20 # in all valine residues
21 my $str = ':VAL@CA,CB';
22 my $patt = Chemistry::MidasPattern->new($str);
23  
24 # apply the pattern to the molecule
25 $patt->match($mol);
26  
27 # extract the results
28 for my $atom ($patt->atom_map) {
29 printf "%s\t%s\n", $atom->attr("pdb/residue_name"), $atom->name;
30 }
31 printf "FOUND %d atoms\n", scalar($patt->atom_map);
32  
33 =head1 DESCRIPTION
34  
35 This module partially implements a pattern matching engine for selecting atoms
36 in macromolecules by using Midas/Chimera patterns. See
37 L<http://www.cmpharm.ucsf.edu/~troyer/troff2html/midas/Midas-uh-3.html#sh-2.1>
38 for a detailed description of this language.
39  
40 This module shares the same interface as L<Chemistry::Pattern>; to perform a
41 pattern matching operation on a molecule, follow these steps.
42  
43 1) Create a pattern object, by parsing a string. Let's assume that the pattern
44 object is stored in $patt and that the molecule is $mol.
45  
46 2) Execute the pattern on the molecule by calling $patt->match($mol).
47  
48 3) If $patt->match() returns true, extract the "map" that relates the pattern
49 to the molecule by calling $patt->atom_map. These method returns a list of the
50 atoms in the molecule that are matched by the pattern. Thus $patt->atom_map(1)
51 would be analogous to the $1 special variable used for regular expresion
52 matching. The difference between Chemistry::Pattern and Perl regular
53 expressions is that atoms are always captured, and that each atom always uses
54 one "slot".
55  
56 =head1 MIDAS ATOM SPECIFICATION LANGUAGE QUICK SUMMARY
57  
58 The current implementation does not have the concept of a model, only of
59 residues and atoms.
60  
61 What follows is not exactly a formal grammar specification, but it should give
62 a general idea:
63  
64 SELECTOR = ((:RESIDUE(.CHAIN)?)*(@ATOM)*)*
65  
66 The star here means "zero or more", the question mark means "zero or one", and
67 the parentheses are used to delimit the effect of the star. All other
68 characters are used verbatim.
69  
70 RESIDUE can be a name (e.g., LYS), a sequence number (e.g., 108), a range
71 (e.g., 1-10), or a comma-separated list of RESIDUEs (e.g. 1-10,6,LYS).
72  
73 ATOM is an atom name, a serial number (this is a non-standard extension) or a
74 comma-separated list of ATOMs.
75  
76 Names can have wildcards: * matches the whole name; ? matches one character;
77 and = matches zero or more characters. An @ATOM specification is asociated with
78 the closest preceding residue specification.
79  
80 DISTANCE_SELECTOR = SELECTOR za< DISTANCE
81  
82 Atoms within a certain distance of those that are matched by a selector can be
83 selected by using the za< operator, where DISTANCE is a number in Angstroms.
84  
85 EXPR = ( SELECTOR | DISTANCE_SELECTOR ) (& (SELECTOR | DISTANCE_SELECTOR))*
86  
87 The result of two or more selectors can be intersected using the & operator.
88  
89 =head1 EXAMPLES
90  
91 :ARG All arginine atoms
92 :ARG.A All arginine atoms in chain 'A'
93 :ARG@* All arginine atoms
94 @CA All alpha carbons
95 :*@CA All alpha carbons
96 :ARG@CA Arginine alpha carbons
97 :VAL@C= Valine carbons
98 :VAL@C? Valine carbons with two-letter names
99 :ARG,VAL@CA Arginine and valine alpha carbons
100 :ARG:VAL@CA All arginine atoms and valine alpha carbons
101 :ARG@CA,CB Arginine alpha and beta carbons
102 :ARG@CA@CB Arginine alpha and beta carbons
103 :1-10 Atoms in residues 1 to 10
104 :48-* Atoms in residues 11 to the last one
105 :30-40@CA & :ARG Alpha carbons in residues 1-10 which are
106 also arginines.
107 @123 Atom 123
108 @123 za<5.0 Atoms within 5.0 Angstroms of atom 123
109 @123 za>30.0 Atoms not within 30.0 Angstroms of atom 123
110 @CA & @123 za<5.0 Alpha carbons within 5.0 Angstroms of atom 123
111  
112 =cut
113  
114  
115 9 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
116 9 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
117 9 ▶use Chemistry::MacroMol;
Subroutine BEGIN: called CC=1 SCAR=0.0
118 9 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
119 9 ▶use base "Chemistry::Pattern";
Subroutine BEGIN: called CC=1 SCAR=0.0
120  
121 9 our $DEBUG = 0;
122  
123 0 ▶sub new {
Subroutine new: not called CC=2 SCAR=17.9
Pod documented
124 0 my ($class, $str) = @_;
125 0 ▶ my $self = bless {
Condition0%0/3
ref $class || $class
l!l&&r!l&&!r
000
MC/DC0%0/2
ref $class || $class
ref $class $class
Truth table0%0/3
A || B
A= ref $classB= $class
ABresult
1X1
011
000
126 atom_map => [],
127 options => {},
128 matched => 0,
129 name => $str,
130 }, ref $class || $class;
131 0 $self->parse_midas_pattern($str);
132 0 $self;
133 }
134  
135 0 ▶sub atom_map {
Subroutine atom_map: not called CC=1 SCAR=6.9
Pod documented
136 0 my ($self) = @_;
137 0 @{$self->{atom_map}};
138 }
139  
140 0 ▶sub bond_map { () }
Subroutine bond_map: not called CC=1 SCAR=6.9
Pod documented
141  
142 0 ▶sub options {
Subroutine options: not called CC=1 SCAR=6.9
Pod documented
143 0 my $self = shift;
144 0 $self->{options} = {@_};
145 0 $self;
146 }
147  
148 # residue specifier: name | range | number | *
149 # atom specifier: name | number | *
150 # names may have ? and = as wildcards (equivalent to . and .*)
151 0 ▶sub parse_midas_pattern {
Subroutine parse_midas_pattern: not called CC=7 SCAR=40.3
Pod undocumented
152 0 my ($self, $string) = @_;
153 0 my $tree = [];
154 0 $self->{tree} = $tree;
155  
156 0 for my $str (split / +& +/, $string) {
157 0 my $node = { type => 'normal' };
158 0 ▶ if ($str =~ s/ +z(.?)([<>])\s*(\d+(\.\d+)?)//) {
Branch: 1 branch
BranchTrueFalseTotal
if ($str =~ s/ +z(.?)([<>])\s*(\d+(\.\d+)?)//) 0 0 0
159 0 ▶ $node->{type} = 'zone_' . ($1 || 'r');
Condition0%0/2
$1 || 'r'
l!l
00
MC/DC0%0/1
$1 || 'r'
$1
Truth table0%0/2
A
A= $1
Aresult
11
00
160 0 $node->{zone_op} = $2;
161 0 $node->{zone_val} = $3;
162 }
163 0 push @$tree, $node;
164 0 my $conditions = [];
165 0 $node->{conditions} = $conditions;
166  
167 0 $str =~ s/\s+//g; # ignore whitespace
168 0 ▶ $str = ":*$str" unless $str =~ /^:/; # add implicit "every residue"
Branch: 1 branch
BranchTrueFalseTotal
unless $str =~ /^:/ 0 0 0
169 0 my (undef, @residues) = split ':', $str;# =~ /:([^:]+)/g;
170 0 for my $residue (@residues) {
171 0 my ($res_base, $atom_base) = split '@', $residue, 2;
172 #print "res_base = $res_base\n";
173 0 my @res = map { parse_res($_) } split ',', $res_base;
174 0 my $res_node = { residue => \@res };
175 0 push @$conditions, $res_node;
176  
177 0 ▶ my (@atoms) = map { parse_atom($_) } split /[\@,]/, $atom_base||'*';
Condition0%0/2
$atom_base || '*'
l!l
00
MC/DC0%0/1
$atom_base || '*'
$atom_base
Truth table0%0/2
A
A= $atom_base
Aresult
11
00
178 0 $res_node->{atoms} = \@atoms;
179 }
180 }
181 }
182  
183 0 ▶sub parse_res {
Subroutine parse_res: not called CC=10 SCAR=47.0
Pod undocumented
184 0 my ($s) = @_;
185 0 $s = lc $s;
186 0 my $chain_id;
187 my $sub;
188 0 ▶ if ($s =~ s/\.(.)$//) { # chain id
Branch: 1 branch
BranchTrueFalseTotal
if ($s =~ s/\.(.)$//) 0 0 0
189 0 $chain_id = $1;
190 }
191 0 ▶ if ($s =~ /^\d+$/) {
Branch: 5 branches
BranchTrueFalseTotal
if ($s =~ /^\d+$/) { } 0 0 0
elsif ($s =~ /^[a-zA-Z]+$/) { } 0 0 0
elsif ($s =~ /^[a-zA-Z=?]+$/) { } 0 0 0
elsif ($s eq '*') { } 0 0 0
elsif ($s =~ /^(\d+|\*)-(\d+|\*)/) { } 0 0 0
192 0 ▶ $sub = sub {$_->attr('pdb/sequence_number') == $s};
Subroutine __ANON__: not called CC=1 SCAR=6.9
193 } elsif ($s =~ /^[a-zA-Z]+$/) {
194 0 ▶ $sub = sub {lc $_->type eq $s};
Subroutine __ANON__: not called CC=1 SCAR=6.9
195 } elsif ($s =~ /^[a-zA-Z=?]+$/) {
196 0 $s =~ s/\?/./g;
197 0 $s =~ s/=/.*/g;
198 0 ▶ $sub = sub {$_->type =~ qr/$s/i};
Subroutine __ANON__: not called CC=1 SCAR=6.9
199 } elsif ($s eq '*') {
200 0 ▶ $sub = sub {1};
Subroutine __ANON__: not called CC=1 SCAR=6.9
201 } elsif ($s =~ /^(\d+|\*)-(\d+|\*)/) {
202 0 my ($from, $to) = ($1, $2);
203 0 ▶ $from = 0 if $from eq '*';
Branch: 1 branch
BranchTrueFalseTotal
if $from eq "*" 0 0 0
204 0 ▶ $to = 1e9 if $to eq '*';
Branch: 1 branch
BranchTrueFalseTotal
if $to eq "*" 0 0 0
205
206 0 ▶ $sub = sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
207 0 ▶ my $n = $_->attr('pdb/sequence_number'); $n >= $from and $n <= $to
Branch: 1 branch
BranchTrueFalseTotal
$n >= $from and $n <= $to 0 0 0
208 0 };
209 } else {
210 0 croak "Invalid residue specification '$s'\n";
211 }
212  
213 return $chain_id ?
214 0 ▶ sub {lc $_->attr('pdb/chain_id') eq $chain_id and $sub->()}
Subroutine __ANON__: not called CC=2 SCAR=17.9
Branch: 1 branch
BranchTrueFalseTotal
lc $_->attr("pdb/chain_id") eq $chain_id and &$sub() 0 0 0
215 0 ▶ : $sub;
Branch: 1 branch
BranchTrueFalseTotal
$chain_id ? : 0 0 0
216 }
217  
218 0 ▶sub parse_atom {
Subroutine parse_atom: not called CC=4 SCAR=30.0
Pod undocumented
219 0 my ($s) = @_;
220 0 $s = lc $s;
221 0 ▶ if ($s =~ /^\d+$/) {
Branch: 3 branches
BranchTrueFalseTotal
if ($s =~ /^\d+$/) { } 0 0 0
elsif ($s =~ /^[a-zA-Z0-9='"?]+$/) { } 0 0 0
elsif ($s eq '*') { } 0 0 0
222 0 ▶ return sub {$_->attr('pdb/serial_number') == $s};
Subroutine __ANON__: not called CC=1 SCAR=6.9
223 } elsif ($s =~ /^[a-zA-Z0-9='"?]+$/) {
224 0 $s =~ s/\?/./g;
225 0 $s =~ s/=/.*/g;
226 0 ▶ return sub {$_->name =~ qr/^$s$/i};
Subroutine __ANON__: not called CC=1 SCAR=6.9
227 } elsif ($s eq '*') {
228 0 ▶ return sub {1};
Subroutine __ANON__: not called CC=1 SCAR=6.9
229 } else {
230 0 croak "Invalid atom specification '$s'\n";
231 }
232 }
233  
234 0 ▶sub match {
Subroutine match: not called CC=27 SCAR=66.3
Pod documented
235 0 my ($self, $mol) = @_;
236 0 my $tree = $self->{tree};
237 0 my @ret;
238 0 my $first = 1;
239  
240 0 ▶ if ($self->{matched} and $self->{matched} eq $mol) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"matched"} and $self->{"matched"} eq $mol) 0 0 0
Condition0%0/3
$self->{"matched"} and $self->{"matched"} eq $mol
!ll&&!rl&&r
000
MC/DC0%0/2
$self->{"matched"} and $self->{"matched"} eq $mol
$self->{"matched"} $self->{"matched"} eq $mol
Truth table0%0/3
A and B
A= $self->{"matched"}B= $self->{"matched"} eq $mol
ABresult
0X0
100
111
241 0 $self->{matched} = 0;
242 0 return 0;
243 }
244  
245 0 for my $term (@$tree) {
246 0 ▶ print "term\n" if $DEBUG;
Branch: 1 branch
BranchTrueFalseTotal
if $Chemistry::MidasPattern::DEBUG 0 0 0
247 0 my @atoms;
248 0 for my $residue_spec (@{$term->{conditions}}) {
249 0 ▶ print "\tresidue_spec\n" if $DEBUG;
Branch: 1 branch
BranchTrueFalseTotal
if $Chemistry::MidasPattern::DEBUG 0 0 0
250 0 my @residues;
251
252 # get the matching residues
253 0 for my $cond (@{$residue_spec->{residue}}) {
254 0 ▶ print "\t\tresidue condition\n" if $DEBUG;
Branch: 1 branch
BranchTrueFalseTotal
if $Chemistry::MidasPattern::DEBUG 0 0 0
255 0 push @residues, grep $cond->(), $mol->domains;
256 }
257 0 ▶ if ($self->{options}{unique}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"options"}{"unique"}) 0 0 0
258 0 my %seen;
259 0 @seen{@residues} = @residues;
260 0 @residues = values %seen;
261 }
262 0 ▶ printf "got %d residues\n", scalar @residues if $DEBUG;
Branch: 1 branch
BranchTrueFalseTotal
if $Chemistry::MidasPattern::DEBUG 0 0 0
263  
264 # get the matching atoms
265 0 for my $res (@residues) {
266 0 for my $cond (@{$residue_spec->{atoms}}) {
267 0 ▶ print "atom_cond\n" if $DEBUG;
Branch: 1 branch
BranchTrueFalseTotal
if $Chemistry::MidasPattern::DEBUG 0 0 0
268 0 push @atoms, grep $cond->(), $res->atoms;
269 }
270 }
271 }
272 0 my %seen;
273 0 ▶ if ($self->{options}{unique}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"options"}{"unique"}) 0 0 0
274 0 @seen{@atoms} = @atoms;
275 0 @atoms = values %seen;
276 }
277 0 ▶ if ($term->{type} eq 'normal') {
Branch: 3 branches
BranchTrueFalseTotal
if ($term->{'type'} eq 'normal') { } 0 0 0
elsif ($term->{'type'} eq 'zone_r') { } 0 0 0
elsif ($term->{'type'} eq 'zone_a') { } 0 0 0
278 0 @seen{@atoms} = @atoms;
279 } elsif ($term->{type} eq 'zone_r') {
280 0 croak "zr operator not implemented\n";
281 } elsif ($term->{type} eq 'zone_a') {
282 0 my $d = $term->{zone_val};
283 0 my $gt = $term->{zone_op} eq '>';
284 #print "zone_a ret(@ret)\n" unless $first;
285 @atoms = grep {
286 0 my $found = 0;
287 0 for my $a (@atoms) {
288 0 ▶ $found = 1, last if ($a->coords - $_->coords)->length < $d;
Branch: 1 branch
BranchTrueFalseTotal
if ($a->coords - $_->coords)->length < $d 0 0 0
289 }
290 0 ▶ $found xor $gt;
Branch: 1 branch
BranchTrueFalseTotal
$first ? : 0 0 0
Condition0%0/4
$found ^^ $gt
l&&rl&&!r!l&&r!l&&!r
0000
MC/DC0%0/2
$found ^^ $gt
$found $gt
Truth table0%0/4
A ^^ B
A= $foundB= $gt
ABresult
110
101
011
000
291 } $first ? $mol->atoms : @ret;
292 #print "zone_a atoms(@atoms)\n" unless $first;
293 0 @seen{@atoms} = @atoms;
294 }
295 0 ▶ if ($first) {
Branch: 1 branch
BranchTrueFalseTotal
if ($first) { } 0 0 0
296 # keep all the atoms from this term
297 0 @ret = @atoms;
298 0 $first = 0;
299 } else {
300 # keep the intersection of the previous terms with the
301 # atoms from the current term
302 0 my @tmp = @ret;
303 0 @ret = ();
304 0 for (@tmp) {
305 0 ▶ push @ret, $_ if $seen{$_};
Branch: 1 branch
BranchTrueFalseTotal
if $seen{$_} 0 0 0
306 }
307 }
308 0 ▶ last unless @ret; # don't bother evaluating the other terms
Branch: 1 branch
BranchTrueFalseTotal
unless @ret 0 0 0
309 }
310 # optionally sort the result
311 0 ▶ if ($self->{options}{sort}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"options"}{"sort"}) 0 0 0
312 0 @ret = map { $_->[0] } sort { $a->[1] <=> $b->[1] }
313 0 map { [$_, $_->attr("pdb/serial_number")] } @ret;
314 }
315 0 $self->{atom_map} = \@ret;
316 0 $self->{matched} = $mol;
317 }
318  
319 9 1;
320  
321  
322  
323 =head1 CAVEATS
324  
325 If a feature does not appear in any of the examples, it is probably not
326 implemented. For example, the zr< zone specifier, atom properties, and
327 various Chimera extensions.
328  
329 The zone specifiers (selection by distance) currently use a brute-force N^2
330 algorithm. You can optimize an & expression by putting the most unlikely
331 selectors first; for example
332  
333 :1-20 zr<10.0 & :38 atoms in residue 38 within 10 A of atoms
334 in residues 1-20 (slow)
335  
336 :38 & :1-20 zr<10.0 atoms in residue 38 within 10 A of atoms
337 in residues 1-20 (not so slow)
338
339 In the first case, the N^2 search measures the distance between every atom in
340 the molecule and every atom in residues 1-20, and then intersects the results
341 with the atom list of residue 28; the second case only measures the distance
342 between every atom in residue 38 with every atom in residues 1-20. The second
343 way is much, much faster for large systems.
344  
345 Some day, a future version may implement a smarter algorithm...
346  
347 =head1 VERSION
348  
349 0.11
350  
351 =head1 SEE ALSO
352  
353 L<Chemistry::File::MidasPattern>, L<Chemistry::Pattern>
354  
355 The PerlMol website L<http://www.perlmol.org/>
356  
357 =head1 AUTHOR
358  
359 Ivan Tubert E<lt>itub@cpan.orgE<gt>
360  
361 =head1 COPYRIGHT
362  
363 Copyright (c) 2005 Ivan Tubert. All rights reserved. This program is free
364 software; you can redistribute it and/or modify it under the same terms as
365 Perl itself.
366  
367 =cut
368  
369  
370  
« blib/lib/Chemistry/Ring/Find.pm ↑ Summary blib/lib/Parse/Yapp/Driver.pm »