Editing PatternQuery:Principles (section)

==Example, Part One==

Let’s assume we have loaded a protein stored in a PDB or mmCIF file with correctly annotated HET groups and '''we want to find all HET residues in it'''.

The characteristics of an imperative approach is explicitly stating steps that need to be performed in order achieve a particular goal. In contrast a declarative approach states the goal we would like to achieve, leaving the individual steps as an "implementation detail".

Using the imperative approach, we would do something like this:

<syntaxhighlight lang="python">
result = List()
for residue in molecule.Residues:
  if residue.IsHet():
    result.Add(residue)
</syntaxhighlight>

In the declarative approach, our code would look like this:

<syntaxhighlight lang="python">
HetResidues()
</syntaxhighlight>

Now, let’s extend our example to "all HET residues and atoms within 4A around them".

In the imperative approach we would need to do something along the following lines:

<syntaxhighlight lang="python">
temp = List()

for residue in molecule.Residues():
  if residue.IsHet():
    temp.Add(residue)

neighborhoodLookup = NeighborhoodLookup(molecule.Atoms())
result = List()

for residue in temp:
  surroundings = neiborhoodLookup.Find(residue.Atoms, 4.0)
  result.Add(union(residue, surroundings))

return result
</syntaxhighlight>

Declaratively, our code would be just:

<syntaxhighlight lang="python">
HetResidues().AmbientAtoms(4.0)
</syntaxhighlight>

Internally, the function <code>[[PatternQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code> might run code similar to the imperative version. However, what is important is that this complexity is hidden from the user when the declarative approach is used.

Now, let’s extend our example even further: "all HET residues and atoms within 4A around them, where the entire structure contains at least one calcium atom".

We will not bother the reader with writing down the imperative version - implementing the condition "at least one calcium atom" is rather boring. However, using the declarative approach, the description of the pattern becomes simply:

<syntaxhighlight lang="python">
HetResidues()
  .AmbientAtoms(4.0)
  .Filter(lambda m: m.Count(Atoms('Ca')) >= 1)
</syntaxhighlight>