View source for PatternQuery:How to build a query

<div class="toclimit-3">

In order to tune up your queries before executing them on the whole database or just to work with the language interactively, feel free to use the [http://webchem.ncbr.muni.cz/Platform/PatternQuery/Index '''Explorer'''] application, where you can upload a PDB molecule of choice, or load a random sample from the PDB database based on selected properties.

You can either try one of our ready-to-use examples or try to make up one of your own.

==How to think about queries==
When building queries, you have to decompose the problem into smaller chunks, think of a query for each of the pieces and then wisely bind them together. Let us have a goal:

'''Get all the residues which are as much as 5Å away from any histidine residue and check if the given pattern contains at least 2 negatively charged amino acids.'''

From scratch you can't probably think out a solution right now, but when you decompose the problem into separate individual sub problems, it is not so difficult after all. (Whenever you are unsure about the meaning of the queries, consult the [[PatternQuery:Language Reference | language reference]]). For the given problem, the decomposition and the corresponding queries are as follows:
{{col-begin}}
{{col-2}}
#Select histidine residues
#Select residual surrounding of a pattern up to 5Å.
#Find negatively charged residues.
#Count the amino acids.
#Filter the histidine plus its surrounding matching the condition above.
{{col-2}}
#<code>[[PatternQuery:Language Reference#Residues | Residues("HIS")]]</code>
#<code>[[PatternQuery:Language Reference#AmbientResidues | AmbientResidues(5)]]</code>
#<code>[[PatternQuery:Language Reference#AminoAcids| AminoAcids(ChargeType="Negative")]]</code>
#<code>[[PatternQuery:Language Reference#Count| Count(residues)]]</code>
#<code>[[PatternQuery:Language Reference#Filter| Filter(condition)]]</code>
{{col-end}}
It wasn't that difficult, was it? When we have composed all the queries, we can compose them together in order to achieve our goal as highlighted in the query bellow and in the illustrative info-graphics:

<syntaxhighlight lang="python">
Residues("HIS").
  AmbientResidues(5).
  Filter(lambda l: l.Count(AminoAcids(ChargeType = "Negative")) >= 2)
</syntaxhighlight>

[[Image:PatternQuery-Representation.png | center]]

==Ready-to-use examples==

Now when we are aware of how to think about queries, you are ready to browse a plenty of different examples listed below. The text is separated into three plus one part which differs by data type queries are operated (Atoms, Residues and Patterns). The first two categories deal with only basic ''Atom'' or ''Residue'' selections. Outputs of these two types of queries are Atoms and Residues respectively.  Last category is 'Patterns', which contains a number of advanced queries, these queries demonstrate versatility and a power of '''PQ'''. These queries operate on all results provided by both Atom and Residue queries. On the top of that, you can browse several use biologically relevant [[PatternQuery:Use Cases | use cases]].


==Structure of the text==
*'''[PDB id]''' Here you find an example PDB id where you can try out the query with '''PatternQuery Explorer''' and a rough description of the query function.
* This is followed by examples of this query with with the explanation such as <syntaxhighlight lang="python" inline="">Residues("HEM")</syntaxhighlight>. Copy this query to the command text box in '''PatternQuery Explorer''' application and immediately see the results.
* Type of data query operate on and the expected returned value.
* e.g. ''Type: Atoms(symbols: String*) -> Atoms''. query <code>[[PatternQuery:Language Reference#Atoms | Atoms()]]</code> take 0..n strings, representing elements, in parenthesis ("C", "N", etc.) and based on the input returns a list of individual atoms.

=Queries=

==Atoms==
{{big | Basic queries}}
====Atoms()====
* '''[PDB id: 2hhb]''' Returns a sequence of individual atoms based on element type provided in the argument. More elements can be specified, if separated by a comma. In case no argument is provided a list of all the atoms is returned.
*<syntaxhighlight lang="python" inline="">Atoms("Fe")</syntaxhighlight> - Returns all iron atoms in the given structure.
*<syntaxhighlight lang="python" inline="">Atoms("Fe", "N")</syntaxhighlight> - Returns all iron and nitrogen atoms in the given structure.
* ''Type: Atoms(symbols: String*) -> Atoms.''


====AtomNames()====
* '''[PDB id: 2hhb]''' Returns a sequence of atoms with defined name or names.
* <syntaxhighlight lang="python" inline="">AtomNames("CA")</syntaxhighlight> – Returns all CA atoms.
* <syntaxhighlight lang="python" inline="">AtomNames("CA", "N")</syntaxhighlight> –Returns atoms with names CA (C? carbon) or N (terminal part of amino acids).
* ''Type: AtomNames(names: String+) -> Atoms.''


====AtomIds()====
* '''[PDB id: 2hhb]''' Returns a sequence of atoms with given id or ids
* <syntaxhighlight lang="python" inline="">AtomIds(1)</syntaxhighlight> – Returns atom with id=1 from the given structures.
* <syntaxhighlight lang="python" inline="">AtomIds(1,2,5) </syntaxhighlight>- Returns atoms with id=1, 2 and 5 from the given structures.
* ''Type: AtomIds(ids: Integer+) -> Atoms.''


====AtomIdRange()====
* '''[PDB id: 2hhb]''' Returns a sequence of atoms with ids from a given range (inclusive specified indices).
* <syntaxhighlight lang="python" inline="">AtomIdRange(1, 10)</syntaxhighlight> – returns 10 atoms with IDs from the interval <1, 10>, as specified in the input file.
* ''Type: AtomIdRange(minId: Integer, maxId: ?Integer) -> Atoms''


====NotAtomNames()====
* '''[PDB id: 2hhb]''' Returns a sequence of atoms which are not defined by an argument.
* <syntaxhighlight lang="python" inline="">NotAtomNames("C", "N", "CA", "O")</syntaxhighlight> – returns all the atoms with names other than C, CA, N and O.  i.e. only the side chain atoms of the protein .
* ''Type: NotAtomNames(names: String+) -> Atom.''


====NotAtomIds()====
* '''[PDB id: 2hhb]''' Returns a sequence of atoms which does not have a defined id
* <syntaxhighlight lang="python" inline="">NotAtomIds(1)</syntaxhighlight> - Returns atom with id other but 1 from the given structures.
* <syntaxhighlight lang="python" inline="">NotAtomIds(1,2,5)</syntaxhighlight> - Returns atoms with id other but 1,2 and 5 from the given structures.
* ''Type: NotAtomIds(ids: Integer+) -> Atoms.''


====NotAtoms()====
* '''[PDB id: 2hhb]''' Returns all the atoms not specified in the argument. More elements can be specified, if separated by a comma.
* <syntaxhighlight lang="python" inline="">Atoms("Fe")</syntaxhighlight> – returns all the atoms of the structure, but iron.
* <syntaxhighlight lang="python" inline="">Atoms("Fe", "N")</syntaxhighlight> returns all the atoms of the structure, but iron and nitrogen. 
* ''Type: NotAtoms(symbols: String+) -> Atoms.''


====RingAtoms()====
* '''[PDB id: 2hhb]''' Returns specified atoms found on detected rings .
* <syntaxhighlight lang="python" inline="">RingAtoms(Atoms("N"), Rings(2 * ["C"] + ["N"] + ["C"] + ["N"]))</syntaxhighlight> – Returns all the nitrogen atoms on the histidine side chain.
* ''Type: RingAtoms(atom: Atoms, ring: ?Rings) -> Atoms.''


==Residues==
{{big | Basic queries}}
====Residues()====
* '''[PDB id: 2hhb]''' Returns a sequence of individual residues specified by a function argument. More residues can be specified, if separated by a comma.
* <syntaxhighlight lang="python" inline="">Residues("HEM")</syntaxhighlight> – Returns a list of HEM residues.
* <syntaxhighlight lang="python" inline="">Residues ("HEM", "ALA")</syntaxhighlight> – Returns a set of HEM and ALA residues.
* ''Type: Residues(names: Value*) -> Residues.''


====NotResidues()====
* '''[PDB id: 2hhb]''' Returns a sequence of residues which are not defined by the argument.
* <syntaxhighlight lang="python" inline="">NotResidues("HEM")</syntaxhighlight> – returns a set of residues, which does not have a HEM in their name.
* ''Type: NotResidues(names: Value+) -> Residues.''


====ResidueIds()====
* '''[PDB id: 2hhb]''' Returns a sequence of specified residues in case the structure contains them. Each residue is represented by its PDB ID and chain such as “A 8”.
* <syntaxhighlight lang="python" inline="">ResidueIds ("14 A",  "15 A")</syntaxhighlight> – Returns 14th  and 15th residue of chain A.
* ''Type: ResidueIds(ids: String+) -> Residues''.


====ResidueIdRange()====
* '''[PDB id: 2hhb]''' Returns a set of residues on a given chain from the lower to the upper index. In case a residue is not provided in the structure, it is skipped. 
* <syntaxhighlight lang="python" inline="">ResidueIdRange("A", 50,  100)</syntaxhighlight> – returns a set of residues on chain A from the ID 50 to 100. 
* ''Type: ResidueIdRange(chain: String, min: Integer, max: Integer) -> Residues''.


====NotAminoAcids()====
* '''[PDB id: 2hhb]''' Returns a sequence of residues that are not among the 20 standard amino acids. Allowed values for an optional parameter NoWaters: True, False.
* <syntaxhighlight lang="python" inline="">NotAminoAcids()</syntaxhighlight> – Returns all the nonstandard residues incorporated in the protein structure with the exception of HOH and WAT residues, which stands for solvent.
* <syntaxhighlight lang="python" inline="">NotAminoAcids(NoWaters=False)</syntaxhighlight> – Returns all the nonstandard residues incorporated in the protein structure inclusive solvent (HOH and WAT residues).
* ''Type: NotAminoAcids() -> Residues''.


====AminoAcids()====
*  '''[PDB id: 2hhb]''' Returns a sequence of residues that are among the 20 standard amino acids.
* Allowed values: <syntaxhighlight lang="python" inline="">Positive, Negative, Aromatic, Polar, NonPolar</syntaxhighlight>
* <syntaxhighlight lang="python" inline="">AminoAcids()</syntaxhighlight> – Returns all standard amino acids.
* <syntaxhighlight lang="python" inline="">AminoAcids(ChargeType="Polar")</syntaxhighlight> – Returns all polar amino acids based on the type of their side chain.
* ''Type: AminoAcids() -> Residues.''


====HetResidues()====
* '''[PDB id: 2hhb]''' Returns a sequence of heteroatom residues as specified in input PDB files, excluding residues.
* <syntaxhighlight lang="python" inline="">HetResidues()</syntaxhighlight> – A set of hetatom residues.
* ''Type: HetResidues() -> Residues''


==Patterns==
{{big | Structure specification}}

PQ can select residues or their parts based on their name or Id, however, the true power of PQ lies in its ability to utilize the geometrical and chemical nature of the input structures and select patterns purely based on elements, topology and the connectivity among them.


====Rings()====
* '''[PDB id: 3d12]''' Returns all the rings in the protein structure specified by a user.  Any structural ring can be identified by concatenating individual elements the string is composed from.
* <syntaxhighlight lang="python" inline="">Rings(2 * ["C"] + ["N"] + ["C"] + ["N"])</syntaxhighlight> – Returns the histidine aromatic ring. 
* <syntaxhighlight lang="python" inline="">Rings(4 * ["C"] + ["O"])</syntaxhighlight> – Returns pentose ring. 
* ''Type: Rings(atoms: Value*) -> Ring''


====ToAtoms()====
* '''[PDB id: 1hho]''' Converts the input pattern into a sequence of individual atoms, i.e. each pattern contains a single atom.
* <syntaxhighlight lang="python" inline="">Residues("HEM").ToAtoms()</syntaxhighlight> – Returns all the atoms of HEM residues as a sequence of individual atoms.
* ''Type: ToAtoms(patterns: Patterns) -> Patterns''


====ToResidues()====
* '''[PDB id: 1hho]''' Converts the input pattern into a sequence of individual residues, i.e. It can either decompose a pattern with multiple residues to a sequence of patterns each containing a single residue, or if applied to a sequence of atoms merge atoms to a single pattern per residue.
* <syntaxhighlight lang="python" inline="">Residues("HEM").AmbientResidues(2).ToResidues()</syntaxhighlight> – Returns the sequence of individual residues from the 2A surrounding of the HEM residue, inclusive HEM.
* <syntaxhighlight lang="python" inline="">Atoms("C").ToResidues()</syntaxhighlight> – Returns a sequence of patterns. Each pattern contains only carbon atoms grouped together according to their parent residue.
* ''Type: ToResidues(patterns: PatternSeq) -> Patterns''


====Union()====
* '''[PDB id: 1hho]''' Merges the sequence of input patterns to a single pattern. 
* <syntaxhighlight lang="python" inline="">Residues("HEM").ConnectedResidues(1).Union()</syntaxhighlight> –  Takes two HEM residues of the 1hho protein with covalently bonded residues (2 patterns) and merges them into a single pattern.
* ''Type: Union(patterns: PatternSeq) -> Patterns''


====RegularMotifs()====
* '''[PDB id: 1het]''' Sequence motifs is extracted from the primary sequence based on the input regular expression. Please note, that PQ does not check presence of a gap gap in the chain e.g. if HIS 28 is followed by the residue 30 ALA query ‘HA’ returns positive match for such example.
* In case the information about posttranslational modifications is present in ''MODRES'' or ''_pdbx_struct_mod_residue'' fields, modified residues are treated as standard amino acids. Therefore, a letter ''P'' stands for a proline residue so as all its modifications, e.g. '''HYP''' (hydroxyproline). 
* <syntaxhighlight lang="python" inline=""> RegularMotifs("HH")</syntaxhighlight> – Finds two consecutive histidine residues or their modifications. 
* <syntaxhighlight lang="python" inline=""> RegularMotifs("G.{1,2}G")</syntaxhighlight> – Finds two glycine residues separated by one or two other residues. 
* <syntaxhighlight lang="python" inline=""> RegularMotifs("G.{1,2}G").Filter(lambda m: m.IsConnected())</syntaxhighlight> – Finds two glycine residues separated by one or two residues and verifies that all of them are bonded. 
* <syntaxhighlight lang="python" inline=""> RegularMotifs(".P.").Filter(lambda l: l.Count(NotAminoAcids()) == 0)</syntaxhighlight> - Finds 3 consecutive residues, where the middle one is proline and verifies that neither of them is outside the ''standard 20''.
* ''Type: RegularMotifs(regex: Value) -> Patterns''


====Cluster()====
* Clusters identifies results to a single pattern based on their distance [A]. On contrary to the <syntaxhighlight lang="python" inline="">Near()</syntaxhighlight> query <syntaxhighlight lang="python" inline="">Cluster()</syntaxhighlight> does not provide a count check. See example below.
* <syntaxhighlight lang="python" inline="">Cluster(5, Residues("Ala"))</syntaxhighlight>  – Returns all the alanine residues which are at most 5A distant to each other.
* <syntaxhighlight lang="python" inline="">Cluster(3, RingAtoms(Atoms("N"), Rings(2 * ["C"] + ["N"] + ["C"] + ["N"])))</syntaxhighlight> – Returns all the nitrogen atoms from particular rings to a single pattern in case the atoms are at most 3A distant to each other. 
* <syntaxhighlight lang="python" inline="">Cluster(2 , Atoms("C"), Atoms("C"))</syntaxhighlight> – Returns all the carbon atoms which are pairwise closer than 2Å. In case any other carbon atom would be inside this 2A sphere, it is also included in the result. Therefore, if you insist on exactly 2 carbon atoms to be returned, use <syntaxhighlight lang="python" inline="">Near()</syntaxhighlight> query instead.
* ''Type: Cluster(r: Number, patterns: PatternSeq) -> Patterns''


===Boolean operations===
====Or()====
* '''[PDB id: 2hhb]''' Merges up to ''n'' different patterns together.
* <syntaxhighlight lang="python" inline="">Or(AminoAcids(ChargeType="Negative"), AminoAcids(ChargeType= "Positive"))</syntaxhighlight> – returns all charged amino acids both positively charged and negatively charged.
* ''Type: Or(patterns: PatternSeq+) -> Patterns''


===Topology function===
====AmbientAtoms()====
* '''[PDB id: 1hho]''' Returns all the atoms, which are within nÅ from the geometrical center of a given pattern.
* <syntaxhighlight lang="python" inline="">Atoms("Fe").AmbientAtoms(4)</syntaxhighlight> – returns all the atoms, which are closer than 4Å from the center of mass of iron atom.
* ''Type: AmbientAtoms(pattern: PatternSeq, r: Number) -> Patterns''


====AmbientResidues()====
* '''[PDB id: 1hho]''' Returns all the residues, which are within nÅ from the geometrical center of a given pattern.
* <syntaxhighlight lang="python" inline="">Residues("HEM").AmbientResidues(4)</syntaxhighlight> – returns all the residues, which are closer than 4Å from the center of mass of HEM residues.
* ''Type: AmbientResidues(pattern: PatternSeq, r: Number) -> Patterns'''


====Near()====
* '''[PDB id: 1hho]''' Clusters all the specified patterns, which are pairwise closer [Å] than a specified argument. Additionally, it checks if the pattern contains exactly specified patterns. On the contrary to the Cluster() query this does the ‘count check’.
* <syntaxhighlight lang="python" inline="">Near(0, Rings(6*['C']), Rings(4*['C'] + ['N']))</syntaxhighlight> – Returns patterns containing only purine. In this example the purine part of tryptophan side chain will be returned.
* <syntaxhighlight lang="python" inline="">Near(2 , Atoms("C"), Atoms("C"), Atoms("C"), Atoms("C"))</syntaxhighlight> – Returns patterns which contain exactly 4 carbon atoms within a sphere of 2Å.
* ''Type: Near(r: Number, patterns: PatternSeq+) -> Patterns''


====Inside()====
* '''[PDB id: 1hho]''' Inside query tries to identify given pattern within another pattern. It is particularly useful for location of specific atomic arrangements within a more general ones.
* <syntaxhighlight lang="python" inline="">Residues("Gly").Inside(Chains("A"))</syntaxhighlight> - Returns glycine residues found on the chain A.
* <syntaxhighlight lang="python" inline="">Atoms("S").Inside(HetResidues())</syntaxhighlight> - Returns sulphur atoms found in the heteroatom residues
* ''Type: Inside(patterns&#58; PatternSeq, where&#58; PatternSeq) -&gt; PatternSeq''

===Filtering===
====Filter()====
* '''[PDB id: 1hho]''' Filtering is used for removing unwanted patterns from the result. A condition given as a function argument is evaluated for each pattern from input pattern sequence referred to as ‘m’ in the following text. Only results satisfying the condition are returned, others are filtered out. Technically, it uses lambda abstraction for filtering a collection of input patterns. The usage is the same as in the Python programming language, and therefore, your previous Python experiences are beneficial. 
* <syntaxhighlight lang="python" inline="">Residues().Filter(lambda m: m.IsConnectedTo(Atoms("Fe"))) </syntaxhighlight> – returns a set of patterns from all residues which are covalently bonded to the iron atom (excluded the HEM residue).
* <syntaxhighlight lang="python" inline=""> Residues().Filter(lambda m: m.Count(Atoms("O")) == 2)</syntaxhighlight> returns all the residues containing exactly two oxygen atoms.
* ''Type: Filter(patterns: PatternSeq, filter: Pattern->Bool) -> Patterns''


====Count()====
* '''[PDB id: 1hho]''' Usually it is convenient to utilize this function inside a filtering query. The <syntaxhighlight lang="python" inline="">Count()</syntaxhighlight> query counts the number of occurrences of a pattern inside a different pattern.
* <syntaxhighlight lang="python" inline="">Residues("HEM").ConnectedResidues(2).Filter(lambda m: m.Count(Atoms("S")) == 1)</syntaxhighlight> – Returns patterns composed of a HEM residue surrounded by two layers of bonded residues in case that the whole pattern contains exactly one sulphur atom.
* <syntaxhighlight lang="python" inline="">Residues("CYS").ConnectedResidues(1).Filter(lambda m: m.Count(Residues("VAL")) == 2)</syntaxhighlight> – Returns a cysteine residue which is surrounded from both sides by valine residues.
* ''Type: Count(where: Pattern, what: PatternSeq) -> Integer''.

====Contains()====
* '''[PDB id: 4hhb]''' <syntaxhighlight lang="python" inline="">Contains()</syntaxhighlight> query checks if the input pattern contains a specified pattern of interest. In other words Contains() query is similar to a query, where the number of occurrences is higher than zero <syntaxhighlight lang="python" inline="">(Count() > 0)</syntaxhighlight>
* <syntaxhighlight lang="python" inline="">Residues("HEM").AmbientResidues(2).Filter(lambda m: m.Contains(Residues("HIS")))</syntaxhighlight> – Returns patterns, where any atom of HEM residue is at most 2A distant from the histidine.
* <syntaxhighlight lang="python" inline="">Residues().Filter(lambda m: m.Contains(Atoms("S")))</syntaxhighlight> – Returns all the residue which has a sulphur incorporated in their structure. For this particular example it is similar to the query <syntaxhighlight lang="python" inline="">Residues("CYS", "MET")</syntaxhighlight>.
* ''Type: Contains(where: Pattern, what: PatternSeq) -> Bool''


===Connectivity===
====IsConnected()====
* '''[PDB id: 4m9e, 4m9v]''' Checks, whether a particular pattern is composed of a single component
* <syntaxhighlight lang="python" inline="">Atoms("Zn").AmbientAtoms(4).Filter(lambda m: m.IsConnected())</syntaxhighlight> – Atoms which are at most 4 A distant from the zinc atom and are all binded together, i.e. there is no outlier.
* For comparison please compare with the results of the query <syntaxhighlight lang="python" inline="">Atoms("Zn").AmbientAtoms(4)</syntaxhighlight>
* ''Type: IsConnected(pattern: Pattern) -> Bool.''


====IsConnectedTo()====
* '''[PDB id: 1hho]''' Checks if the two provided patterns are connected one to another. 
* <syntaxhighlight lang="python" inline="">Residues("ALA").Filter(lambda m: m.IsConnectedTo(Residues("GLY")))</syntaxhighlight> – Returns all the alanine residues and directly connected glycine residues.
* ''Type: IsConnectedTo(current: Pattern, patterns: PatternSeq) -> Bool''


====IsNotConnectedTo()====
* '''[PDB id: 1hho]''' Checks if the two provided patterns are NOT connected one to another.
* <syntaxhighlight lang="python" inline="">Residues("ALA").Filter(lambda m: m.IsNotConnectedTo(Residues("GLY")))</syntaxhighlight> – Returns all the alanine residues which are not directly connected to the glycine residues.
* ''Type: IsNotConnectedTo(current: Pattern, patterns: PatternSeq) -> Bool''


====ConnectedAtoms()====
* '''[PDB id: 1hho]''' Returns ''n'' directly bonded layer of atoms to a given pattern.
* <syntaxhighlight lang="python" inline="">Atoms("Fe").ConnectedAtoms(1)</syntaxhighlight> – The iron atom and all the atoms which are covalently bonded to it over a single bond.
* <syntaxhighlight lang="python" inline="">Atoms("Fe").ConnectedAtoms (2)</syntaxhighlight> – Previous selection and all the atoms which are covalently bonded to them (i.e. additional layer of bonded atom). In other words the output composes of all the atoms which are 2 bonds away from the iron atom.
* ''Type: ConnectedAtoms(pattern: PatternSeq, n: Integer) -> Patterns''


====ConnectedResidues()====
* '''[PDB id: 1hho]''' Returns n directly bonded layer of residues to a given pattern.
* <syntaxhighlight lang="python" inline="">Residues("HEM").ConnectedResidues(1)</syntaxhighlight> – The HEM residue and all the residues which are covalently bonded to any atom of the HEM residue.
* <syntaxhighlight lang="python" inline="">Residues("HEM").ConnectedResidues(2)</syntaxhighlight> – previous selection and all the residues which are covalently bonded to them (i.e. additional layer of bonded residues).
* ''Type: ConnectedResidues(pattern: PatternSeq, n: Integer) -> Patterns''