Jump to content

PatternQuery:Language Reference

From WebChemistry Wiki
Revision as of 03:25, 7 June 2013 by Dave (talk | contribs)

Introduction

DISCLAIMER: This is an early version of the MotiveQuery language. There is probably a lot of bugs. Individual function names and syntax are all subject to change.

MotiveQuery is a subset of the Python programming language. Therefore, if you have experience with it, it should not be a problem to use MQ as well.

  • The language is case sensitive - "filter" is NOT the same as "FiLtEr".

Some of the functions return Motives while other only Motive.

  • Motive is a set of atoms.
  • Motives is a sequence of motives (the sets of atoms).

When a molecule is queried say using the expression Rings(5 * ["C"] + ["O"]) a sequences of motives each containing 6 atoms (5 C and 1 O) is returned. However, some functions such as Filter need to operate on a single motive (the set of atoms) - not the whole sequences. The query Filter(Residues(), lambda r: r.Count(Atoms()) > 10) first finds all residue Motives (sequence) and then passes every single Motive (set of atoms) to a function that counts the atoms in the motive and returns True if there is at least 11 of them. This is the reasoning behind these two types.

Elementary Types

Basic value types.

Bool

Example
True
True value.

Integer

Example
42
The ultimate answer.

Real

Example
12.87
Real number.

String

Example
"aBcD"
String.

Symbol

Example
x
The 'x' identifier.


Basic Language Syntax

Basic syntactic elements the MotiveQuery language.

Apply

Apply -> ?
Application of a function to its arguments. (internal)

Example
f(1,"x")
Apply function 'f' to arguments '1' and 'x'.

Assign (=)

Assign -> ?
This symbol is used for assigning optional parameters of functions. (internal)

Example
NotAminoAcids(NoWaters = 1)
All residues that are not amino acids or waters.

Lambda

Lambda -> 'a->'b
An anonymous (nameless) function.

Example
lambda m: Residues("HIS").Count(m)
A function that counts number of HIS residues in Motive m.

List

List(elements: ?+) -> List
A list of elements.

Arguments
elements: ?+ - Elements.
Example
[1, "a", True, [3, 4]]
Create a list with 4 elements.

Repeat (*)

Repeat(x: ?, n: Integer) -> ?
Creates a Seqeuence of x's repeated n times. This symbol is not directly supported and can be accesed thru the function Many or List concatenation of Python. (internal)

Arguments
x: ? - Expression to be repeated.
n: Integer - Count.
Example
Rings(5 * ["C"] + ["O"])
Equivalent to Rings("C","C","C","C","C","O").

Sequence

Sequence(xs: ?*) -> ?
Sequence of elements that is automatically flattened to the argument list of the parent function. (internal)

Arguments
xs: ?* - Values.
Example
1,2,3
Sequence of numbers 1, 2, and 3.

Tuple

Tuple -> ?
A tuple of elements. Tuples serve as arguments for functions. Internal use only. (internal)

Example
(1,"a",True)
Create a tuple with 3 elements.


Value Functions

Functions such as addition or comparison of numbers.

Abs

Abs(x: Number) -> Number
Computes the 'Abs' function of the argument.

Arguments
x: Number - Argument.
Example
Abs(x)
Evaluates the expression.

Divide (/)

Divide(x: Number, y: Number) -> Number
Computes the 'Divide' function of the values.

Arguments
x: Number - Left argument.
y: Number - Right argument.
Example
x / y
Evaluates the expression.

Equal (==)

Equal(x: Value, y: Value) -> Bool
Determines the 'Equal' relation between two values.

Arguments
x: Value - Left argument.
y: Value - Right argument.
Example
x == y
Evaluates to True or False based on the value of x and y.

Greater (>)

Greater(x: Number, y: Number) -> Bool
Determines the 'Greater' relation between two values.

Arguments
x: Number - Left argument.
y: Number - Right argument.
Example
x > y
Evaluates to True or False based on the value of x and y.

GreaterEqual (>=)

GreaterEqual(x: Number, y: Number) -> Bool
Determines the 'GreaterEqual' relation between two values.

Arguments
x: Number - Left argument.
y: Number - Right argument.
Example
x >= y
Evaluates to True or False based on the value of x and y.

Less (<)

Less(x: Number, y: Number) -> Bool
Determines the 'Less' relation between two values.

Arguments
x: Number - Left argument.
y: Number - Right argument.
Example
x < y
Evaluates to True or False based on the value of x and y.

LessEqual (<=)

LessEqual(x: Number, y: Number) -> Bool
Determines the 'LessEqual' relation between two values.

Arguments
x: Number - Left argument.
y: Number - Right argument.
Example
x <= y
Evaluates to True or False based on the value of x and y.

LogicalAnd (&)

LogicalAnd(xs: Bool+) -> Bool
Computes 'LogicalAnd' of the input values.

Arguments
xs: Bool+ - Arguments.
Example
x & y
Evaluates to True or False based on the values of x and y.

LogicalNot (!)

LogicalNot(x: Bool) -> Bool
Computes 'LogicalNot' of the input value.

Arguments
x: Bool - Argument.
Example
!x
Evaluates to True or False based on the value of x.

LogicalOr (|)

LogicalOr(xs: Bool+) -> Bool
Computes 'LogicalOr' of the input values.

Arguments
xs: Bool+ - Arguments.
Example
x | y
Evaluates to True or False based on the values of x and y.

LogicalXor

LogicalXor(xs: Bool+) -> Bool
Computes 'LogicalXor' of the input values.

Arguments
xs: Bool+ - Arguments.
Example
LogicalXor(x, y)
Evaluates to True or False based on the values of x and y.

Minus (-)

Minus(x: Number) -> Number
Computes the arithmetic negation of the argument.

Arguments
x: Number - Argument.
Example
-x
Arithmetic negation of x.

NotEqual (!=)

NotEqual(x: Value, y: Value) -> Bool
Determines the 'NotEqual' relation between two values.

Arguments
x: Value - Left argument.
y: Value - Right argument.
Example
x != y
Evaluates to True or False based on the value of x and y.

Plus (+)

Plus(x: Number, y: Number) -> Number
Computes the 'Plus' function of the values.

Arguments
x: Number - Left argument.
y: Number - Right argument.
Example
x + y
Evaluates the expression.

Power (^)

Power(x: Number, y: Number) -> Number
Computes the 'Power' function of the values.

Arguments
x: Number - Left argument.
y: Number - Right argument.
Example
x ^ y
Evaluates the expression.

Subtract (-)

Subtract(x: Number, y: Number) -> Number
Computes the 'Subtract' function of the values.

Arguments
x: Number - Left argument.
y: Number - Right argument.
Example
x - y
Evaluates the expression.

Times (*)

Times(x: Number, y: Number) -> Number
Computes the 'Times' function of the values.

Arguments
x: Number - Left argument.
y: Number - Right argument.
Example
x * y
Evaluates the expression.


Basic Query Functions

Basic building blocks of the language - i.e. atoms, residues, and the like.

AminoAcids

AminoAcids -> Residues
Sequence of all amino acids in a given protein.

Example
AminoAcids()
Returns all amino acids.

AtomIdRange

AtomIdRange(minId: Integer, maxId: ?Integer) -> Atoms
Sequence of atoms with minId <= atomId <= maxId.

Arguments
minId: Integer - Minimum id.
maxId: ?Integer - Maximum id. If not specified, maxId = minId.
Example
AtomIdRange(152, 161)
Returns all atoms with id between 152 and 161 inclusive.

AtomNames

AtomNames(names: String+) -> Atoms
Sequence of atoms with specified names.

Arguments
names: String+ - Allowed names.
Example
AtomNames("O1","NH1")
Returns all atoms with names O1 or NH1.

Atoms

Atoms(symbols: String*) -> Atoms
Sequence of atoms with specified element symbols. If no symbols are specified, yields all atoms one by one. A single atom can be entered using the '@' operator.

Arguments
symbols: String* - Allowed element symbols.
Example
Atoms("Zn","Ca")
Returns all atoms with element symbol Zn or Ca

Named

Named(motives: Motives) -> Motives
'Names' the motive by its lowest atom id.

Arguments
motives: Motives - Motives to name.
Example
Atoms("Zn").Named().AmbientAtoms(7)
When exported, the result files will have names in the format '[parent id]_[pseudorandom numner]_[zn atomid]'. If the Named function was not used, the name would be just '[parent id]_[pseudorandom numner]'.

NotAminoAcids

NotAminoAcids -> Residues
Sequence of all residues resudies that are not amino acids.

Options
NoWaters: Bool = True - Ignore water residues such as HOH.
Example
NotAminoAcids()
Returns all residues that are not amino acids.

NotAtomNames

NotAtomNames(names: String+) -> Atoms
Sequence of atoms that do not have a specified name.

Arguments
names: String+ - Forbidden names.
Example
NotAtomNames("O4")
Returns all atoms that are not called O4.

NotAtoms

NotAtoms(symbols: String+) -> Atoms
Sequence of atoms that are not particular elements.

Arguments
symbols: String+ - Forbidden element symbols.
Example
NotAtoms("O")
Returns all atoms that are not C.

NotResidues

NotResidues(names: Value+) -> Residues
Sequence of residues that are not called by the specified names.

Arguments
names: Value+ - Forbidden residue names.
Example
NotResidues("THR","CYS")
Returns all residues that are not THR or CYS.

RegularMotives

RegularMotives(regex: String) -> Motives
Regular motives. The protein is split into individual chains before the motives are identified.

Arguments
regex: String - Regular expression on one letter abbreviations of amino acids.
Example
RegularMotives("RGD")
Finds all RGD motives.

ResidueIdRange

ResidueIdRange(chain: String, min: Integer, max: ?Integer) -> Residues
Sequence of residues with specific chain and min <= sequence number <= max.

Arguments
chain: String - Chain idetifier. Case sensitive (a != A).
min: Integer - Minimum sequence number.
max: ?Integer - Maximum sequence number. If not specified, max = min.
Example
ResidueIdRange("A", 161, 165)
Returns all residues on chain A with seq. number between 161 and 165 inclusive.

Residues

Residues(names: Value*) -> Residues
Sequence of residues with specified names. If no names are specified, yields all residues one by one. A single residue can be entered using the '#' operator.

Arguments
names: Value* - Allowed residue names.
Example
Residues("HIS", "CYS")
Returns all HIS or CYS residues.

RingAtoms

RingAtoms(atom: Atoms, ring: ?Rings) -> Atoms
Returns all rings atoms.

Arguments
atom: Atoms - Atom types.
ring: ?Rings - Specific ring.
Example
OnRing(Atoms("C"), Rings(4 * ["C"] + ["O"]))
Returns all C atoms on a ring with 4C and O.

Rings

Rings(atoms: Value*) -> Rings
Sequence of rings with particular atoms. If no atoms are specified, yields all rings (cycles) one by one.

Arguments
atoms: Value* - Ring atoms.
Example
Rings(5 * ["C"] + ["O"])
Returns all rings with 5C and 1O atoms.


Advanced Query Functions

Advanced building blocks of the language - i.e. filters and unions.

Count

Count(where: Motive, what: Motives) -> Integer
Counts all occurences of motive 'what' in motive 'where'.

Arguments
where: Motive - Where to count it.
what: Motives - What motive to count.
Example
m.Count(Residues("HIS"))
Returns the count of HIS residues in the motive m.

Current

Current -> Motive
A variable that is assigned by the application environment.

Example
AtomSimilarity(Current(), Motive("model"))
Returns the atom similarity of the current motive and the model.

Filter

Filter(motives: Motives, filter: Motive->Bool) -> Motives
Filters a sequence of motives with a given predicate.

Arguments
motives: Motives - Motives to filter.
filter: Motive->Bool - Filter predicate.
Example
Residues().Filter(lambda m: m.Count(Atoms("C")) >= 3)
Returns all residues that contain at least 3 C atoms.

Find

Find(source: Motive, motives: Motives) -> Motives
Converts the source motive to a structure and finds motives within it.

Arguments
source: Motive - Where to look.
motives: Motives - Motives to find.
Example
AtomSimilarity(Current().Find(NotAtoms("N")).ToMotive(), Motive("model").Find(NotAtoms("N")).ToMotive())
Computes the atom similarity of the 'current' and 'model' motives, but ignores N atoms.

Inside

Inside(motives: Motives, where: Motives) -> Motives
Finds motives within another motive. Equivalent to where.SelectMany(lambda m: m.Find(motives))

Arguments
motives: Motives - Motives to find.
where: Motives - Where to find them.
Example
Atoms("C").Inside(Residues("HIS"))
Returns all C atoms on HIS residues.

Motive

Motive(structureName: String) -> Motive
Returns a structure represented a motive.

Arguments
structureName: String - Name of a structure.
Example
Motive("1tqn_12")
Returns the structure '1tqn_12' represented as a motive.

Or

Or(motives: Motives+) -> Motives
Merges several motive sequences into one.

Arguments
motives: Motives+ - Motives to merge.
Example
Or(Atoms("Zn").ConnectedResidues(1), Rings())
Finds all zincs and their connected residues or rings.

SelectMany

SelectMany(motives: Motives, selector: Motive->Motives) -> Motives
Projects a sequence of motives to another.

Arguments
motives: Motives - Motives to project.
selector: Motive->Motives - The selector.
Example
Residues("HIS").SelectMany(lambda m: m.Find(Atoms("C")))
Returns all C atoms on HIS residues.

ToAtoms

ToAtoms(motives: Motives) -> Motives
Collects all 'inner' motives and yields all unique atoms one by one.

Arguments
motives: Motives - Motives to split.
Example
Residues("HIS").ToAtoms()
Returns all atoms on HIS residues one by one.

ToMotive

ToMotive(motives: Motives) -> Motive
Collects all 'inner' motives and yields them as a single motive.

Arguments
motives: Motives - Motives to convert.
Example
ToMotive(Residues("HIS"))
Returns a single motive that contains all HIS residues.

ToResidues

ToResidues(motives: Motives) -> Motives
Collects all 'inner' motives and yields all unique residues one by one. The residues contain only the atoms that have been yielded by the inner query.

Arguments
motives: Motives - Motives to split.
Example
ToResidues(Atoms("C"))
Returns all C atoms grouped by residues.

Union

Union(motives: Motives) -> Motives
Collects all 'inner' motives and yields one created from their unique atoms.

Arguments
motives: Motives - Motives to merge.
Example
Rings().Union()
Creates a single motive that contains all rings.


Topology Functions

Functions that manipulate the topology of motives.

ConnectedAtoms

ConnectedAtoms(motive: Motives, n: Integer) -> Motives
Surrounds the inner motive by n layers of atoms.

Arguments
motive: Motives - Basic motive.
n: Integer - Number of atom layers to connect.
Options
YieldNamedDuplicates: Bool = False - Yield duplicate motifs if they have a different name.
Example
Residues("MAN").ConnectedAtoms(2)
Finds all MAN residues and then adds two connected levels of atoms to them.

ConnectedResidues

ConnectedResidues(motive: Motives, n: Integer) -> Motives
Surrounds the inner motive by n layers of residues.

Arguments
motive: Motives - Basic motive.
n: Integer - Number of residue layers to connect.
Options
YieldNamedDuplicates: Bool = False - Yield duplicate motifs if they have a different name.
Example
Atoms("Zn").ConnectedResidues(1))
Finds all Zn atoms and adds all residues that are connected to them.

IsConnectedTo

IsConnectedTo(current: Motive, motive: Motives) -> Bool
Checks if a particular motive is connected to any other specified motive. The motives must have empty intersection for this function to return true.

Arguments
current: Motive - A motive to test.
motive: Motives - Motive sequence to test against.
Example
Atoms().Filter(lambda a: a.IsConnectedTo(Rings()))
Finds all atoms that are connected to a ring they do not belong to.

IsNotConnectedTo

IsNotConnectedTo(current: Motive, motive: Motives) -> Bool
Checks if a particular motive is not connected to any other specified motive. The motives must have empty intersection for this function to return true.

Arguments
current: Motive - A motive to test.
motive: Motives - Motive sequence to test against.
Example
Residues().Filter(lambda r: r.IsNotConnectedTo(Atoms("Ca")))
Finds all residues that are not connected to Ca atoms. The residue itself can still contain Ca atoms.


Geometry Functions

Functions that manipulate the geometry of motives.

AmbientAtoms

AmbientAtoms(motive: Motives, r: Number) -> Motives
Surrounds the inner motive by atoms that within the given radius from the inner motive.

Arguments
motive: Motives - Basic motive.
r: Number - Radius.
Options
ExcludeBase: Bool = False - Exclude the central original motif.
NoWaters: Bool = True - Ignore water residues such as HOH.
YieldNamedDuplicates: Bool = False - Yield duplicate motifs if they have a different name.
Example
Atoms("Fe").AmbientAtoms(4)
Finds Fe atoms and all atoms within 4 (angstroms) from each of them.

AmbientResidues

AmbientResidues(motive: Motives, r: Number) -> Motives
Surrounds the inner motive by residues that have at least one atom within the given radius from the inner motive.

Arguments
motive: Motives - Basic motive.
r: Number - Radius.
Options
ExcludeBase: Bool = False - Exclude the central original motif.
NoWaters: Bool = True - Ignore water residues such as HOH.
YieldNamedDuplicates: Bool = False - Yield duplicate motifs if they have a different name.
Example
Rings(6 * ["C"]).AmbientResidues(4)
Finds rings with 6C atoms and all residues within 4 (angstroms) from each of them.

Cluster

Cluster(r: Number, motives: Motives+) -> Motives
Clusters all motives that are pairwise closer than r (angstroms).

Arguments
r: Number - Maximum distance between two motives in the cluster.
motives: Motives+ - Motives to cluster.
Example
Cluster(4, Atoms("Ca"), Rings(5 * ["C"] + ["O"]))
Finds all instance of one or more rings with 5C and O atoms and one or more Ca atoms that are closer than 4 (angstroms).

Filled

Filled(motive: Motives) -> Motives
Adds all atoms that fall within the circumsphere (with radius multiplied by the factor) of the basic motive.

Arguments
motive: Motives - Basic motive.
Options
NoWaters: Bool = True - Ignore water residues such as HOH.
RadiusFactor: Number = 0.75 - Circumsphere radius factor.
Example
Cluster(4, Residues("HIS")).Filled(RadiusFactor = 0.75)
Finds clusters of HIS residues and all atoms within the circumsphere.

Near

Near(r: Number, motives: Motives+) -> Motives
Clusters all motives that are pairwise closer than r (angstroms) and checks if the "counts" match.

Arguments
r: Number - Maximum distance between two sub-motives in the motive.
motives: Motives+ - Motives to 'cluster'.
Example
Near(4, Many(2, Atoms("Ca")), Rings(5 * ["C"] + ["O"]))
Finds all instance of a single ring with 5C and O atoms and two Ca atoms that are closer than 4 (angstroms).

NearestDistanceTo

NearestDistanceTo(current: Motive, motive: Motives) -> Real
Finds the distance to a particular motive.

Arguments
current: Motive - A motive to test.
motive: Motives - Motive sequence to test against.
Example
Atoms().Filter(lambda m: m.NearestDistanceTo(Residues("ASP")) >= 5)
Finds all atoms that are at least 5 (angstroms) away from any ASP residue.


Miscellaneous Functions

Various useful functions.

AtomProperty

AtomProperty(atomMotive: Motive, name: String) -> ?
If the property exists and the motive consits of a single atom, returns the property. Otherwise, returns Nothing.

Arguments
atomMotive: Motive - Single atom motive.
name: String - Property name.
Example
a.Property("my_charges")
Gets the 'my_charges' property of the atom a.

AtomSimilarity

AtomSimilarity(a: Motive, b: Motive) -> Real
Computes Jaccard/Tanimoto coefficient on atoms (element symbols) of both structures.

Arguments
a: Motive - First motive.
b: Motive - Second motive.
Example
AtomSimilarity(m,Motive("1tqn_12"))
Computes the atom similarity between motives m and 1tqn_12.

Descriptor

Descriptor(motive: Motive, name: String) -> ?
Returns the descriptor. If the descriptor does not exist, 'null' is returned.

Arguments
motive: Motive - Motive that represents entire structure.
name: String - Descriptor name.
Example
Current().Descriptor("similarity")
Returns the 'similarity' descriptor of the current motive.

ResidueSimilarity

ResidueSimilarity(a: Motive, b: Motive) -> Real
Computes Jaccard/Tanimoto coefficient on residue names of both structures.

Arguments
a: Motive - First motive.
b: Motive - Second motive.
Example
ResidueSimilarity(m, Motive("1tqn_12"))
Computes the residue similarity between motives m and 1tqn_12.


Retrieved from "https://webchemwiki.biodata.ceitec.cz/index.php?title=PatternQuery:Language_Reference&oldid=6"