In order to tune up your queries before executing them on the whole database or just to try out an interactive work with the language, feel free to use 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 in smaller chunks, think a query for each of the pieces and them wisely bind them together. Let us have a goal:

Get all the residues which are as much as 5A away from any histidine residue and check if the given fragment 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 language reference). For given problem, the decomposition is as follows:

Select histidine residues
Select residual surrounding of a fragment up to 5A.
Find negatively charged residues.
Count the amino acids.
Filter the histidine plus its surrounding matching the condition above.

Now we are ready for constructing individual queries:

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:

Residues("HIS").
  AmbientResidues(5).
  Filter(lambda l: l.Count(AminoAcids(ChargeType = "Negative")) >= 2)

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 to three plus one part which differs by data type queries are operated (Atoms, Residues and Fragments). 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 Fragments, which contain numerous advanced queries demonstrating versatility and power of MQ. 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 use cases.

Structure of the text

[PDB ID] Here you find an example PDB ID where you can try out the query with MotiveExplorer and a rough description of the query function.
This is followed by examples of this query with with the explanation such as Residues("HEM"). Copy this query to the command text box in MotiveExplorer 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 Atoms() take 0..n strings, representing elements, in parenthesis ("C", "N", etc.) and based on the input returns a list of individual atoms.

Queries

Atoms

Basic queries

Atoms()

[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.
Atoms("Fe") - Returns all iron atoms in the given structure.
Atoms("Fe", "N") - Returns all iron and nitrogen atoms in the given structure.
Type: Atoms(symbols: String*) -> Atoms.

AtomNames()

[2hhb] Returns a sequence of atoms with defined name or names.
AtomNames("CA") – Returns all CA atoms.
AtomNames("CA", "N") –Returns atoms with names CA (C? carbon) or N (terminal part of amino acids).
Type: AtomNames(names: String+) -> Atoms.

AtomIds()

[2hhb] Returns a sequence of atoms with given id or ids
AtomIds(1) – Returns atom with id=1 from the given structures.
AtomIds(1,2,5) - Returns atoms with id=1, 2 and 5 from the given structures.
Type: AtomIds(ids: Integer+) -> Atoms.

AtomIdRange()

[2hhb] Returns a sequence of atoms with ids from a given range (inclusive specified indices).
AtomIdRange(1, 10) – returns 10 atoms with IDs from the interval <1, 10>, as specified in the input file.
Type: AtomIdRange(minId: Integer, maxId: ?Integer) -> Atoms

NotAtomNames()

[2hhb] Returns a sequence of atoms which are not defined by an argument.
NotAtomNames("C", "N", "CA", "O") – 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()

[2hhb] Returns a sequence of atoms which does not have a defined id
NotAtomIds(1) - Returns atom with id other but 1 from the given structures.
NotAtomIds(1,2,5) - Returns atoms with id other but 1,2 and 5 from the given structures.
Type: NotAtomIds(ids: Integer+) -> Atoms.

NotAtoms()

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

RingAtoms()

[2hhb] Returns specified atoms found on detected rings .
RingAtoms(Atoms("N"), Rings(2 * ["C"] + ["N"] + ["C"] + ["N"])) – Returns all the nitrogen atoms on the histidine sidechain.
Type: RingAtoms(atom: Atoms, ring: ?Rings) -> Atoms.

Residues

Basic queries

Residues()

[2hhb] Returns a sequence of individual residues specified by a function argument. More residues can be specified, if separated by a comma.
Residues("HEM") – Returns a list of HEM residues.
Residues ("HEM", "ALA") – Returns a set of HEM and ALA residues.
Type: Residues(names: Value*) -> Residues.

NotResidues()

[2hhb] Returns a sequence of residues which are not defined by the argument.
NotResidues("HEM") – returns a set of residues, which does not have a HEM in their name.
Type: NotResidues(names: Value+) -> Residues.

ResidueIds()

[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”.
ResidueIds ("14 A", "15 A") – Returns 14th and 15th residue of chain A.
Type: ResidueIds(ids: String+) -> Residues.

ResidueIdRange()

[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.
ResidueIdRange("A", 50, 100) – returns a set of residues on chain A from the ID 50 to 100.
Type: ResidueIdRange(chain: String, min: Integer, max: Integer) -> Residues.

NotAminoAcids()

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

AminoAcids()

[2hhb] Returns a sequence of residues that are among the 20 standard amino acids.
Allowed values: Positive, Negative, Aromatic, Polar, NonPolar
AminoAcids() – Returns all standard amino acids.
AminoAcids(ChargeType=”Polar”) – Returns all polar amino acids based on the type of their side chain.
Type: AminoAcids() -> Residues.

HetResidues()

[2hhb] Returns a sequence of heteroatom residues as specified in input PDB files, excluding residues.
HetResidues() – A set of hetatom residues.
Type: HetResidues() -> Residues

Fragments

Structure specification

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

Rings()

[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.
Rings(2 * ["C"] + ["N"] + ["C"] + ["N"]) – Returns the histidine aromatic ring.
Rings(4 * ["C"] + ["O"]) – Returns pentose ring.
Type: Rings(atoms: Value*) -> Ring

ToAtoms()

[1hho] Converts the input motive into a sequence of individual atoms, i.e. each motive contains a single atom.
Residues("HEM").ToAtoms() – Returns all the atoms of HEM residues as a sequence of individual atoms.
Type: ToAtoms(motives: Fragments) -> Fragments

ToResidues()

[1hho] Converts the input motive into a sequence of individual residues, i.e. It can either decompose a motif with multiple residues to a sequence of motives each containing a single residue, or if applied to a sequence of atoms merge atoms to a single motif per residue.
Residues("HEM").AmbientResidues(2).ToResidues() – Returns the sequence of individual residues from the 2A surrounding of the HEM residue, inclusive HEM.
Atoms("C").ToResidues() – Returns a sequence of motifs. Each motif contains only carbon atoms grouped together according to their parent residue.
Type: ToResidues(motives: Fragments) -> Fragments

Union()

[1hho] Merges the sequence of input motives to a single motiv.
Residues("HEM").ConnectedResidues(1).Union() – Takes two HEM residues of the 1hho protein with covalently bonded residues (2 motives) and merges them into a single motiv.
Type: Union(motives: Fragments) -> Fragments

RegularMotifs()

From the primary sequence extracts motives based on the input regular expression. Please note, that MQ does not check whether there is a gap in the chain e.g. if HIS 28 is followed by the residue 30 ALA query ‘HA’ returns positive match for such example.
RegularMotifs("HH") – Finds two consecutive histidine residues.
RegularMotifs("G.{1,2}G") – Finds two glycine residues separated by one or two other residues.
RegularMotifs("G.{1,2}G").Filter(lambda m: m.IsConnected()) – Finds two glycine residues separated by one or two residues and verifies that all of them are bonded.
Type: RegularMotifs(regex: Value) -> Fragments

Cluster()

Clusters identified results to a single motive based on their distance in angstroms. On contrary to the Near() query Cluster() does not provide a count check. See example below.
Cluster(5, Residues("Ala")) – Returns all the alanine residues which are at most 5A distant to each other.
Cluster(3, RingAtoms(Atoms("N"), Rings(2 * ["C"] + ["N"] + ["C"] + ["N"]))) – Returns all the nitrogen atoms from particular rings to a single motif in case the atoms are at most 3A distant to each other.
Cluster(2 , Atoms("C"), Atoms("C")) – Returns all the carbon atoms which are pairwise closer than 2A. 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 Near() query instead.
Type: Cluster(r: Number, motives: Fragments+) -> Fragments

Boolean operations

Or()

[2hhb] Merges up to n different motives together.
Or(AminoAcids(ChargeType="Negative"),AminoAcids(ChargeType= "Positive")) – returns all charged amino acids both positively charged and negatively charged.
Type: Or(motives: Fragments+) -> Fragments

Topology function

AmbientAtoms()

[1hho] Returns all the atoms, which are within n A from the geometrical center of a given motif.
Atoms("Fe").AmbientAtoms(4) – returns all the atoms, which are closer than 4A from the center of mass of iron atom.
Type: AmbientAtoms(motive: Fragments, r: Number) -> Fragments

AmbientResidues()

[1hho] Returns all the residues, which are within n A from the geometrical center of a given motif.
Residues("HEM").AmbientResidues(4) – returns all the residues, which are closer than 4A from the center of mass of HEM residues.
Type: AmbientResidues(motive: Fragments, r: Number) -> Fragments'

Near()

[1hho] Clusters all the specified motives, which are pairwise closer in Angströms than a specified argument. Additionally, it checks if the motive contains exactly specified motives. On the contrary to the Cluster() query this does the ‘count check’.
Near(0, Rings(6*['C']), Rings(4*['C'] + ['N'])) – Returns motives containing only purine. In this example the purine part of tryptophan side chain will be returned.
Near(2 , Atoms("C"), Atoms("C"), Atoms("C"), Atoms("C")) – Returns motives which contain exactly 4 carbon atoms within a sphere of 2A.
Type: Near(r: Number, motives: Fragments+) -> Fragments

Filtering

Filter()

[1hho] Basically, an argument of the function is a Boolean condition, which is evaluated of each and every motive of input sequence of motives. 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 motives, the usage is the same as in the Python programming language, and therefore, your previous Python experiences are beneficial.
Residues().Filter(lambda m: m.IsConnectedTo(Atoms("Fe"))) – returns a set of motives from all residues which are covalently bonded to the iron atom (excluded the HEM residue).
Residues().Filter(lambda m: m.Count(Atoms("O")) == 2) returns all the residues containing exactly two oxygen atoms.
Type: Filter(motives: Fragments, filter: Fragment->Bool) -> Fragments

Count()

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

Contains()

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

Connectivity

IsConnected()

[4m9e, 4m9v] Checks, whether a particular motif is composed of a single component
Atoms("Zn").AmbientAtoms(4).Filter(lambda m: m.IsConnected()) – 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 Atoms("Zn").AmbientAtoms(4)
Type: IsConnected(motive: Fragment) -> Bool.

IsConnectedTo()

[1hho] Checks if the two provided motives are connected one to another.
Residues("ALA").Filter(lambda m: m.IsConnectedTo(Residues("GLY"))) – Returns all the alanine residues which are directly connected to the glycine residues.
Type: IsConnectedTo(current: Fragment, motive: Fragments) -> Bool

IsNotConnectedTo()

[1hho] Checks if the two provided motives are NOT connected one to another.
Residues("ALA").Filter(lambda m: m.IsNotConnectedTo(Residues("GLY"))) – Returns all the alanine residues which are not directly connected to the glycine residues.
Type: IsNotConnectedTo(current: Fragment, motive: Fragments) -> Bool

ConnectedAtoms()

[1hho] Returns n directly bonded layer of atoms to a given motive.
Atoms("Fe").ConnectedAtoms(1) – The iron atom and all the atoms which are covalently bonded to it over a single bond.
Atoms("Fe"). ConnectedAtoms (2) – 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(motive: Fragments, n: Integer) -> Fragments

ConnectedResidues()

[1hho] Returns n directly bonded layer of residues to a given motive.
Residues("HEM").ConnectedResidues(1) – The HEM residue and all the residues which are covalently bonded to any atom of the HEM residue.
Residues("HEM").ConnectedResidues(2) – previous selection and all the residues which are covalently bonded to them (i.e. additional layer of bonded residues).
Type: ConnectedResidues(motive: Fragments, n: Integer) -> Fragments

PatternQuery:How to build a query

Contents

How to think about queries

Ready-to-use examples

Structure of the text

Queries

Atoms

Basic queries

Atoms()

AtomNames()

AtomIds()

AtomIdRange()

NotAtomNames()

NotAtomIds()

NotAtoms()

RingAtoms()

Residues

Basic queries

Residues()

NotResidues()

ResidueIds()

ResidueIdRange()

NotAminoAcids()

AminoAcids()

HetResidues()

Fragments

Structure specification

Rings()

ToAtoms()

ToResidues()

Union()

RegularMotifs()

Cluster()

Boolean operations

Or()

Topology function

AmbientAtoms()

AmbientResidues()

Near()

Filtering

Filter()

Count()

Contains()

Connectivity

IsConnected()

IsConnectedTo()

IsNotConnectedTo()

ConnectedAtoms()

ConnectedResidues()

Navigation menu

Search