How to's: Difference between revisions

Revision as of 10:43, 18 October 2013

Introduction

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 Motive (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.

Using MotiveQuery in Silverlight applications

MotiveQuery can be used in SiteBinder, EEM Charges, and MotiveExplorer from the the corresponding UI elements. Moreover, it is possible to use MQ from the Scripting window. This is achieved using the MQ.Execute function. The function takes two parameters: the query and an optional target structure list.

Examples

These examples can be executed from the Scripting window of SiteBinder, MotiveExplorer, or other Silverlight applications.

q = Atoms("Zn").ConnectedAtoms(2) 
MQ.Execute(q)

This command finds all motifs specified by the query q in all loaded structures.

MQ.Execute(Residues("HEM"), [ Session.StructureMap["1tqn"], Session.StructureMap["2wer"] ])

This command finds all HEM residues in structures 1tqn and 2wer (provided structures with these names are loaded).

q = AtomSimilarity(Motive("model"), Motive("1gtz_0"))
MQ.Execute(q)

This command computes the atom similarity (Jaccard coefficient) for structures model and 1gtz_0.

q = ResidueSimilarity(Motive("model"), Current())
MQ.Execute(q, Session.Structures)

This command computes the residue similarity (Jaccard coefficient) for the structure with id 'model' (which is loaded using the Motive function) and all other loaded structures (computed one by one using the function Current()). The result is returned in CSV format.

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.

Options

ChargeType: String = "" - Specify type of the charge. Allowed values: Positive, Negative, Aromatic, Polar, NonPolar.

Examples

AminoAcids()

All amino acids.

AminoAcids(ChargeType = "Polar")

Amino acids with polar charge.

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

NotAtoms("O")

Returns all atoms that are not O.

NotResidues

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

Arguments

names: Value+ - Forbidden residue names.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

RingAtoms(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.

Examples

Rings(5 * ["C"] + ["O"])

Returns all rings with 5C and 1O atoms.

Advanced Query Functions

Advanced building blocks of the language.

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.

Examples

Atoms("C").Inside(Residues("HIS"))

Returns all C atoms on HIS residues.

Or

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

Arguments

motives: Motives+ - Motives to merge.

Examples

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.

Examples

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.

Examples

Residues("HIS").ToAtoms()

Returns all atoms on HIS residues one by one.

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.

Examples

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.

Examples

Rings().Union()

Creates a single motive that contains all rings.

Filter Functions

Functions useful for filtering motifs.

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.

Examples

m.Count(Residues("HIS"))

Returns the count of HIS residues in the motive m. Where m is a Motive (for example when using the Filter function or returned by the ToMotive() function). This example will not work directly and is here to illustrate a concept.

Atoms("Zn").ConnectedResidues(1).Filter(lambda m: m.Count(Residues("HIS")) == 2)

Motifs with Zn atoms and its connected residues with exactly 2 HIS residues.

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.

Examples

Residues().Filter(lambda m: m.Count(Atoms("C")) >= 3)

Returns all residues that contain at least 3 C atoms.

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.

Examples

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.

Examples

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.

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.

Examples

Atoms().Filter(lambda m: m.NearestDistanceTo(Residues("ASP")) >= 5)

Finds all atoms that are at least 5 (angstroms) away from any ASP residue.

Topology Functions

Functions that rely on the topology of motifs.

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.

Examples

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.

Examples

Atoms("Zn").ConnectedResidues(1)

Finds all Zn atoms and adds all residues that are connected to them.

Geometry Functions

Functions that rely on the geometry of motifs.

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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'.

Examples

Near(4, Many(Atoms("Ca"), 2), 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).

Miscellaneous Functions

Various useful functions. These function often require a special setup (i.e. only useful in Scripting window or in specific applications).

AtomProperty

AtomProperty(atomMotive: Motive, name: String) -> ?
If the property exists and the motive consits of a single atom, returns the property. Otherwise, returns Nothing.
Note: This function cannot be used directly to query motifs from MotiveExplorer or MotiveQuery service.

Arguments

atomMotive: Motive - Single atom motive.

name: String - Property name.

Examples

a.Property("charge")

Gets the 'charge' property of the atom a. Where a is a single atom Motive. This example will not work directly.

Atoms().Filter(lambda a: a.Property("charge") >= 2)

All atoms with the charge property greater or equal to 2. This example will only work in cases where a suitable property is defined. For example in Scripting window in the Charges app.

AtomSimilarity

AtomSimilarity(a: Motive, b: Motive) -> Real
Computes Jaccard/Tanimoto coefficient on atoms (element symbols) of both structures.
Note: This function cannot be used directly to query motifs from MotiveExplorer or MotiveQuery service.

Arguments

a: Motive - First motive.

b: Motive - Second motive.

Examples

AtomSimilarity(Current(),Motive("1tqn_12"))

Computes the atom similarity between the current motif and 1tqn_12. This example can be used in SiteBinder to create a descriptor (assuming a structure with id '1tqn_12' is loaded).

CSA

CSA -> Motives
Entries from Catalytic Site Atlas represented as motifs. Works only if used from the command line version of MotiveQuery and property configured.
Note: This function cannot be used directly to query motifs from MotiveExplorer or MotiveQuery service.

Examples

CSA()

All CSA sites for the given structure. This example will only work if used from the command line version of MotiveQuery and property configured.

Current

Current -> Motive
A variable that is assigned by the application environment.
Note: This function cannot be used directly to query motifs from MotiveExplorer or MotiveQuery service.

Examples

AtomSimilarity(Current(), Motive("model"))

Returns the atom similarity of the current motive and the model. This example will work for example when defining a structure descriptor in SiteBinder and there is a structure with id 'model' loaded.

Descriptor

Descriptor(motive: Motive, name: String) -> ?
Returns the descriptor. If the descriptor does not exist, 'null' is returned.
Note: This function cannot be used directly to query motifs from MotiveExplorer or MotiveQuery service.

Arguments

motive: Motive - Motive that represents entire structure.

name: String - Descriptor name.

Examples

Current().Descriptor("similarity") >= 0.75

Returns True if 'similarity' descriptor of the current motif is at least 0.75. This example will work for example in SiteBinder's structure selection if the 'similarity' descriptor has been previously defined.

Find

Find(source: Motive, motives: Motives) -> Motives
Converts the source motive to a structure and finds motives within it.
Note: This function cannot be used directly to query motifs from MotiveExplorer or MotiveQuery service.

Arguments

source: Motive - Where to look.

motives: Motives - Motives to find.

Examples

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. This example can be used in SiteBinder to create a descriptor (assuming a structure with id 'model' is loaded).

Motive

Motive(structureName: String) -> Motive
Returns a structure represented a motive.
Note: This function cannot be used directly to query motifs from MotiveExplorer or MotiveQuery service.

Arguments

structureName: String - Name of a structure.

Examples

Motive("1tqn_12")

Returns the structure '1tqn_12' represented as a motive. Usable in defining descriptors or in Scripting window (using MQ.Execute).

ResidueSimilarity

ResidueSimilarity(a: Motive, b: Motive) -> Real
Computes Jaccard/Tanimoto coefficient on residue names of both structures.
Note: This function cannot be used directly to query motifs from MotiveExplorer or MotiveQuery service.

Arguments

a: Motive - First motive.

b: Motive - Second motive.

Examples

ResidueSimilarity(Current(), Motive("1tqn_12"))

Computes the residue similarity between the current motif and 1tqn_12. This example can be used in SiteBinder to create a descriptor (assuming a structure with id '1tqn_12' is loaded).

ToMotive

ToMotive(motives: Motives) -> Motive
Converts a sequence of Motives to a single motive. The Motive type is required by some function such as AtomSimilarity.
Note: This function cannot be used directly to query motifs from MotiveExplorer or MotiveQuery service.

Arguments

motives: Motives - Motives to convert.

Examples

Residues("HIS").ToMotive()

Converts a sequence of HIS residue Motives to a single Motive.

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.

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

Not(x)

Evaluates to True or False based on the value of x.

x.Not()

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.

Examples

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.

Examples

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.

Examples

-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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

x * y

Evaluates the expression.