WebChemistry Wiki - User contributions [en]

LiteMol:Embedding

2016-08-09T11:50:00Z

Dave: Created page with "To find out how to embed LiteMol, please check the example included with with source code distribution. LiteMol has a very flexible plugin architecture and allows you to cust..."

To find out how to embed LiteMol, please check the example included with with source code distribution.

LiteMol has a very flexible plugin architecture and allows you to customise which components you want to include. The examples also show how to write your own components and control schemes.

PatternQuery:UserManual

2015-04-26T22:23:19Z

Dave:

__NOTOC__

'''PatternQuery''' ('''PQ''') is interactive, user-friendly and platform independent web service enabling users to effectively define, extract and analyze biomolecular structural patterns using the '''PatternQuery language'''. Such analysis is particularly useful not only in a structural and functional assignment of uncharacterized or newly determined proteins, but also represents a key point in rational design and engineering of novel functional sites and comparative protein structural analyses.

'''PQ''' is provided as a web service for mining the whole [http://pdb.org/pdb/home/home.do PDB database], however it can also be restricted based on numerous metadata, such as the ''Release date'', ''Resolution'', ''EC number'' and so on. Therefore, only structures relevant for your research are processed. Additionally, smaller datasets can be processed by the [[PatternQuery:Explorer | PatternQuery Explorer]] application. Larger in-house databases can be processed with the [[PatternQuery:Command Line | command line application]].

Below you can find the '''PQ''' user manual, which contains all the information you need in order to make efficient use of '''PQ'''. Additional support is provided on the [http://webchem.ncbr.muni.cz/Platform/PatternQuery/Index '''PQ''' web pages]. When you first access the '''PQ''' page, you will find basic information in the Quick Help tab, and useful examples in the Samples tab. Follow the green ? buttons to access the embedded interactive guides that assist you in setting up your calculations and interpreting the results. Many tool tips are available when hovering over various elements of the interface.
----
===[[PatternQuery:Introduction | Introduction]]===
----
===[[PatternQuery:Terminology | Terminology]]===
#[[PatternQuery:Terminology#Atom | Atom]]
#[[PatternQuery:Terminology#Residue | Residue]]
#[[PatternQuery:Terminology#Fragment | Fragment]]
#[[PatternQuery:Terminology#Query | Query]]

----
===[[PatternQuery:Principles | Principles of the PQ language]]===
#[[PatternQuery:Principles#Example, Part One | Example - introduction]]
#[[PatternQuery:Principles#Basic Principles of the Language | Basic Principle]]
#[[PatternQuery:Principles#Example, Part One | Example - revised]]
----
===[[PatternQuery:How to build a query | How to build a query]]===
#[[PatternQuery:How to build a query#How to think about queries | How to think about query]]
#[[PatternQuery:How to build a query#Ready-to-use examples | Ready-to-use examples]]
----
===[[PatternQuery:Use Cases | Biological use cases]]===
#[[PatternQuery:Use Cases#Find all post-translational modified amino acids | Post-translational modified aminoacids]]
#[[PatternQuery:Use Cases#Identify Zinc fingers | Zinc fingers]]
#[[PatternQuery:Use Cases#Identify all the residues, which contain a sugar ring | Residue containing carbohydrate moiety]]
----
===[[PatternQuery:Explorer | PatternQuery Explorer]]===
# [[PatternQuery:Explorer#Launch PatternQuery Explorer app | Launch application]]
# [[PatternQuery:Explorer#Get started with PatternQuery Explorer | How to work with it]]
# [[PatternQuery:Explorer#Executing Query & interpreting results | Execute query]]
----

===[[PatternQuery:Service Organization | Using PatternQuery Service]]===
# [[PatternQuery:Service Organization#Synopsis Page | Synopsis Page]]
# [[PatternQuery:Service Organization#Job Submission | Job submission]]
# [[PatternQuery:Service Organization#Specifics Page | Result analysis]]
# [[PatternQuery:Specifics Page| Specifics Page]]
## [[PatternQuery:Specifics Page#Calculation Summary| Calculation Summary]]
## [[PatternQuery:Specifics Page#Fragment Details | Fragment Details]]
## [[PatternQuery:Specifics Page#Structure Details | Structure Details ]]
----

===[[PatternQuery:Language_Reference | Language reference]]===
----
===[[PatternQuery:Command Line | Command line version & Technical details]]===
----

PatternQuery:Language Reference

2015-04-23T20:48:18Z

Dave:

== Introduction ==

PatternQuery (PQ) is a user friendly chemical language primarily designed for defining atom patterns in molecules. PQ combines the clarity and brevity of programming languages with the versatility of natural language, aiming for an efficient inclusion of chemical and biochemical knowledge into the definition of patterns. PQ allows definitions based on chemical connectivity and three-dimensional structure at the same time. Additionally, in the case of molecules based on residue chains (such as proteins, nucleic acids, saccharides, etc.), PQ allows the user to include any amount of information regarding the residue level structure directly into the definition of the patternss.

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

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

Some of the functions return '''<code>PatternSeq</code>''' while other return '''<code>Pattern</code>'''.
* '''<code>Pattern</code>''' is a set of atoms.
* '''<code>PatternSeq</code>''' is a sequence of '''<code>Pattern</code>''' (the sets of atoms).

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

== Basic Query Functions ==
''Basic building blocks of the language - i.e. atoms, residues, and the like.''
=== AminoAcids ===
<code>AminoAcids() -> Residues</code> 
''Sequence of all residues with the 20 basic amino acid names.'' 
;Options
: ChargeType: String = "" - ''Specify type of the charge. Allowed values: Positive, Negative, Aromatic, Polar, NonPolar.''
;Examples
: <code>AminoAcids()</code>
:: ''All amino acids.''
: <code>AminoAcids(ChargeType = "Polar")</code>
:: ''Amino acids with polar charge.''
----
=== AtomIdRange ===
<code>AtomIdRange(minId: Integer, maxId: ?Integer) -> Atoms</code> 
''Sequence of atoms with minId <= atomId <= maxId.'' 
;Arguments
: minId: Integer - ''Minimum id.''
: maxId: ?Integer - ''Maximum id. If not specified, maxId = minId.''
;Examples
: <code>AtomIdRange(152, 161)</code>
:: ''Returns all atoms with id between 152 and 161 inclusive.''
----
=== AtomIds ===
<code>AtomIds(ids: Integer+) -> Atoms</code> 
''Sequence of atoms with specified identifiers.'' 
;Arguments
: ids: Integer+ - ''Identifiers.''
;Examples
: <code>AtomIds(1, 2, 3)</code>
:: ''Returns atoms with ids 1, 2, 3.''
----
=== AtomNames ===
<code>AtomNames(names: String+) -> Atoms</code> 
''Sequence of atoms with specified names.'' 
;Arguments
: names: String+ - ''Allowed names.''
;Examples
: <code>AtomNames("O1","NH1")</code>
:: ''Returns all atoms with names O1 or NH1.''
----
=== Atoms ===
<code>Atoms(symbols: String*) -> Atoms</code> 
''Sequence of atoms with specified element symbols. If no symbols are specified, yields all atoms one by one.'' 
;Arguments
: symbols: String* - ''Allowed element symbols.''
;Examples
: <code>Atoms("Zn","Ca")</code>
:: ''Returns all atoms with element symbol Zn or Ca''
----
=== Chains ===
<code>Chains(identifiers: Value*) -> PatternSeq</code> 
''Splits the structures into chains. If no identifiers are specified, all chains are returned.'' 
;Arguments
: identifiers: Value* - ''Chain identifiers.''
;Examples
: <code>Chains()</code>
:: ''Returns all chains.''
: <code>Chains("")</code>
:: ''Returns chains without specific identifier.''
: <code>Chains("A", "B")</code>
:: ''Returns chains A and B.''
----
=== Helices ===
<code>Helices() -> PatternSeq</code> 
''Returns all helices. This assumes the information about helices was present in the input structure.'' 
;Examples
: <code>Helices()</code>
:: ''Returns all helices.''
----
=== HetResidues ===
<code>HetResidues() -> Residues</code> 
''Sequence of all residues that contain HET atoms.'' 
;Options
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
;Examples
: <code>HetResidues()</code>
:: ''Returns all residues that contain HET atoms (ignores water).''
: <code>HetResidues(NoWaters=False)</code>
:: ''Returns all residues that contain HET atoms (includes water).''
----
=== ModifiedResidues ===
<code>ModifiedResidues(parentNames: String*) -> Residues</code> 
''Sequence of modified residues that originate from the specified name. If no names are specified, yields all modified residues one by one.'' 
;Arguments
: parentNames: String* - ''Parent residue names.''
;Examples
: <code>ModifiedResidues("MET")</code>
:: ''Returns all residues modified from MET (for example MSE).''
----
=== Named ===
<code>Named(patterns: PatternSeq) -> PatternSeq</code> 
'''Names' the pattern by its lowest atom id.'' 
;Arguments
: patterns: PatternSeq - ''Patterns to name.''
;Examples
: <code>Atoms("Zn").Named().AmbientAtoms(7)</code>
:: ''When exported, the result files will have names in the format '[parent id]_[pseudorandom number]_[zn atomid]'. If the Named function was not used, the name would be just '[parent id]_[pseudorandom number]'.''
----
=== NotAminoAcids ===
<code>NotAminoAcids() -> Residues</code> 
''Sequence of all residues that are not any of the 20 basic amino acids.'' 
;Options
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
;Examples
: <code>NotAminoAcids()</code>
:: ''Returns all residues that are not amino acids.''
----
=== NotAtomIds ===
<code>NotAtomIds(ids: Integer+) -> Atoms</code> 
''Sequence of atoms that do not have specified identifiers.'' 
;Arguments
: ids: Integer+ - ''Identifiers.''
;Examples
: <code>NotAtomIds(1, 2, 3)</code>
:: ''Returns atoms that do not have id 1, 2, nor 3.''
----
=== NotAtomNames ===
<code>NotAtomNames(names: String+) -> Atoms</code> 
''Sequence of atoms that do not have a specified name.'' 
;Arguments
: names: String+ - ''Forbidden names.''
;Examples
: <code>NotAtomNames("O4")</code>
:: ''Returns all atoms that are not called O4.''
----
=== NotAtoms ===
<code>NotAtoms(symbols: String+) -> Atoms</code> 
''Sequence of atoms that are not particular elements.'' 
;Arguments
: symbols: String+ - ''Forbidden element symbols.''
;Examples
: <code>NotAtoms("O")</code>
:: ''Returns all atoms that are not O.''
----
=== NotResidues ===
<code>NotResidues(names: Value+) -> Residues</code> 
''Sequence of residues that are not called by the specified names.'' 
;Arguments
: names: Value+ - ''Forbidden residue names.''
;Examples
: <code>NotResidues("THR","CYS")</code>
:: ''Returns all residues that are not THR or CYS.''
----
=== RegularMotifs ===
<code>RegularMotifs(regex: Value) -> PatternSeq</code> 
''Identifies regular motifs. The protein is split into individual chains and the residues are sorted by their Sequence Number before the motifs are identified. The query does not check if adjacent residues have consecutive Sequence Numbers. The query works in two modes: Amino and Nucleotide, on amino acids and nucleotides respectively. In the Amino mode, all the derivatives of standard residues are treated as the standard residues, as long as this information is properly annotated in MODRES or _pdbx_struct_mod_residue field. The default mode is 'Amino''' 
;Arguments
: regex: Value - ''Regular expression on one letter abbreviations of amino acids.''
;Options
: Type: String = "Amino" - ''Determines the type of the query. Allowed values: Amino, Nucleotide.''
;Examples
: <code>RegularMotifs("RGD")</code>
:: ''Finds all RGD motifs.''
: <code>RegularMotifs("ACGTU", Type = 'Nucleotide')</code>
:: ''Finds all consecutive occurrences of the ACGTU nucleotides.''
: <code>RegularMotifs(".HC.").Filter(lambda m: m.IsConnected())</code>
:: ''Finds all 4 residue motifs with ?-HIS-CYS-? that are connected.''
----
=== ResidueIdRange ===
<code>ResidueIdRange(chain: String, min: Integer, max: ?Integer) -> Residues</code> 
''Sequence of residues with specific chain and min <= sequence number <= max.'' 
;Arguments
: chain: String - ''Chain identifier. Case sensitive (a != A).''
: min: Integer - ''Minimum sequence number.''
: max: ?Integer - ''Maximum sequence number. If not specified, max = min.''
;Examples
: <code>ResidueIdRange("A", 161, 165)</code>
:: ''Returns all residues on chain A with seq. number between 161 and 165 inclusive.''
----
=== ResidueIds ===
<code>ResidueIds(ids: String+) -> Residues</code> 
''Sequence of residues with specific identifiers. If the structure does not contain a residue with the given identifier, it is skipped.'' 
;Arguments
: ids: String+ - ''One or more identifiers in the format 'NUMBER [CHAIN] [i:INSERTIONCODE]' (parameters in [] are optional, for example '175 i:12' or '143 B'). Case sensitive (a != A).''
;Examples
: <code>ResidueIds("132 A", "178 A")</code>
:: ''Returns residues A 123 and A 178 (provided the input structure contains them).''
----
=== Residues ===
<code>Residues(names: String*) -> Residues</code> 
''Sequence of residues with specified names. If no names are specified, yields all residues one by one.'' 
;Arguments
: names: String* - ''Allowed residue names.''
;Examples
: <code>Residues("HIS", "CYS")</code>
:: ''Returns all HIS or CYS residues.''
----
=== RingAtoms ===
<code>RingAtoms(atom: Atoms, ring: ?Rings) -> Atoms</code> 
''Returns all rings atoms.'' 
;Arguments
: atom: Atoms - ''Atom types.''
: ring: ?Rings - ''Specific ring.''
;Examples
: <code>RingAtoms(Atoms("C"), Rings(4 * ["C"] + ["O"]))</code>
:: ''Returns all C atoms on a ring with 4C and O.''
----
=== Rings ===
<code>Rings(atoms: Value*) -> Rings</code> 
''Sequence of rings with particular atoms. If no atoms are specified, yields all rings (cycles) one by one. The order of atoms matters.'' 
;Arguments
: atoms: Value* - ''Ring atoms.''
;Examples
: <code>Rings()</code>
:: ''Returns all rings.''
: <code>Rings(5 * ["C"] + ["O"])</code>
:: ''Returns all rings with 5C and 1O atoms.''
: <code>Rings(["C", "C", "N", "C", "N"])</code>
:: ''Returns all rings with C-C-N-C-N atoms.''
: <code>Or(Rings(["C", "C", "N", "C", "N"]), Rings(["C", "C", "C", "N", "N"]))</code>
:: ''Returns all rings with C-C-N-C-N or C-C-C-N-N atoms.''
----
=== Sheets ===
<code>Sheets() -> PatternSeq</code> 
''Returns all sheets. This assumes the information about sheets was present in the input structure.'' 
;Examples
: <code>Sheets()</code>
:: ''Returns all sheets.''
 
== Advanced Query Functions ==
''Advanced building blocks of the language.''
=== Flatten ===
<code>Flatten(patterns: PatternSeq, selector: Pattern->PatternSeq) -> PatternSeq</code> 
''Converts a sequence of sequence of patterns into a single 'flat' sequence.'' 
;Arguments
: patterns: PatternSeq - ''Patterns to project.''
: selector: Pattern->PatternSeq - ''The selector.''
;Examples
: <code>Residues("HIS").Flatten(lambda m: m.Find(Atoms("C")))</code>
:: ''Returns all C atoms on HIS residues.''
----
=== Inside ===
<code>Inside(patterns: PatternSeq, where: PatternSeq) -> PatternSeq</code> 
''Finds patterns within another pattern. Equivalent to where.Flatten(lambda m: m.Find(patterns))'' 
;Arguments
: patterns: PatternSeq - ''Patterns to find.''
: where: PatternSeq - ''Where to find them.''
;Examples
: <code>Atoms("C").Inside(Residues("HIS"))</code>
:: ''Returns all C atoms on HIS residues.''
----
=== Or ===
<code>Or(patterns: PatternSeq+) -> PatternSeq</code> 
''Merges several pattern sequences into one.'' 
;Arguments
: patterns: PatternSeq+ - ''Patterns to merge.''
;Examples
: <code>Or(Atoms("Zn").ConnectedResidues(1), Rings())</code>
:: ''Finds all zincs and their connected residues or rings.''
----
=== ToAtoms ===
<code>ToAtoms(patterns: PatternSeq) -> PatternSeq</code> 
''Collects all 'inner' patterns and yields all unique atoms one by one.'' 
;Arguments
: patterns: PatternSeq - ''Patterns to split.''
;Examples
: <code>Residues("HIS").ToAtoms()</code>
:: ''Returns all atoms on HIS residues one by one.''
----
=== ToResidues ===
<code>ToResidues(patterns: PatternSeq) -> PatternSeq</code> 
''Collects all 'inner' patterns and yields all unique residues one by one. The residues contain only the atoms that have been yielded by the inner query.'' 
;Arguments
: patterns: PatternSeq - ''Patterns to split.''
;Examples
: <code>Atoms("C").ToResidues()</code>
:: ''Returns all C atoms grouped by residues.''
----
=== Union ===
<code>Union(patterns: PatternSeq) -> PatternSeq</code> 
''Collects all 'inner' patterns and yields one created from their unique atoms.'' 
;Arguments
: patterns: PatternSeq - ''Patterns to merge.''
;Examples
: <code>Rings().Union()</code>
:: ''Creates a single pattern that contains all rings.''
 
== Filter Functions ==
''Functions useful for filtering patterns.''
=== Contains ===
<code>Contains(where: Pattern, what: PatternSeq) -> Bool</code> 
''Checks if a pattern is contained within another one. Equivalent to where.Count(what) > 0.'' 
;Arguments
: where: Pattern - ''Where to look.''
: what: PatternSeq - ''What to find.''
;Examples
: <code>HetResidues().Filter(lambda m: m.Contains(Rings(5*['C']+['O'])).Not())</code>
:: ''Returns all HET residues that do not contain a 5CO ring.''
----
=== Count ===
<code>Count(where: Pattern, what: PatternSeq) -> Integer</code> 
''Counts all occurrences of pattern 'what' in pattern 'where'.'' 
;Arguments
: where: Pattern - ''Where to count it.''
: what: PatternSeq - ''What pattern to count.''
;Examples
: <code>m.Count(Residues("HIS"))</code>
:: ''Returns the count of HIS residues in the pattern m. Where m is a Pattern (for example when using the Filter function or returned by the ToPattern() function). This example will not work directly and is here to illustrate a concept.''
: <code>Atoms("Zn").ConnectedResidues(1).Filter(lambda m: m.Count(Residues("HIS")) == 2)</code>
:: ''Patterns with Zn atoms and its connected residues with exactly 2 HIS residues.''
----
=== ExecuteIf ===
<code>ExecuteIf(query: PatternSeq, condition: Pattern->Bool) -> PatternSeq</code> 
''Executes a query only if the condition is met. Otherwise, return an empty sequence of patterns.'' 
;Arguments
: query: PatternSeq - ''Query to execute.''
: condition: Pattern->Bool - ''Condition that must be satisfied for the parent structure/pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.Resolution() <= 2.4)</code>
:: ''Returns residues in structures that have resolution lower than 2.4ang.''
: <code>AminoAcids().ExecuteIf(lambda p: p.Count(Atoms('Fe')) > 3)</code>
:: ''Returns all amino acids in structures that have at least 3 Fe atoms.''
----
=== Filter ===
<code>Filter(patterns: PatternSeq, filter: Pattern->Bool) -> PatternSeq</code> 
''Filters a sequence of patterns with a given predicate.'' 
;Arguments
: patterns: PatternSeq - ''Patterns to filter.''
: filter: Pattern->Bool - ''Filter predicate.''
;Examples
: <code>Residues().Filter(lambda m: m.Count(Atoms("C")) >= 3)</code>
:: ''Returns all residues that contain at least 3 C atoms.''
----
=== IsConnected ===
<code>IsConnected(pattern: Pattern) -> Bool</code> 
''Checks if a particular pattern is a connected graph.'' 
;Arguments
: pattern: Pattern - ''A pattern to test.''
;Examples
: <code>Atoms("Zn").AmbientResidues(3).Filter(lambda m: m.IsConnected())</code>
:: ''Finds all patterns with a Zn and residues within 3 ang, where all the ambient residues are connected to the central atom.''
----
=== IsConnectedTo ===
<code>IsConnectedTo(where: Pattern, patterns: PatternSeq) -> Bool</code> 
''Checks if a particular pattern is connected to any other specified pattern. The patterns must have empty intersection for this function to return true.'' 
;Arguments
: where: Pattern - ''A pattern to test.''
: patterns: PatternSeq - ''Pattern sequence to test against.''
;Examples
: <code>Atoms().Filter(lambda a: a.IsConnectedTo(Rings()))</code>
:: ''Finds all atoms that are connected to a ring they do not belong to.''
----
=== IsNotConnectedTo ===
<code>IsNotConnectedTo(what: Pattern, patterns: PatternSeq) -> Bool</code> 
''Checks if a particular pattern is not connected to any other specified pattern. The patterns must have empty intersection for this function to return true.'' 
;Arguments
: what: Pattern - ''A pattern to test.''
: patterns: PatternSeq - ''Pattern sequence to test against.''
;Examples
: <code>Residues().Filter(lambda r: r.IsNotConnectedTo(Atoms("Ca")))</code>
:: ''Finds all residues that are not connected to Ca atoms. The residue itself can still contain Ca atoms.''
----
=== NearestDistanceTo ===
<code>NearestDistanceTo(where: Pattern, patterns: PatternSeq) -> Real</code> 
''Finds the distance to a particular pattern.'' 
;Arguments
: where: Pattern - ''A pattern to test.''
: patterns: PatternSeq - ''Pattern sequence to test against.''
;Examples
: <code>Atoms().Filter(lambda m: m.NearestDistanceTo(Residues("ASP")) >= 5)</code>
:: ''Finds all atoms that are at least 5 (angstroms) away from any ASP residue.''
----
=== SeqCount ===
<code>SeqCount(what: PatternSeq) -> Integer</code> 
''Counts the length of a sequence of motifs.'' 
;Arguments
: what: PatternSeq - ''What pattern sequence to count.''
;Examples
: <code>Atoms("Zn").AmbientResidues(3).Filter(lambda m: m.Find(Residues("HIS")).SeqCount() > 1)</code>
:: ''Returns a sequence of patterns with Zn atom and residues within 3ang if the pattern contains at least 2 HIS residues.''
 
== Topology Functions ==
''Functions that rely on the topology of patterns.''
=== ConnectedAtoms ===
<code>ConnectedAtoms(pattern: PatternSeq, n: Integer) -> PatternSeq</code> 
''Surrounds the inner pattern by n layers of atoms.'' 
;Arguments
: pattern: PatternSeq - ''Basic pattern.''
: n: Integer - ''Number of atom layers to connect.''
;Options
: YieldNamedDuplicates: Bool = False - ''Yield duplicate patterns if they have a different name.''
;Examples
: <code>Residues("MAN").ConnectedAtoms(2)</code>
:: ''Finds all MAN residues and then adds two connected levels of atoms to them.''
----
=== ConnectedResidues ===
<code>ConnectedResidues(pattern: PatternSeq, n: Integer) -> PatternSeq</code> 
''Surrounds the inner pattern by n layers of residues.'' 
;Arguments
: pattern: PatternSeq - ''Basic pattern.''
: n: Integer - ''Number of residue layers to connect.''
;Options
: YieldNamedDuplicates: Bool = False - ''Yield duplicate patterns if they have a different name.''
;Examples
: <code>Atoms("Zn").ConnectedResidues(1)</code>
:: ''Finds all Zn atoms and adds all residues that are connected to them.''
----
=== Path ===
<code>Path(patterns: PatternSeq+) -> PatternSeq</code> 
''Creates a new pattern from 'connected' parts.'' 
;Arguments
: patterns: PatternSeq+ - ''Patterns to path.''
;Examples
: <code>Path(Atoms("O"), Atoms("C"), Atoms("O"))</code>
:: ''Finds patterns with two O and one C atoms where the C atoms is connected to the O ones.''
----
=== Star ===
<code>Star(center: PatternSeq, patterns: PatternSeq+) -> PatternSeq</code> 
''Creates a new pattern from a central one and connected parts.'' 
;Arguments
: center: PatternSeq - ''Center pattern.''
: patterns: PatternSeq+ - ''Patterns to chain.''
;Examples
: <code>Star(Atoms("C"), Atoms("O"), Atoms("O"))</code>
:: ''Finds patterns with two O atoms and one C atom in the center.''
: <code>Atoms("C").Star(Atoms("O"), Atoms("O"))</code>
:: ''Finds patterns with two O atoms and one C atom in the center.''
 
== Geometry Functions ==
''Functions that rely on the geometry of patterns.''
=== AmbientAtoms ===
<code>AmbientAtoms(pattern: PatternSeq, r: Number) -> PatternSeq</code> 
''Surrounds the inner pattern by atoms that within the given radius from the inner pattern.'' 
;Arguments
: pattern: PatternSeq - ''Basic pattern.''
: r: Number - ''Radius.''
;Options
: ExcludeBase: Bool = False - ''Exclude the central original pattern.''
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
: YieldNamedDuplicates: Bool = False - ''Yield duplicate patterns if they have a different name.''
;Examples
: <code>Atoms("Fe").AmbientAtoms(4)</code>
:: ''Finds Fe atoms and all atoms within 4 (angstroms) from each of them.''
----
=== AmbientResidues ===
<code>AmbientResidues(pattern: PatternSeq, r: Number) -> PatternSeq</code> 
''Surrounds the inner pattern by residues that have at least one atom within the given radius from the inner pattern.'' 
;Arguments
: pattern: PatternSeq - ''Basic pattern.''
: r: Number - ''Radius.''
;Options
: ExcludeBase: Bool = False - ''Exclude the central original pattern.''
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
: YieldNamedDuplicates: Bool = False - ''Yield duplicate patterns if they have a different name.''
;Examples
: <code>Rings(6 * ["C"]).AmbientResidues(4)</code>
:: ''Finds rings with 6C atoms and all residues within 4 (angstroms) from each of them.''
----
=== Cluster ===
<code>Cluster(r: Number, patterns: PatternSeq+) -> PatternSeq</code> 
''Clusters all patterns that are pairwise closer than r (angstroms).'' 
;Arguments
: r: Number - ''Maximum distance between two patterns in the cluster.''
: patterns: PatternSeq+ - ''Patterns to cluster.''
;Examples
: <code>Cluster(4, Atoms("Ca"), Rings(5 * ["C"] + ["O"]))</code>
:: ''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 ===
<code>Filled(pattern: PatternSeq) -> PatternSeq</code> 
''Adds all atoms that fall within the circumsphere (with radius multiplied by the factor) of the basic pattern.'' 
;Arguments
: pattern: PatternSeq - ''Basic pattern.''
;Options
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
: RadiusFactor: Number = 0.75 - ''Circumsphere radius factor.''
;Examples
: <code>Cluster(4, Residues("HIS")).Filled(RadiusFactor = 0.75)</code>
:: ''Finds clusters of HIS residues and all atoms within the circumsphere.''
----
=== Near ===
<code>Near(r: Number, patterns: PatternSeq+) -> PatternSeq</code> 
''Clusters all patterns that are pairwise closer than r (angstroms) and checks if the "counts" match.'' 
;Arguments
: r: Number - ''Maximum distance between two sub-patterns in the pattern.''
: patterns: PatternSeq+ - ''Patterns to 'cluster'.''
;Examples
: <code>Near(4, Atoms("Ca"), Atoms("Ca"), Rings(5 * ["C"] + ["O"]))</code>
:: ''Finds all instance of a single ring with 5C and O atoms and two Ca atoms that are closer than 4 (angstroms).''
 
== Meta-data Functions ==
''Functions dealing with meta-data about structures such as release date or authors.''
=== Authors ===
<code>Authors(pattern: Pattern) -> String</code> 
''Returns authors of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== ECNumbers ===
<code>ECNumbers(pattern: Pattern) -> String</code> 
''Returns Enzymatic Commission numbers assigned to enzymes in the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== EntitySources ===
<code>EntitySources(pattern: Pattern) -> String</code> 
''Returns entity sources of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== ExperimentMethod ===
<code>ExperimentMethod(pattern: Pattern) -> String</code> 
''Get the experiment method. The value is always an upper-case string. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ExperimentMethod() == "INFRARED SPECTROSCOPY")</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== HasAllAuthors ===
<code>HasAllAuthors(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given authors. The comparison is case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllAuthors("Holmes", "Watson"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllECNumbers ===
<code>HasAllECNumbers(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given Enzymatic Commission numbers. It is possible to enter just a number prefix without the '.'. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllECNumbers("3.2.1.18", "3.3"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllEntitySources ===
<code>HasAllEntitySources(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given entity sources. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllEntitySources("GMO", "Natural", "Synthetic"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllHostOrganismGenus ===
<code>HasAllHostOrganismGenus(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given host organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllHostOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllHostOrganismIds ===
<code>HasAllHostOrganismIds(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given host organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllHostOrganismIds("7108", "11244"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllHostOrganisms ===
<code>HasAllHostOrganisms(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given host organism names. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllHostOrganisms("Spodoptera frugiperda", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllKeywords ===
<code>HasAllKeywords(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given keywords. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllKeywords("membrane", "glycoprotein"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllOriginOrganismGenus ===
<code>HasAllOriginOrganismGenus(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given origin organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllOriginOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllOriginOrganismIds ===
<code>HasAllOriginOrganismIds(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given origin organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllOriginOrganismIds("121791", "10090"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllOriginOrganisms ===
<code>HasAllOriginOrganisms(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given origin organism names. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllOriginOrganisms("Nipah virus", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyAuthor ===
<code>HasAnyAuthor(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given authors. The comparison is case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyAuthor("Holmes", "Watson"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyECNumber ===
<code>HasAnyECNumber(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given Enzymatic Commission number. It is possible to enter just a number prefix without the '.'s. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyECNumber("3.2.1.19", "3.3"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyEntitySources ===
<code>HasAnyEntitySources(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given entity sources. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyEntitySources("GMO", "Natural", "Synthetic"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyHostOrganism ===
<code>HasAnyHostOrganism(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given host organism names. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyHostOrganism("Spodoptera frugiperda", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyHostOrganismGenus ===
<code>HasAnyHostOrganismGenus(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given host organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyHostOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyHostOrganismId ===
<code>HasAnyHostOrganismId(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given host organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyHostOrganismId("7108", "11244"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyKeyword ===
<code>HasAnyKeyword(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given keywords. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyKeyword("membrane", "glycoprotein"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyOriginOrganism ===
<code>HasAnyOriginOrganism(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given origin organism names. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyOriginOrganism("Nipah virus", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyOriginOrganismGenus ===
<code>HasAnyOriginOrganismGenus(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given origin organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyOriginOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyOriginOrganismId ===
<code>HasAnyOriginOrganismId(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given origin organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyOriginOrganismId("121791", "10090"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HostOrganismGenus ===
<code>HostOrganismGenus(pattern: Pattern) -> String</code> 
''Returns host organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== HostOrganismIds ===
<code>HostOrganismIds(pattern: Pattern) -> String</code> 
''Returns host organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== HostOrganisms ===
<code>HostOrganisms(pattern: Pattern) -> String</code> 
''Returns host organism names of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== Keywords ===
<code>Keywords(pattern: Pattern) -> String</code> 
''Returns keywords of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== LatestRevisionDate ===
<code>LatestRevisionDate(pattern: Pattern) -> Value</code> 
''Get the latest revision date of the parent structure. The value has to be compared to the DateTime(year, month, day) object. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.LatestRevisionDate() >= DateTime(2008, 1, 1))</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== LatestRevisionYear ===
<code>LatestRevisionYear(pattern: Pattern) -> Integer</code> 
''Get the latest revision year of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.LatestRevisionYear() == 2006)</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== OriginOrganismGenus ===
<code>OriginOrganismGenus(pattern: Pattern) -> String</code> 
''Returns origin organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== OriginOrganismIds ===
<code>OriginOrganismIds(pattern: Pattern) -> String</code> 
''Returns origin organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== OriginOrganisms ===
<code>OriginOrganisms(pattern: Pattern) -> String</code> 
''Returns origin organism names of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== PolymerType ===
<code>PolymerType(pattern: Pattern) -> String</code> 
''Get the polymer type of the structure. Possible values are: NotAssigned, Protein, DNA, RNA, ProteinDNA, ProteinRNA, NucleicAcids, Mixture, Sugar, Other. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.PolymerType() == "ProteinDNA")</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== ProteinStoichiometry ===
<code>ProteinStoichiometry(pattern: Pattern) -> String</code> 
''Get the protein stoichiometry of the parent structure. Possible values are: NotAssigned, Monomer, Homomer, Heteromer. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ProteinStoichiometry() == "Heteromer")</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== ProteinStoichiometryString ===
<code>ProteinStoichiometryString(pattern: Pattern) -> String</code> 
''Get the protein stoichiometry string of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== ReleaseDate ===
<code>ReleaseDate(pattern: Pattern) -> Value</code> 
''Get the release date of the parent structure. The value has to be compared to the DateTime(year, month, day) object. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ReleaseDate() >= DateTime(2008, 1, 1))</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== ReleaseYear ===
<code>ReleaseYear(pattern: Pattern) -> Integer</code> 
''Get the release year of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ReleaseYear() == 2006)</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== Resolution ===
<code>Resolution(pattern: Pattern) -> Real</code> 
''Get the resolution in angstroms of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.Resolution() <= 2.4)</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== Weight ===
<code>Weight(pattern: Pattern) -> Real</code> 
''Get the weight of the molecule in kDa. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.Weight() > 100000.0)</code>
:: ''Returns residues in structures that satisfy the property.''
 
== Miscellaneous Functions ==
''Various useful functions. These function often require a special setup (i.e. only useful in Scripting window or in specific applications).''
=== AminoSequenceString ===
<code>AminoSequenceString(pattern: Pattern) -> String</code> 
''Returns a string of single-letter amino acids contained in the pattern.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: pattern: Pattern - ''Pattern to convert.''
;Examples
: <code>Pattern("1tqn_12").AminoSequenceString()</code>
:: ''Returns a string representing amino acids in the pattern '1tqn_12'.''
: <code>RegularMotifs(Pattern("1tqn_12").AminoSequenceString())</code>
:: ''Returns all regular patterns that correspond to the AMK sequence in 1tqn_12.''
----
=== AtomProperty ===
<code>AtomProperty(atomPattern: Pattern, name: String) -> ?</code> 
''If the property exists and the pattern consists of a single atom, returns the property. Otherwise, returns Nothing.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: atomPattern: Pattern - ''Single atom pattern.''
: name: String - ''Property name.''
;Examples
: <code>a.AtomProperty("charge")</code>
:: ''Gets the 'charge' property of the atom a. Where a is a single atom Pattern. This example will not work directly.''
: <code>Atoms().Filter(lambda a: a.AtomProperty("charge") >= 2)</code>
:: ''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 ===
<code>AtomSimilarity(a: Pattern, b: Pattern) -> Real</code> 
''Computes Jaccard/Tanimoto coefficient on atoms (element symbols) of both structures.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: a: Pattern - ''First pattern.''
: b: Pattern - ''Second pattern.''
;Examples
: <code>AtomSimilarity(Current(),Pattern("1tqn_12"))</code>
:: ''Computes the atom similarity between the current pattern and 1tqn_12. This example can be used in SiteBinder to create a descriptor (assuming a structure with id '1tqn_12' is loaded).''
----
=== CommonAtoms ===
<code>CommonAtoms(modelId: String) -> PatternSeq</code> 
''Returns a single pattern with atoms common with the model. Properties checked: atom id, element symbol, chain, residue number. This query is useful for example for atom selection in SiteBinder.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: modelId: String - ''Id of the model.''
;Examples
: <code>CommonAtoms("1tqn_12")</code>
:: ''Returns a pattern formed by atoms common with the '1tqn_12' structure.''
----
=== CSA ===
<code>CSA() -> PatternSeq</code> 
''Entries from Catalytic Site Atlas represented as patterns. Works only if used from the command line version of Queries and property configured.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Examples
: <code>CSA()</code>
:: ''All CSA sites for the given structure. This example will only work if used from the command line version of Queries and property configured.''
----
=== Current ===
<code>Current() -> Pattern</code> 
''A variable that is assigned by the application environment.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Examples
: <code>AtomSimilarity(Current(), Pattern("model"))</code>
:: ''Returns the atom similarity of the current pattern 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 ===
<code>Descriptor(pattern: Pattern, name: String) -> ?</code> 
''Returns the descriptor. If the descriptor does not exist, 'null' is returned.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: pattern: Pattern - ''Pattern that represents entire structure.''
: name: String - ''Descriptor name.''
;Examples
: <code>Current().Descriptor("similarity") >= 0.75</code>
:: ''Returns True if 'similarity' descriptor of the current pattern is at least 0.75. This example will work for example in SiteBinder's structure selection if the 'similarity' descriptor has been previously defined.''
----
=== DynamicInvoke ===
<code>DynamicInvoke(value: Value, name: String, isProperty: Bool, args: Value) -> Value</code> 
''Dynamically invoke a member. (internal)'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: value: Value - ''InnerQuery.''
: name: String - ''Member name.''
: isProperty: Bool - ''Is this a property.''
: args: Value - ''Array of arguments.''
----
=== Find ===
<code>Find(source: Pattern, patterns: PatternSeq) -> PatternSeq</code> 
''Converts the source pattern to a structure and finds patterns within it.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: source: Pattern - ''Where to look.''
: patterns: PatternSeq - ''Patterns to find.''
;Examples
: <code>AtomSimilarity(Current().Find(NotAtoms("N")).ToPattern(), Pattern("model").Find(NotAtoms("N")).ToPattern())</code>
:: ''Computes the atom similarity of the 'current' and 'model' patterns, but ignores N atoms. This example can be used in SiteBinder to create a descriptor (assuming a structure with id 'model' is loaded).''
----
=== GroupedAtoms ===
<code>GroupedAtoms(symbols: String*) -> PatternSeq</code> 
''Groups atoms using the element symbol and then returns each group as a single pattern.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: symbols: String* - ''Allowed element symbols.''
;Examples
: <code>GroupedAtoms()</code>
:: ''Returns groups of all atom types. For example if the input has atoms 5xC-1xO, patterns with 5xC and 1xO atoms are returned.''
: <code>GroupedAtoms('C', 'O')</code>
:: ''Returns groups of all atom types. For example if the input has atoms 5xC-1xO-6xH, patterns with 5xC and 1xO atoms are returned (but the H atoms are ignored).''
----
=== Pattern ===
<code>Pattern(structureName: String) -> Pattern</code> 
''Returns a structure represented as a pattern.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: structureName: String - ''Name of a structure.''
;Examples
: <code>Pattern("1tqn_12")</code>
:: ''Returns the structure '1tqn_12' represented as a pattern. Usable in defining descriptors or in Scripting window (using MQ.Execute).''
----
=== ResidueSimilarity ===
<code>ResidueSimilarity(a: Pattern, b: Pattern) -> Real</code> 
''Computes Jaccard/Tanimoto coefficient on residue names of both structures.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: a: Pattern - ''First pattern.''
: b: Pattern - ''Second pattern.''
;Examples
: <code>ResidueSimilarity(Current(), Pattern("1tqn_12"))</code>
:: ''Computes the residue similarity between the current pattern and '1tqn_12'. This example can be used in SiteBinder to create a descriptor (assuming a structure with id '1tqn_12' is loaded).''
----
=== ToPattern ===
<code>ToPattern(patterns: PatternSeq) -> Pattern</code> 
''Converts a sequence of Patterns (AtomSetSeq) to a single Pattern by merging all atoms into a single atom set. The Pattern type is required by some function such as AtomSimilarity.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: patterns: PatternSeq - ''Patterns to convert.''
;Examples
: <code>Residues("HIS").ToPattern()</code>
:: ''Converts a sequence of HIS residue Patterns to a single Pattern.''
: <code>AtomSimilarity(Current().Find(NotAtoms("N")).ToPattern(), Pattern("model").Find(NotAtoms("N")).ToPattern())</code>
:: ''Computes the atom similarity of the 'current' and 'model' patterns, but ignores N atoms.''
 
== Value Functions ==
''Functions such as addition or comparison of numbers.''
=== Abs ===
<code>Abs(x: Number) -> Number</code> 
''Computes the 'Abs' function of the argument.'' 
;Arguments
: x: Number - ''Argument.''
;Examples
: <code>Abs(x)</code>
:: ''Evaluates the expression.''
----
=== Divide (/) ===
<code>Divide(x: Number, y: Number) -> Number</code> 
''Computes the 'Divide' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x / y</code>
:: ''Evaluates the expression.''
----
=== Equal (==) ===
<code>Equal(x: Value, y: Value) -> Bool</code> 
''Determines the 'Equal' relation between two values.'' 
;Arguments
: x: Value - ''Left argument.''
: y: Value - ''Right argument.''
;Examples
: <code>x == y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== Greater (>) ===
<code>Greater(x: Number, y: Number) -> Bool</code> 
''Determines the 'Greater' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x > y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== GreaterEqual (>=) ===
<code>GreaterEqual(x: Number, y: Number) -> Bool</code> 
''Determines the 'GreaterEqual' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x >= y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== Less (<) ===
<code>Less(x: Number, y: Number) -> Bool</code> 
''Determines the 'Less' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x < y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== LessEqual (<=) ===
<code>LessEqual(x: Number, y: Number) -> Bool</code> 
''Determines the 'LessEqual' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x <= y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== LogicalAnd (&) ===
<code>LogicalAnd(xs: Bool+) -> Bool</code> 
''Computes 'LogicalAnd' of the input values.'' 
;Arguments
: xs: Bool+ - ''Arguments.''
;Examples
: <code>x & y</code>
:: ''Evaluates to True or False based on the values of x and y.''
----
=== LogicalNot (Not) ===
<code>LogicalNot(x: Bool) -> Bool</code> 
''Computes 'LogicalNot' of the input value. This function can be called using the shorthand 'Not'.'' 
;Arguments
: x: Bool - ''Argument.''
;Examples
: <code>LogicalNot(x)</code>
:: ''Evaluates to True or False based on the value of x.''
: <code>x.Not()</code>
:: ''Evaluates to True or False based on the value of x.''
----
=== LogicalOr (|) ===
<code>LogicalOr(xs: Bool+) -> Bool</code> 
''Computes 'LogicalOr' of the input values.'' 
;Arguments
: xs: Bool+ - ''Arguments.''
;Examples
: <code>x | y</code>
:: ''Evaluates to True or False based on the values of x and y.''
----
=== LogicalXor (Xor) ===
<code>LogicalXor(xs: Bool+) -> Bool</code> 
''Computes 'LogicalXor' of the input values. This function can be called using the shorthand 'Xor'.'' 
;Arguments
: xs: Bool+ - ''Arguments.''
;Examples
: <code>LogicalXor(x, y)</code>
:: ''Evaluates to True or False based on the values of x and y.''
: <code>Xor(x, y)</code>
:: ''Evaluates to True or False based on the values of x and y.''
----
=== Minus (-) ===
<code>Minus(x: Number) -> Number</code> 
''Computes the arithmetic negation of the argument.'' 
;Arguments
: x: Number - ''Argument.''
;Examples
: <code>-x</code>
:: ''Arithmetic negation of x.''
----
=== NotEqual (!=) ===
<code>NotEqual(x: Value, y: Value) -> Bool</code> 
''Determines the 'NotEqual' relation between two values.'' 
;Arguments
: x: Value - ''Left argument.''
: y: Value - ''Right argument.''
;Examples
: <code>x != y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== Plus (+) ===
<code>Plus(x: Number, y: Number) -> Number</code> 
''Computes the 'Plus' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x + y</code>
:: ''Evaluates the expression.''
----
=== Power (^) ===
<code>Power(x: Number, y: Number) -> Number</code> 
''Computes the 'Power' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x ^ y</code>
:: ''Evaluates the expression.''
----
=== Subtract (-) ===
<code>Subtract(x: Number, y: Number) -> Number</code> 
''Computes the 'Subtract' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x - y</code>
:: ''Evaluates the expression.''
----
=== Times (*) ===
<code>Times(x: Number, y: Number) -> Number</code> 
''Computes the 'Times' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x * y</code>
:: ''Evaluates the expression.''

PatternQuery:Language Reference

2015-04-23T20:47:45Z

Dave:

== Introduction ==

PatternQuery (PQ) is a user friendly chemical language primarily designed for defining atom patterns in molecules. PQ combines the clarity and brevity of programming languages with the versatility of natural language, aiming for an efficient inclusion of chemical and biochemical knowledge into the definition of patterns. PQ allows definitions based on chemical connectivity and three-dimensional structure at the same time. Additionally, in the case of molecules based on residue chains (such as proteins, nucleic acids, saccharides, etc.), PQ allows the user to include any amount of information regarding the residue level structure directly into the definition of the patternss.

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

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

Some of the functions return '''<code>PatternSeq</code>''' while other return '''<code>Pattern</code>'''.
* '''<code>Pattern</code>''' is a set of atoms.
* '''<code>PatternSeq</code>''' is a sequence of '''<code>Pattern</code>''' (the sets of atoms).

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

== Basic Query Functions ==
''Basic building blocks of the language - i.e. atoms, residues, and the like.''
=== AminoAcids ===
<code>AminoAcids() -> Residues</code> 
''Sequence of all residues with the 20 basic amino acid names.'' 
;Options
: ChargeType: String = "" - ''Specify type of the charge. Allowed values: Positive, Negative, Aromatic, Polar, NonPolar.''
;Examples
: <code>AminoAcids()</code>
:: ''All amino acids.''
: <code>AminoAcids(ChargeType = "Polar")</code>
:: ''Amino acids with polar charge.''
----
=== AtomIdRange ===
<code>AtomIdRange(minId: Integer, maxId: ?Integer) -> Atoms</code> 
''Sequence of atoms with minId <= atomId <= maxId.'' 
;Arguments
: minId: Integer - ''Minimum id.''
: maxId: ?Integer - ''Maximum id. If not specified, maxId = minId.''
;Examples
: <code>AtomIdRange(152, 161)</code>
:: ''Returns all atoms with id between 152 and 161 inclusive.''
----
=== AtomIds ===
<code>AtomIds(ids: Integer+) -> Atoms</code> 
''Sequence of atoms with specified identifiers.'' 
;Arguments
: ids: Integer+ - ''Identifiers.''
;Examples
: <code>AtomIds(1, 2, 3)</code>
:: ''Returns atoms with ids 1, 2, 3.''
----
=== AtomNames ===
<code>AtomNames(names: String+) -> Atoms</code> 
''Sequence of atoms with specified names.'' 
;Arguments
: names: String+ - ''Allowed names.''
;Examples
: <code>AtomNames("O1","NH1")</code>
:: ''Returns all atoms with names O1 or NH1.''
----
=== Atoms ===
<code>Atoms(symbols: String*) -> Atoms</code> 
''Sequence of atoms with specified element symbols. If no symbols are specified, yields all atoms one by one.'' 
;Arguments
: symbols: String* - ''Allowed element symbols.''
;Examples
: <code>Atoms("Zn","Ca")</code>
:: ''Returns all atoms with element symbol Zn or Ca''
----
=== Chains ===
<code>Chains(identifiers: Value*) -> PatternSeq</code> 
''Splits the structures into chains. If no identifiers are specified, all chains are returned.'' 
;Arguments
: identifiers: Value* - ''Chain identifiers.''
;Examples
: <code>Chains()</code>
:: ''Returns all chains.''
: <code>Chains("")</code>
:: ''Returns chains without specific identifier.''
: <code>Chains("A", "B")</code>
:: ''Returns chains A and B.''
----
=== Helices ===
<code>Helices() -> PatternSeq</code> 
''Returns all helices. This assumes the information about helices was present in the input structure.'' 
;Examples
: <code>Helices()</code>
:: ''Returns all helices.''
----
=== HetResidues ===
<code>HetResidues() -> Residues</code> 
''Sequence of all residues that contain HET atoms.'' 
;Options
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
;Examples
: <code>HetResidues()</code>
:: ''Returns all residues that contain HET atoms (ignores water).''
: <code>HetResidues(NoWaters=False)</code>
:: ''Returns all residues that contain HET atoms (includes water).''
----
=== ModifiedResidues ===
<code>ModifiedResidues(parentNames: String*) -> Residues</code> 
''Sequence of modified residues that originate from the specified name. If no names are specified, yields all modified residues one by one.'' 
;Arguments
: parentNames: String* - ''Parent residue names.''
;Examples
: <code>ModifiedResidues("MET")</code>
:: ''Returns all residues modified from MET (for example MSE).''
----
=== Named ===
<code>Named(patterns: PatternSeq) -> PatternSeq</code> 
'''Names' the pattern by its lowest atom id.'' 
;Arguments
: patterns: PatternSeq - ''Patterns to name.''
;Examples
: <code>Atoms("Zn").Named().AmbientAtoms(7)</code>
:: ''When exported, the result files will have names in the format '[parent id]_[pseudorandom number]_[zn atomid]'. If the Named function was not used, the name would be just '[parent id]_[pseudorandom number]'.''
----
=== NotAminoAcids ===
<code>NotAminoAcids() -> Residues</code> 
''Sequence of all residues that are not any of the 20 basic amino acids.'' 
;Options
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
;Examples
: <code>NotAminoAcids()</code>
:: ''Returns all residues that are not amino acids.''
----
=== NotAtomIds ===
<code>NotAtomIds(ids: Integer+) -> Atoms</code> 
''Sequence of atoms that do not have specified identifiers.'' 
;Arguments
: ids: Integer+ - ''Identifiers.''
;Examples
: <code>NotAtomIds(1, 2, 3)</code>
:: ''Returns atoms that do not have id 1, 2, nor 3.''
----
=== NotAtomNames ===
<code>NotAtomNames(names: String+) -> Atoms</code> 
''Sequence of atoms that do not have a specified name.'' 
;Arguments
: names: String+ - ''Forbidden names.''
;Examples
: <code>NotAtomNames("O4")</code>
:: ''Returns all atoms that are not called O4.''
----
=== NotAtoms ===
<code>NotAtoms(symbols: String+) -> Atoms</code> 
''Sequence of atoms that are not particular elements.'' 
;Arguments
: symbols: String+ - ''Forbidden element symbols.''
;Examples
: <code>NotAtoms("O")</code>
:: ''Returns all atoms that are not O.''
----
=== NotResidues ===
<code>NotResidues(names: Value+) -> Residues</code> 
''Sequence of residues that are not called by the specified names.'' 
;Arguments
: names: Value+ - ''Forbidden residue names.''
;Examples
: <code>NotResidues("THR","CYS")</code>
:: ''Returns all residues that are not THR or CYS.''
----
=== RegularMotifs ===
<code>RegularMotifs(regex: Value) -> PatternSeq</code> 
''Identifies regular motifs. The protein is split into individual chains and the residues are sorted by their Sequence Number before the motifs are identified. The query does not check if adjacent residues have consecutive Sequence Numbers. The query works in two modes: Amino and Nucleotide, on amino acids and nucleotides respectively. In the Amino mode, all the derivatives of standard residues are treated as the standard residues, as long as this information is properly annotated in MODRES or _pdbx_struct_mod_residue field. The default mode is 'Amino''' 
;Arguments
: regex: Value - ''Regular expression on one letter abbreviations of amino acids.''
;Options
: Type: String = "Amino" - ''Determines the type of the query. Allowed values: Amino, Nucleotide.''
;Examples
: <code>RegularMotifs("RGD")</code>
:: ''Finds all RGD motifs.''
: <code>RegularMotifs("ACGTU", Type = 'Nucleotide')</code>
:: ''Finds all consecutive occurrences of the ACGTU nucleotides.''
: <code>RegularMotifs(".HC.").Filter(lambda m: m.IsConnected())</code>
:: ''Finds all 4 residue motifs with ?-HIS-CYS-? that are connected.''
----
=== ResidueIdRange ===
<code>ResidueIdRange(chain: String, min: Integer, max: ?Integer) -> Residues</code> 
''Sequence of residues with specific chain and min <= sequence number <= max.'' 
;Arguments
: chain: String - ''Chain identifier. Case sensitive (a != A).''
: min: Integer - ''Minimum sequence number.''
: max: ?Integer - ''Maximum sequence number. If not specified, max = min.''
;Examples
: <code>ResidueIdRange("A", 161, 165)</code>
:: ''Returns all residues on chain A with seq. number between 161 and 165 inclusive.''
----
=== ResidueIds ===
<code>ResidueIds(ids: String+) -> Residues</code> 
''Sequence of residues with specific identifiers. If the structure does not contain a residue with the given identifier, it is skipped.'' 
;Arguments
: ids: String+ - ''One or more identifiers in the format 'NUMBER [CHAIN] [i:INSERTIONCODE]' (parameters in [] are optional, for example '175 i:12' or '143 B'). Case sensitive (a != A).''
;Examples
: <code>ResidueIds("132 A", "178 A")</code>
:: ''Returns residues A 123 and A 178 (provided the input structure contains them).''
----
=== Residues ===
<code>Residues(names: String*) -> Residues</code> 
''Sequence of residues with specified names. If no names are specified, yields all residues one by one.'' 
;Arguments
: names: String* - ''Allowed residue names.''
;Examples
: <code>Residues("HIS", "CYS")</code>
:: ''Returns all HIS or CYS residues.''
----
=== RingAtoms ===
<code>RingAtoms(atom: Atoms, ring: ?Rings) -> Atoms</code> 
''Returns all rings atoms.'' 
;Arguments
: atom: Atoms - ''Atom types.''
: ring: ?Rings - ''Specific ring.''
;Examples
: <code>RingAtoms(Atoms("C"), Rings(4 * ["C"] + ["O"]))</code>
:: ''Returns all C atoms on a ring with 4C and O.''
----
=== Rings ===
<code>Rings(atoms: Value*) -> Rings</code> 
''Sequence of rings with particular atoms. If no atoms are specified, yields all rings (cycles) one by one. The order of atoms matters.'' 
;Arguments
: atoms: Value* - ''Ring atoms.''
;Examples
: <code>Rings()</code>
:: ''Returns all rings.''
: <code>Rings(5 * ["C"] + ["O"])</code>
:: ''Returns all rings with 5C and 1O atoms.''
: <code>Rings(["C", "C", "N", "C", "N"])</code>
:: ''Returns all rings with C-C-N-C-N atoms.''
: <code>Or(Rings(["C", "C", "N", "C", "N"]), Rings(["C", "C", "C", "N", "N"]))</code>
:: ''Returns all rings with C-C-N-C-N or C-C-C-N-N atoms.''
----
=== Sheets ===
<code>Sheets() -> PatternSeq</code> 
''Returns all sheets. This assumes the information about sheets was present in the input structure.'' 
;Examples
: <code>Sheets()</code>
:: ''Returns all sheets.''
 
== Advanced Query Functions ==
''Advanced building blocks of the language.''
=== Flatten ===
<code>Flatten(patterns: PatternSeq, selector: Pattern->PatternSeq) -> PatternSeq</code> 
''Converts a sequence of sequence of patterns into a single 'flat' sequence.'' 
;Arguments
: patterns: PatternSeq - ''Patterns to project.''
: selector: Pattern->PatternSeq - ''The selector.''
;Examples
: <code>Residues("HIS").Flatten(lambda m: m.Find(Atoms("C")))</code>
:: ''Returns all C atoms on HIS residues.''
----
=== Inside ===
<code>Inside(patterns: PatternSeq, where: PatternSeq) -> PatternSeq</code> 
''Finds patterns within another pattern. Equivalent to where.Flatten(lambda m: m.Find(patterns))'' 
;Arguments
: patterns: PatternSeq - ''Patterns to find.''
: where: PatternSeq - ''Where to find them.''
;Examples
: <code>Atoms("C").Inside(Residues("HIS"))</code>
:: ''Returns all C atoms on HIS residues.''
----
=== Or ===
<code>Or(patterns: PatternSeq+) -> PatternSeq</code> 
''Merges several pattern sequences into one.'' 
;Arguments
: patterns: PatternSeq+ - ''Patterns to merge.''
;Examples
: <code>Or(Atoms("Zn").ConnectedResidues(1), Rings())</code>
:: ''Finds all zincs and their connected residues or rings.''
----
=== ToAtoms ===
<code>ToAtoms(patterns: PatternSeq) -> PatternSeq</code> 
''Collects all 'inner' patterns and yields all unique atoms one by one.'' 
;Arguments
: patterns: PatternSeq - ''Patterns to split.''
;Examples
: <code>Residues("HIS").ToAtoms()</code>
:: ''Returns all atoms on HIS residues one by one.''
----
=== ToResidues ===
<code>ToResidues(patterns: PatternSeq) -> PatternSeq</code> 
''Collects all 'inner' patterns and yields all unique residues one by one. The residues contain only the atoms that have been yielded by the inner query.'' 
;Arguments
: patterns: PatternSeq - ''Patterns to split.''
;Examples
: <code>Atoms("C").ToResidues()</code>
:: ''Returns all C atoms grouped by residues.''
----
=== Union ===
<code>Union(patterns: PatternSeq) -> PatternSeq</code> 
''Collects all 'inner' patterns and yields one created from their unique atoms.'' 
;Arguments
: patterns: PatternSeq - ''Patterns to merge.''
;Examples
: <code>Rings().Union()</code>
:: ''Creates a single pattern that contains all rings.''
 
== Filter Functions ==
''Functions useful for filtering patterns.''
=== Contains ===
<code>Contains(where: Pattern, what: PatternSeq) -> Bool</code> 
''Checks if a pattern is contained within another one. Equivalent to where.Count(what) > 0.'' 
;Arguments
: where: Pattern - ''Where to look.''
: what: PatternSeq - ''What to find.''
;Examples
: <code>HetResidues().Filter(lambda m: m.Contains(Rings(5*['C']+['O'])).Not())</code>
:: ''Returns all HET residues that do not contain a 5CO ring.''
----
=== Count ===
<code>Count(where: Pattern, what: PatternSeq) -> Integer</code> 
''Counts all occurrences of pattern 'what' in pattern 'where'.'' 
;Arguments
: where: Pattern - ''Where to count it.''
: what: PatternSeq - ''What pattern to count.''
;Examples
: <code>m.Count(Residues("HIS"))</code>
:: ''Returns the count of HIS residues in the pattern m. Where m is a Pattern (for example when using the Filter function or returned by the ToPattern() function). This example will not work directly and is here to illustrate a concept.''
: <code>Atoms("Zn").ConnectedResidues(1).Filter(lambda m: m.Count(Residues("HIS")) == 2)</code>
:: ''Patterns with Zn atoms and its connected residues with exactly 2 HIS residues.''
----
=== ExecuteIf ===
<code>ExecuteIf(query: PatternSeq, condition: Pattern->Bool) -> PatternSeq</code> 
''Executes a query only if the condition is met. Otherwise, return an empty sequence of patterns.'' 
;Arguments
: query: PatternSeq - ''Query to execute.''
: condition: Pattern->Bool - ''Condition that must be satisfied for the parent structure/pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.Resolution() <= 2.4)</code>
:: ''Returns residues in structures that have resolution lower than 2.4ang.''
: <code>AminoAcids().ExecuteIf(lambda p: p.Count(Atoms('Fe')) > 3)</code>
:: ''Returns all amino acids in structures that have at least 3 Fe atoms.''
----
=== Filter ===
<code>Filter(patterns: PatternSeq, filter: Pattern->Bool) -> PatternSeq</code> 
''Filters a sequence of patterns with a given predicate.'' 
;Arguments
: patterns: PatternSeq - ''Patterns to filter.''
: filter: Pattern->Bool - ''Filter predicate.''
;Examples
: <code>Residues().Filter(lambda m: m.Count(Atoms("C")) >= 3)</code>
:: ''Returns all residues that contain at least 3 C atoms.''
----
=== IsConnected ===
<code>IsConnected(pattern: Pattern) -> Bool</code> 
''Checks if a particular pattern is a connected graph.'' 
;Arguments
: pattern: Pattern - ''A pattern to test.''
;Examples
: <code>Atoms("Zn").AmbientResidues(3).Filter(lambda m: m.IsConnected())</code>
:: ''Finds all patterns with a Zn and residues within 3 ang, where all the ambient residues are connected to the central atom.''
----
=== IsConnectedTo ===
<code>IsConnectedTo(where: Pattern, patterns: PatternSeq) -> Bool</code> 
''Checks if a particular pattern is connected to any other specified pattern. The patterns must have empty intersection for this function to return true.'' 
;Arguments
: where: Pattern - ''A pattern to test.''
: patterns: PatternSeq - ''Pattern sequence to test against.''
;Examples
: <code>Atoms().Filter(lambda a: a.IsConnectedTo(Rings()))</code>
:: ''Finds all atoms that are connected to a ring they do not belong to.''
----
=== IsNotConnectedTo ===
<code>IsNotConnectedTo(what: Pattern, patterns: PatternSeq) -> Bool</code> 
''Checks if a particular pattern is not connected to any other specified pattern. The patterns must have empty intersection for this function to return true.'' 
;Arguments
: what: Pattern - ''A pattern to test.''
: patterns: PatternSeq - ''Pattern sequence to test against.''
;Examples
: <code>Residues().Filter(lambda r: r.IsNotConnectedTo(Atoms("Ca")))</code>
:: ''Finds all residues that are not connected to Ca atoms. The residue itself can still contain Ca atoms.''
----
=== NearestDistanceTo ===
<code>NearestDistanceTo(where: Pattern, patterns: PatternSeq) -> Real</code> 
''Finds the distance to a particular pattern.'' 
;Arguments
: where: Pattern - ''A pattern to test.''
: patterns: PatternSeq - ''Pattern sequence to test against.''
;Examples
: <code>Atoms().Filter(lambda m: m.NearestDistanceTo(Residues("ASP")) >= 5)</code>
:: ''Finds all atoms that are at least 5 (angstroms) away from any ASP residue.''
----
=== SeqCount ===
<code>SeqCount(what: PatternSeq) -> Integer</code> 
''Counts the length of a sequence of motifs.'' 
;Arguments
: what: PatternSeq - ''What pattern sequence to count.''
;Examples
: <code>Atoms("Zn").AmbientResidues(3).Filter(lambda m: m.Find(Residues("HIS")).SeqCount() > 1)</code>
:: ''Returns a sequence of patterns with Zn atom and residues within 3ang if the pattern contains at least 2 HIS residues.''
 
== Topology Functions ==
''Functions that rely on the topology of patterns.''
=== ConnectedAtoms ===
<code>ConnectedAtoms(pattern: PatternSeq, n: Integer) -> PatternSeq</code> 
''Surrounds the inner pattern by n layers of atoms.'' 
;Arguments
: pattern: PatternSeq - ''Basic pattern.''
: n: Integer - ''Number of atom layers to connect.''
;Options
: YieldNamedDuplicates: Bool = False - ''Yield duplicate patterns if they have a different name.''
;Examples
: <code>Residues("MAN").ConnectedAtoms(2)</code>
:: ''Finds all MAN residues and then adds two connected levels of atoms to them.''
----
=== ConnectedResidues ===
<code>ConnectedResidues(pattern: PatternSeq, n: Integer) -> PatternSeq</code> 
''Surrounds the inner pattern by n layers of residues.'' 
;Arguments
: pattern: PatternSeq - ''Basic pattern.''
: n: Integer - ''Number of residue layers to connect.''
;Options
: YieldNamedDuplicates: Bool = False - ''Yield duplicate patterns if they have a different name.''
;Examples
: <code>Atoms("Zn").ConnectedResidues(1)</code>
:: ''Finds all Zn atoms and adds all residues that are connected to them.''
----
=== Path ===
<code>Path(patterns: PatternSeq+) -> PatternSeq</code> 
''Creates a new pattern from 'connected' parts.'' 
;Arguments
: patterns: PatternSeq+ - ''Patterns to path.''
;Examples
: <code>Path(Atoms("O"), Atoms("C"), Atoms("O"))</code>
:: ''Finds patterns with two O and one C atoms where the C atoms is connected to the O ones.''
----
=== Star ===
<code>Star(center: PatternSeq, patterns: PatternSeq+) -> PatternSeq</code> 
''Creates a new pattern from a central one and connected parts.'' 
;Arguments
: center: PatternSeq - ''Center pattern.''
: patterns: PatternSeq+ - ''Patterns to chain.''
;Examples
: <code>Star(Atoms("C"), Atoms("O"), Atoms("O"))</code>
:: ''Finds patterns with two O atoms and one C atom in the center.''
: <code>Atoms("C").Star(Atoms("O"), Atoms("O"))</code>
:: ''Finds patterns with two O atoms and one C atom in the center.''
 
== Geometry Functions ==
''Functions that rely on the geometry of patterns.''
=== AmbientAtoms ===
<code>AmbientAtoms(pattern: PatternSeq, r: Number) -> PatternSeq</code> 
''Surrounds the inner pattern by atoms that within the given radius from the inner pattern.'' 
;Arguments
: pattern: PatternSeq - ''Basic pattern.''
: r: Number - ''Radius.''
;Options
: ExcludeBase: Bool = False - ''Exclude the central original pattern.''
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
: YieldNamedDuplicates: Bool = False - ''Yield duplicate patterns if they have a different name.''
;Examples
: <code>Atoms("Fe").AmbientAtoms(4)</code>
:: ''Finds Fe atoms and all atoms within 4 (angstroms) from each of them.''
----
=== AmbientResidues ===
<code>AmbientResidues(pattern: PatternSeq, r: Number) -> PatternSeq</code> 
''Surrounds the inner pattern by residues that have at least one atom within the given radius from the inner pattern.'' 
;Arguments
: pattern: PatternSeq - ''Basic pattern.''
: r: Number - ''Radius.''
;Options
: ExcludeBase: Bool = False - ''Exclude the central original pattern.''
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
: YieldNamedDuplicates: Bool = False - ''Yield duplicate patterns if they have a different name.''
;Examples
: <code>Rings(6 * ["C"]).AmbientResidues(4)</code>
:: ''Finds rings with 6C atoms and all residues within 4 (angstroms) from each of them.''
----
=== Cluster ===
<code>Cluster(r: Number, patterns: PatternSeq+) -> PatternSeq</code> 
''Clusters all patterns that are pairwise closer than r (angstroms).'' 
;Arguments
: r: Number - ''Maximum distance between two patterns in the cluster.''
: patterns: PatternSeq+ - ''Patterns to cluster.''
;Examples
: <code>Cluster(4, Atoms("Ca"), Rings(5 * ["C"] + ["O"]))</code>
:: ''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 ===
<code>Filled(pattern: PatternSeq) -> PatternSeq</code> 
''Adds all atoms that fall within the circumsphere (with radius multiplied by the factor) of the basic pattern.'' 
;Arguments
: pattern: PatternSeq - ''Basic pattern.''
;Options
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
: RadiusFactor: Number = 0.75 - ''Circumsphere radius factor.''
;Examples
: <code>Cluster(4, Residues("HIS")).Filled(RadiusFactor = 0.75)</code>
:: ''Finds clusters of HIS residues and all atoms within the circumsphere.''
----
=== Near ===
<code>Near(r: Number, patterns: PatternSeq+) -> PatternSeq</code> 
''Clusters all patterns that are pairwise closer than r (angstroms) and checks if the "counts" match.'' 
;Arguments
: r: Number - ''Maximum distance between two sub-patterns in the pattern.''
: patterns: PatternSeq+ - ''Patterns to 'cluster'.''
;Examples
: <code>Near(4, Atoms("Ca"), Atoms("Ca"), Rings(5 * ["C"] + ["O"]))</code>
:: ''Finds all instance of a single ring with 5C and O atoms and two Ca atoms that are closer than 4 (angstroms).''
 
== Meta-data Functions ==
''Functions dealing with meta-data about structures such as release date or authors.''
=== Authors ===
<code>Authors(pattern: Pattern) -> String</code> 
''Returns authors of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== ECNumbers ===
<code>ECNumbers(pattern: Pattern) -> String</code> 
''Returns Enzymatic Commission numbers assigned to enzymes in the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== EntitySources ===
<code>EntitySources(pattern: Pattern) -> String</code> 
''Returns entity sources of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== ExperimentMethod ===
<code>ExperimentMethod(pattern: Pattern) -> String</code> 
''Get the experiment method. The value is always an upper-case string. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ExperimentMethod() == "INFRARED SPECTROSCOPY")</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== HasAllAuthors ===
<code>HasAllAuthors(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given authors. The comparison is case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllAuthors("Holmes", "Watson"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllECNumbers ===
<code>HasAllECNumbers(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given Enzymatic Commission numbers. It is possible to enter just a number prefix without the '.'. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllECNumbers("3.2.1.18", "3.3"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllEntitySources ===
<code>HasAllEntitySources(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given entity sources. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllEntitySources("GMO", "Natural", "Synthetic"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllHostOrganismGenus ===
<code>HasAllHostOrganismGenus(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given host organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllHostOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllHostOrganismIds ===
<code>HasAllHostOrganismIds(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given host organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllHostOrganismIds("7108", "11244"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllHostOrganisms ===
<code>HasAllHostOrganisms(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given host organism names. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllHostOrganisms("Spodoptera frugiperda", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllKeywords ===
<code>HasAllKeywords(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given keywords. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllKeywords("membrane", "glycoprotein"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllOriginOrganismGenus ===
<code>HasAllOriginOrganismGenus(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given origin organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllOriginOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllOriginOrganismIds ===
<code>HasAllOriginOrganismIds(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given origin organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllOriginOrganismIds("121791", "10090"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllOriginOrganisms ===
<code>HasAllOriginOrganisms(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given origin organism names. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllOriginOrganisms("Nipah virus", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyAuthor ===
<code>HasAnyAuthor(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given authors. The comparison is case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyAuthor("Holmes", "Watson"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyECNumber ===
<code>HasAnyECNumber(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given Enzymatic Commission number. It is possible to enter just a number prefix without the '.'s. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyECNumber("3.2.1.19", "3.3"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyEntitySources ===
<code>HasAnyEntitySources(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given entity sources. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyEntitySources("GMO", "Natural", "Synthetic"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyHostOrganism ===
<code>HasAnyHostOrganism(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given host organism names. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyHostOrganism("Spodoptera frugiperda", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyHostOrganismGenus ===
<code>HasAnyHostOrganismGenus(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given host organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyHostOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyHostOrganismId ===
<code>HasAnyHostOrganismId(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given host organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyHostOrganismId("7108", "11244"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyKeyword ===
<code>HasAnyKeyword(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given keywords. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyKeyword("membrane", "glycoprotein"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyOriginOrganism ===
<code>HasAnyOriginOrganism(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given origin organism names. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyOriginOrganism("Nipah virus", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyOriginOrganismGenus ===
<code>HasAnyOriginOrganismGenus(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given origin organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyOriginOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyOriginOrganismId ===
<code>HasAnyOriginOrganismId(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given origin organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyOriginOrganismId("121791", "10090"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HostOrganismGenus ===
<code>HostOrganismGenus(pattern: Pattern) -> String</code> 
''Returns host organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== HostOrganismIds ===
<code>HostOrganismIds(pattern: Pattern) -> String</code> 
''Returns host organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== HostOrganisms ===
<code>HostOrganisms(pattern: Pattern) -> String</code> 
''Returns host organism names of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== Keywords ===
<code>Keywords(pattern: Pattern) -> String</code> 
''Returns keywords of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== LatestRevisionDate ===
<code>LatestRevisionDate(pattern: Pattern) -> Value</code> 
''Get the latest revision date of the parent structure. The value has to be compared to the DateTime(year, month, day) object. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.LatestRevisionDate() >= DateTime(2008, 1, 1))</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== LatestRevisionYear ===
<code>LatestRevisionYear(pattern: Pattern) -> Integer</code> 
''Get the latest revision year of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.LatestRevisionYear() == 2006)</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== OriginOrganismGenus ===
<code>OriginOrganismGenus(pattern: Pattern) -> String</code> 
''Returns origin organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== OriginOrganismIds ===
<code>OriginOrganismIds(pattern: Pattern) -> String</code> 
''Returns origin organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== OriginOrganisms ===
<code>OriginOrganisms(pattern: Pattern) -> String</code> 
''Returns origin organism names of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== PolymerType ===
<code>PolymerType(pattern: Pattern) -> String</code> 
''Get the polymer type of the structure. Possible values are: NotAssigned, Protein, DNA, RNA, ProteinDNA, ProteinRNA, NucleicAcids, Mixture, Sugar, Other. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.PolymerType() == "ProteinDNA")</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== ProteinStoichiometry ===
<code>ProteinStoichiometry(pattern: Pattern) -> String</code> 
''Get the protein stoichiometry of the parent structure. Possible values are: NotAssigned, Monomer, Homomer, Heteromer. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ProteinStoichiometry() == "Heteromer")</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== ProteinStoichiometryString ===
<code>ProteinStoichiometryString(pattern: Pattern) -> String</code> 
''Get the protein stoichiometry string of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== ReleaseDate ===
<code>ReleaseDate(pattern: Pattern) -> Value</code> 
''Get the release date of the parent structure. The value has to be compared to the DateTime(year, month, day) object. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ReleaseDate() >= DateTime(2008, 1, 1))</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== ReleaseYear ===
<code>ReleaseYear(pattern: Pattern) -> Integer</code> 
''Get the release year of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ReleaseYear() == 2006)</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== Resolution ===
<code>Resolution(pattern: Pattern) -> Real</code> 
''Get the resolution in angstroms of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.Resolution() <= 2.4)</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== Weight ===
<code>Weight(pattern: Pattern) -> Real</code> 
''Get the weight of the molecule in kDa. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.Weight() > 100000.0)</code>
:: ''Returns residues in structures that satisfy the property.''
 
== Miscellaneous Functions ==
''Various useful functions. These function often require a special setup (i.e. only useful in Scripting window or in specific applications).''
=== AminoSequenceString ===
<code>AminoSequenceString(pattern: Pattern) -> String</code> 
''Returns a string of single-letter amino acids contained in the pattern.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: pattern: Pattern - ''Pattern to convert.''
;Examples
: <code>Pattern("1tqn_12").AminoSequenceString()</code>
:: ''Returns a string representing amino acids in the pattern '1tqn_12'.''
: <code>RegularMotifs(Pattern("1tqn_12").AminoSequenceString())</code>
:: ''Returns all regular patterns that correspond to the AMK sequence in 1tqn_12.''
----
=== AtomProperty ===
<code>AtomProperty(atomPattern: Pattern, name: String) -> ?</code> 
''If the property exists and the pattern consists of a single atom, returns the property. Otherwise, returns Nothing.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: atomPattern: Pattern - ''Single atom pattern.''
: name: String - ''Property name.''
;Examples
: <code>a.AtomProperty("charge")</code>
:: ''Gets the 'charge' property of the atom a. Where a is a single atom Pattern. This example will not work directly.''
: <code>Atoms().Filter(lambda a: a.AtomProperty("charge") >= 2)</code>
:: ''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 ===
<code>AtomSimilarity(a: Pattern, b: Pattern) -> Real</code> 
''Computes Jaccard/Tanimoto coefficient on atoms (element symbols) of both structures.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: a: Pattern - ''First pattern.''
: b: Pattern - ''Second pattern.''
;Examples
: <code>AtomSimilarity(Current(),Pattern("1tqn_12"))</code>
:: ''Computes the atom similarity between the current pattern and 1tqn_12. This example can be used in SiteBinder to create a descriptor (assuming a structure with id '1tqn_12' is loaded).''
----
=== CommonAtoms ===
<code>CommonAtoms(modelId: String) -> PatternSeq</code> 
''Returns a single pattern with atoms common with the model. Properties checked: atom id, element symbol, chain, residue number. This query is useful for example for atom selection in SiteBinder.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: modelId: String - ''Id of the model.''
;Examples
: <code>CommonAtoms("1tqn_12")</code>
:: ''Returns a pattern formed by atoms common with the '1tqn_12' structure.''
----
=== CSA ===
<code>CSA() -> PatternSeq</code> 
''Entries from Catalytic Site Atlas represented as patterns. Works only if used from the command line version of Queries and property configured.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Examples
: <code>CSA()</code>
:: ''All CSA sites for the given structure. This example will only work if used from the command line version of Queries and property configured.''
----
=== Current ===
<code>Current() -> Pattern</code> 
''A variable that is assigned by the application environment.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Examples
: <code>AtomSimilarity(Current(), Pattern("model"))</code>
:: ''Returns the atom similarity of the current pattern 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 ===
<code>Descriptor(pattern: Pattern, name: String) -> ?</code> 
''Returns the descriptor. If the descriptor does not exist, 'null' is returned.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: pattern: Pattern - ''Pattern that represents entire structure.''
: name: String - ''Descriptor name.''
;Examples
: <code>Current().Descriptor("similarity") >= 0.75</code>
:: ''Returns True if 'similarity' descriptor of the current pattern is at least 0.75. This example will work for example in SiteBinder's structure selection if the 'similarity' descriptor has been previously defined.''
----
=== DynamicInvoke ===
<code>DynamicInvoke(value: Value, name: String, isProperty: Bool, args: Value) -> Value</code> 
''Dynamically invoke a member. (internal)'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: value: Value - ''InnerQuery.''
: name: String - ''Member name.''
: isProperty: Bool - ''Is this a property.''
: args: Value - ''Array of arguments.''
----
=== Find ===
<code>Find(source: Pattern, patterns: PatternSeq) -> PatternSeq</code> 
''Converts the source pattern to a structure and finds patterns within it.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: source: Pattern - ''Where to look.''
: patterns: PatternSeq - ''Patterns to find.''
;Examples
: <code>AtomSimilarity(Current().Find(NotAtoms("N")).ToPattern(), Pattern("model").Find(NotAtoms("N")).ToPattern())</code>
:: ''Computes the atom similarity of the 'current' and 'model' patterns, but ignores N atoms. This example can be used in SiteBinder to create a descriptor (assuming a structure with id 'model' is loaded).''
----
=== GroupedAtoms ===
<code>GroupedAtoms(symbols: String*) -> PatternSeq</code> 
''Groups atoms using the element symbol and then returns each group as a single pattern.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: symbols: String* - ''Allowed element symbols.''
;Examples
: <code>GroupedAtoms()</code>
:: ''Returns groups of all atom types. For example if the input has atoms 5xC-1xO, patterns with 5xC and 1xO atoms are returned.''
: <code>GroupedAtoms('C', 'O')</code>
:: ''Returns groups of all atom types. For example if the input has atoms 5xC-1xO-6xH, patterns with 5xC and 1xO atoms are returned (but the H atoms are ignored).''
----
=== Pattern ===
<code>Pattern(structureName: String) -> Pattern</code> 
''Returns a structure represented as a pattern.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: structureName: String - ''Name of a structure.''
;Examples
: <code>Pattern("1tqn_12")</code>
:: ''Returns the structure '1tqn_12' represented as a pattern. Usable in defining descriptors or in Scripting window (using MQ.Execute).''
----
=== ResidueSimilarity ===
<code>ResidueSimilarity(a: Pattern, b: Pattern) -> Real</code> 
''Computes Jaccard/Tanimoto coefficient on residue names of both structures.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: a: Pattern - ''First pattern.''
: b: Pattern - ''Second pattern.''
;Examples
: <code>ResidueSimilarity(Current(), Pattern("1tqn_12"))</code>
:: ''Computes the residue similarity between the current pattern and '1tqn_12'. This example can be used in SiteBinder to create a descriptor (assuming a structure with id '1tqn_12' is loaded).''
----
=== ToPattern ===
<code>ToPattern(patterns: PatternSeq) -> Pattern</code> 
''Converts a sequence of Patterns (AtomSetSeq) to a single Pattern by merging all atoms into a single atom set. The Pattern type is required by some function such as AtomSimilarity.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: patterns: PatternSeq - ''Patterns to convert.''
;Examples
: <code>Residues("HIS").ToPattern()</code>
:: ''Converts a sequence of HIS residue Patterns to a single Pattern.''
: <code>AtomSimilarity(Current().Find(NotAtoms("N")).ToPattern(), Pattern("model").Find(NotAtoms("N")).ToPattern())</code>
:: ''Computes the atom similarity of the 'current' and 'model' patterns, but ignores N atoms.''
 
== Value Functions ==
''Functions such as addition or comparison of numbers.''
=== Abs ===
<code>Abs(x: Number) -> Number</code> 
''Computes the 'Abs' function of the argument.'' 
;Arguments
: x: Number - ''Argument.''
;Examples
: <code>Abs(x)</code>
:: ''Evaluates the expression.''
----
=== Divide (/) ===
<code>Divide(x: Number, y: Number) -> Number</code> 
''Computes the 'Divide' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x / y</code>
:: ''Evaluates the expression.''
----
=== Equal (==) ===
<code>Equal(x: Value, y: Value) -> Bool</code> 
''Determines the 'Equal' relation between two values.'' 
;Arguments
: x: Value - ''Left argument.''
: y: Value - ''Right argument.''
;Examples
: <code>x == y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== Greater (>) ===
<code>Greater(x: Number, y: Number) -> Bool</code> 
''Determines the 'Greater' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x > y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== GreaterEqual (>=) ===
<code>GreaterEqual(x: Number, y: Number) -> Bool</code> 
''Determines the 'GreaterEqual' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x >= y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== Less (<) ===
<code>Less(x: Number, y: Number) -> Bool</code> 
''Determines the 'Less' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x < y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== LessEqual (<=) ===
<code>LessEqual(x: Number, y: Number) -> Bool</code> 
''Determines the 'LessEqual' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x <= y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== LogicalAnd (&) ===
<code>LogicalAnd(xs: Bool+) -> Bool</code> 
''Computes 'LogicalAnd' of the input values.'' 
;Arguments
: xs: Bool+ - ''Arguments.''
;Examples
: <code>x & y</code>
:: ''Evaluates to True or False based on the values of x and y.''
----
=== LogicalNot (Not) ===
<code>LogicalNot(x: Bool) -> Bool</code> 
''Computes 'LogicalNot' of the input value. This function can be called using the shorthand 'Not'.'' 
;Arguments
: x: Bool - ''Argument.''
;Examples
: <code>LogicalNot(x)</code>
:: ''Evaluates to True or False based on the value of x.''
: <code>x.Not()</code>
:: ''Evaluates to True or False based on the value of x.''
----
=== LogicalOr (|) ===
<code>LogicalOr(xs: Bool+) -> Bool</code> 
''Computes 'LogicalOr' of the input values.'' 
;Arguments
: xs: Bool+ - ''Arguments.''
;Examples
: <code>x | y</code>
:: ''Evaluates to True or False based on the values of x and y.''
----
=== LogicalXor (Xor) ===
<code>LogicalXor(xs: Bool+) -> Bool</code> 
''Computes 'LogicalXor' of the input values. This function can be called using the shorthand 'Xor'.'' 
;Arguments
: xs: Bool+ - ''Arguments.''
;Examples
: <code>LogicalXor(x, y)</code>
:: ''Evaluates to True or False based on the values of x and y.''
: <code>Xor(x, y)</code>
:: ''Evaluates to True or False based on the values of x and y.''
----
=== Minus (-) ===
<code>Minus(x: Number) -> Number</code> 
''Computes the arithmetic negation of the argument.'' 
;Arguments
: x: Number - ''Argument.''
;Examples
: <code>-x</code>
:: ''Arithmetic negation of x.''
----
=== NotEqual (!=) ===
<code>NotEqual(x: Value, y: Value) -> Bool</code> 
''Determines the 'NotEqual' relation between two values.'' 
;Arguments
: x: Value - ''Left argument.''
: y: Value - ''Right argument.''
;Examples
: <code>x != y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== Plus (+) ===
<code>Plus(x: Number, y: Number) -> Number</code> 
''Computes the 'Plus' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x + y</code>
:: ''Evaluates the expression.''
----
=== Power (^) ===
<code>Power(x: Number, y: Number) -> Number</code> 
''Computes the 'Power' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x ^ y</code>
:: ''Evaluates the expression.''
----
=== Subtract (-) ===
<code>Subtract(x: Number, y: Number) -> Number</code> 
''Computes the 'Subtract' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x - y</code>
:: ''Evaluates the expression.''
----
=== Times (*) ===
<code>Times(x: Number, y: Number) -> Number</code> 
''Computes the 'Times' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x * y</code>
:: ''Evaluates the expression.''

PatternQuery:Language Reference

2015-04-23T20:46:56Z

Dave:

== Introduction ==

PatternQuery (PQ) is a user friendly chemical language primarily designed for defining atom patterns in molecules. PQ combines the clarity and brevity of programming languages with the versatility of natural language, aiming for an efficient inclusion of chemical and biochemical knowledge into the definition of patterns. PQ allows definitions based on chemical connectivity and three-dimensional structure at the same time. Additionally, in the case of molecules based on residue chains (such as proteins, nucleic acids, saccharides, etc.), PQ allows the user to include any amount of information regarding the residue level structure directly into the definition of the patternss.

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

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

Some of the functions return '''<code>PatternSeq</code>''' while other return '''<code>Pattern</code>'''.
* '''<code>Pattern</code>''' is a set of atoms.
* '''<code>PatternSeq</code>''' is a sequence of '''<code>Pattern</code>''' (the sets of atoms).

When a molecule is queried, say using the expression <code>Rings(5 * ["C"] + ["O"])</code> a sequences of patterns each containing 6 atoms (5 C and 1 O) is returned. However, some functions such as <code>Filter</code> need to operate on a single pattern (the set of atoms) - not the whole sequences. The query <code>Filter(Residues(), lambda r: r.Count(Atoms()) > 10)</code> first finds all residue patterns ('''<code>PatternSeq</code>''') and then passes every single '''<code>Pattern</code>''' (set of atoms) to a function that counts the atoms in the pattern and returns True if there is at least 11 of them. This is the reasoning behind these two types.== Basic Query Functions ==
''Basic building blocks of the language - i.e. atoms, residues, and the like.''
=== AminoAcids ===
<code>AminoAcids() -> Residues</code> 
''Sequence of all residues with the 20 basic amino acid names.'' 
;Options
: ChargeType: String = "" - ''Specify type of the charge. Allowed values: Positive, Negative, Aromatic, Polar, NonPolar.''
;Examples
: <code>AminoAcids()</code>
:: ''All amino acids.''
: <code>AminoAcids(ChargeType = "Polar")</code>
:: ''Amino acids with polar charge.''
----
=== AtomIdRange ===
<code>AtomIdRange(minId: Integer, maxId: ?Integer) -> Atoms</code> 
''Sequence of atoms with minId <= atomId <= maxId.'' 
;Arguments
: minId: Integer - ''Minimum id.''
: maxId: ?Integer - ''Maximum id. If not specified, maxId = minId.''
;Examples
: <code>AtomIdRange(152, 161)</code>
:: ''Returns all atoms with id between 152 and 161 inclusive.''
----
=== AtomIds ===
<code>AtomIds(ids: Integer+) -> Atoms</code> 
''Sequence of atoms with specified identifiers.'' 
;Arguments
: ids: Integer+ - ''Identifiers.''
;Examples
: <code>AtomIds(1, 2, 3)</code>
:: ''Returns atoms with ids 1, 2, 3.''
----
=== AtomNames ===
<code>AtomNames(names: String+) -> Atoms</code> 
''Sequence of atoms with specified names.'' 
;Arguments
: names: String+ - ''Allowed names.''
;Examples
: <code>AtomNames("O1","NH1")</code>
:: ''Returns all atoms with names O1 or NH1.''
----
=== Atoms ===
<code>Atoms(symbols: String*) -> Atoms</code> 
''Sequence of atoms with specified element symbols. If no symbols are specified, yields all atoms one by one.'' 
;Arguments
: symbols: String* - ''Allowed element symbols.''
;Examples
: <code>Atoms("Zn","Ca")</code>
:: ''Returns all atoms with element symbol Zn or Ca''
----
=== Chains ===
<code>Chains(identifiers: Value*) -> PatternSeq</code> 
''Splits the structures into chains. If no identifiers are specified, all chains are returned.'' 
;Arguments
: identifiers: Value* - ''Chain identifiers.''
;Examples
: <code>Chains()</code>
:: ''Returns all chains.''
: <code>Chains("")</code>
:: ''Returns chains without specific identifier.''
: <code>Chains("A", "B")</code>
:: ''Returns chains A and B.''
----
=== Helices ===
<code>Helices() -> PatternSeq</code> 
''Returns all helices. This assumes the information about helices was present in the input structure.'' 
;Examples
: <code>Helices()</code>
:: ''Returns all helices.''
----
=== HetResidues ===
<code>HetResidues() -> Residues</code> 
''Sequence of all residues that contain HET atoms.'' 
;Options
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
;Examples
: <code>HetResidues()</code>
:: ''Returns all residues that contain HET atoms (ignores water).''
: <code>HetResidues(NoWaters=False)</code>
:: ''Returns all residues that contain HET atoms (includes water).''
----
=== ModifiedResidues ===
<code>ModifiedResidues(parentNames: String*) -> Residues</code> 
''Sequence of modified residues that originate from the specified name. If no names are specified, yields all modified residues one by one.'' 
;Arguments
: parentNames: String* - ''Parent residue names.''
;Examples
: <code>ModifiedResidues("MET")</code>
:: ''Returns all residues modified from MET (for example MSE).''
----
=== Named ===
<code>Named(patterns: PatternSeq) -> PatternSeq</code> 
'''Names' the pattern by its lowest atom id.'' 
;Arguments
: patterns: PatternSeq - ''Patterns to name.''
;Examples
: <code>Atoms("Zn").Named().AmbientAtoms(7)</code>
:: ''When exported, the result files will have names in the format '[parent id]_[pseudorandom number]_[zn atomid]'. If the Named function was not used, the name would be just '[parent id]_[pseudorandom number]'.''
----
=== NotAminoAcids ===
<code>NotAminoAcids() -> Residues</code> 
''Sequence of all residues that are not any of the 20 basic amino acids.'' 
;Options
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
;Examples
: <code>NotAminoAcids()</code>
:: ''Returns all residues that are not amino acids.''
----
=== NotAtomIds ===
<code>NotAtomIds(ids: Integer+) -> Atoms</code> 
''Sequence of atoms that do not have specified identifiers.'' 
;Arguments
: ids: Integer+ - ''Identifiers.''
;Examples
: <code>NotAtomIds(1, 2, 3)</code>
:: ''Returns atoms that do not have id 1, 2, nor 3.''
----
=== NotAtomNames ===
<code>NotAtomNames(names: String+) -> Atoms</code> 
''Sequence of atoms that do not have a specified name.'' 
;Arguments
: names: String+ - ''Forbidden names.''
;Examples
: <code>NotAtomNames("O4")</code>
:: ''Returns all atoms that are not called O4.''
----
=== NotAtoms ===
<code>NotAtoms(symbols: String+) -> Atoms</code> 
''Sequence of atoms that are not particular elements.'' 
;Arguments
: symbols: String+ - ''Forbidden element symbols.''
;Examples
: <code>NotAtoms("O")</code>
:: ''Returns all atoms that are not O.''
----
=== NotResidues ===
<code>NotResidues(names: Value+) -> Residues</code> 
''Sequence of residues that are not called by the specified names.'' 
;Arguments
: names: Value+ - ''Forbidden residue names.''
;Examples
: <code>NotResidues("THR","CYS")</code>
:: ''Returns all residues that are not THR or CYS.''
----
=== RegularMotifs ===
<code>RegularMotifs(regex: Value) -> PatternSeq</code> 
''Identifies regular motifs. The protein is split into individual chains and the residues are sorted by their Sequence Number before the motifs are identified. The query does not check if adjacent residues have consecutive Sequence Numbers. The query works in two modes: Amino and Nucleotide, on amino acids and nucleotides respectively. In the Amino mode, all the derivatives of standard residues are treated as the standard residues, as long as this information is properly annotated in MODRES or _pdbx_struct_mod_residue field. The default mode is 'Amino''' 
;Arguments
: regex: Value - ''Regular expression on one letter abbreviations of amino acids.''
;Options
: Type: String = "Amino" - ''Determines the type of the query. Allowed values: Amino, Nucleotide.''
;Examples
: <code>RegularMotifs("RGD")</code>
:: ''Finds all RGD motifs.''
: <code>RegularMotifs("ACGTU", Type = 'Nucleotide')</code>
:: ''Finds all consecutive occurrences of the ACGTU nucleotides.''
: <code>RegularMotifs(".HC.").Filter(lambda m: m.IsConnected())</code>
:: ''Finds all 4 residue motifs with ?-HIS-CYS-? that are connected.''
----
=== ResidueIdRange ===
<code>ResidueIdRange(chain: String, min: Integer, max: ?Integer) -> Residues</code> 
''Sequence of residues with specific chain and min <= sequence number <= max.'' 
;Arguments
: chain: String - ''Chain identifier. Case sensitive (a != A).''
: min: Integer - ''Minimum sequence number.''
: max: ?Integer - ''Maximum sequence number. If not specified, max = min.''
;Examples
: <code>ResidueIdRange("A", 161, 165)</code>
:: ''Returns all residues on chain A with seq. number between 161 and 165 inclusive.''
----
=== ResidueIds ===
<code>ResidueIds(ids: String+) -> Residues</code> 
''Sequence of residues with specific identifiers. If the structure does not contain a residue with the given identifier, it is skipped.'' 
;Arguments
: ids: String+ - ''One or more identifiers in the format 'NUMBER [CHAIN] [i:INSERTIONCODE]' (parameters in [] are optional, for example '175 i:12' or '143 B'). Case sensitive (a != A).''
;Examples
: <code>ResidueIds("132 A", "178 A")</code>
:: ''Returns residues A 123 and A 178 (provided the input structure contains them).''
----
=== Residues ===
<code>Residues(names: String*) -> Residues</code> 
''Sequence of residues with specified names. If no names are specified, yields all residues one by one.'' 
;Arguments
: names: String* - ''Allowed residue names.''
;Examples
: <code>Residues("HIS", "CYS")</code>
:: ''Returns all HIS or CYS residues.''
----
=== RingAtoms ===
<code>RingAtoms(atom: Atoms, ring: ?Rings) -> Atoms</code> 
''Returns all rings atoms.'' 
;Arguments
: atom: Atoms - ''Atom types.''
: ring: ?Rings - ''Specific ring.''
;Examples
: <code>RingAtoms(Atoms("C"), Rings(4 * ["C"] + ["O"]))</code>
:: ''Returns all C atoms on a ring with 4C and O.''
----
=== Rings ===
<code>Rings(atoms: Value*) -> Rings</code> 
''Sequence of rings with particular atoms. If no atoms are specified, yields all rings (cycles) one by one. The order of atoms matters.'' 
;Arguments
: atoms: Value* - ''Ring atoms.''
;Examples
: <code>Rings()</code>
:: ''Returns all rings.''
: <code>Rings(5 * ["C"] + ["O"])</code>
:: ''Returns all rings with 5C and 1O atoms.''
: <code>Rings(["C", "C", "N", "C", "N"])</code>
:: ''Returns all rings with C-C-N-C-N atoms.''
: <code>Or(Rings(["C", "C", "N", "C", "N"]), Rings(["C", "C", "C", "N", "N"]))</code>
:: ''Returns all rings with C-C-N-C-N or C-C-C-N-N atoms.''
----
=== Sheets ===
<code>Sheets() -> PatternSeq</code> 
''Returns all sheets. This assumes the information about sheets was present in the input structure.'' 
;Examples
: <code>Sheets()</code>
:: ''Returns all sheets.''
 
== Advanced Query Functions ==
''Advanced building blocks of the language.''
=== Flatten ===
<code>Flatten(patterns: PatternSeq, selector: Pattern->PatternSeq) -> PatternSeq</code> 
''Converts a sequence of sequence of patterns into a single 'flat' sequence.'' 
;Arguments
: patterns: PatternSeq - ''Patterns to project.''
: selector: Pattern->PatternSeq - ''The selector.''
;Examples
: <code>Residues("HIS").Flatten(lambda m: m.Find(Atoms("C")))</code>
:: ''Returns all C atoms on HIS residues.''
----
=== Inside ===
<code>Inside(patterns: PatternSeq, where: PatternSeq) -> PatternSeq</code> 
''Finds patterns within another pattern. Equivalent to where.Flatten(lambda m: m.Find(patterns))'' 
;Arguments
: patterns: PatternSeq - ''Patterns to find.''
: where: PatternSeq - ''Where to find them.''
;Examples
: <code>Atoms("C").Inside(Residues("HIS"))</code>
:: ''Returns all C atoms on HIS residues.''
----
=== Or ===
<code>Or(patterns: PatternSeq+) -> PatternSeq</code> 
''Merges several pattern sequences into one.'' 
;Arguments
: patterns: PatternSeq+ - ''Patterns to merge.''
;Examples
: <code>Or(Atoms("Zn").ConnectedResidues(1), Rings())</code>
:: ''Finds all zincs and their connected residues or rings.''
----
=== ToAtoms ===
<code>ToAtoms(patterns: PatternSeq) -> PatternSeq</code> 
''Collects all 'inner' patterns and yields all unique atoms one by one.'' 
;Arguments
: patterns: PatternSeq - ''Patterns to split.''
;Examples
: <code>Residues("HIS").ToAtoms()</code>
:: ''Returns all atoms on HIS residues one by one.''
----
=== ToResidues ===
<code>ToResidues(patterns: PatternSeq) -> PatternSeq</code> 
''Collects all 'inner' patterns and yields all unique residues one by one. The residues contain only the atoms that have been yielded by the inner query.'' 
;Arguments
: patterns: PatternSeq - ''Patterns to split.''
;Examples
: <code>Atoms("C").ToResidues()</code>
:: ''Returns all C atoms grouped by residues.''
----
=== Union ===
<code>Union(patterns: PatternSeq) -> PatternSeq</code> 
''Collects all 'inner' patterns and yields one created from their unique atoms.'' 
;Arguments
: patterns: PatternSeq - ''Patterns to merge.''
;Examples
: <code>Rings().Union()</code>
:: ''Creates a single pattern that contains all rings.''
 
== Filter Functions ==
''Functions useful for filtering patterns.''
=== Contains ===
<code>Contains(where: Pattern, what: PatternSeq) -> Bool</code> 
''Checks if a pattern is contained within another one. Equivalent to where.Count(what) > 0.'' 
;Arguments
: where: Pattern - ''Where to look.''
: what: PatternSeq - ''What to find.''
;Examples
: <code>HetResidues().Filter(lambda m: m.Contains(Rings(5*['C']+['O'])).Not())</code>
:: ''Returns all HET residues that do not contain a 5CO ring.''
----
=== Count ===
<code>Count(where: Pattern, what: PatternSeq) -> Integer</code> 
''Counts all occurrences of pattern 'what' in pattern 'where'.'' 
;Arguments
: where: Pattern - ''Where to count it.''
: what: PatternSeq - ''What pattern to count.''
;Examples
: <code>m.Count(Residues("HIS"))</code>
:: ''Returns the count of HIS residues in the pattern m. Where m is a Pattern (for example when using the Filter function or returned by the ToPattern() function). This example will not work directly and is here to illustrate a concept.''
: <code>Atoms("Zn").ConnectedResidues(1).Filter(lambda m: m.Count(Residues("HIS")) == 2)</code>
:: ''Patterns with Zn atoms and its connected residues with exactly 2 HIS residues.''
----
=== ExecuteIf ===
<code>ExecuteIf(query: PatternSeq, condition: Pattern->Bool) -> PatternSeq</code> 
''Executes a query only if the condition is met. Otherwise, return an empty sequence of patterns.'' 
;Arguments
: query: PatternSeq - ''Query to execute.''
: condition: Pattern->Bool - ''Condition that must be satisfied for the parent structure/pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.Resolution() <= 2.4)</code>
:: ''Returns residues in structures that have resolution lower than 2.4ang.''
: <code>AminoAcids().ExecuteIf(lambda p: p.Count(Atoms('Fe')) > 3)</code>
:: ''Returns all amino acids in structures that have at least 3 Fe atoms.''
----
=== Filter ===
<code>Filter(patterns: PatternSeq, filter: Pattern->Bool) -> PatternSeq</code> 
''Filters a sequence of patterns with a given predicate.'' 
;Arguments
: patterns: PatternSeq - ''Patterns to filter.''
: filter: Pattern->Bool - ''Filter predicate.''
;Examples
: <code>Residues().Filter(lambda m: m.Count(Atoms("C")) >= 3)</code>
:: ''Returns all residues that contain at least 3 C atoms.''
----
=== IsConnected ===
<code>IsConnected(pattern: Pattern) -> Bool</code> 
''Checks if a particular pattern is a connected graph.'' 
;Arguments
: pattern: Pattern - ''A pattern to test.''
;Examples
: <code>Atoms("Zn").AmbientResidues(3).Filter(lambda m: m.IsConnected())</code>
:: ''Finds all patterns with a Zn and residues within 3 ang, where all the ambient residues are connected to the central atom.''
----
=== IsConnectedTo ===
<code>IsConnectedTo(where: Pattern, patterns: PatternSeq) -> Bool</code> 
''Checks if a particular pattern is connected to any other specified pattern. The patterns must have empty intersection for this function to return true.'' 
;Arguments
: where: Pattern - ''A pattern to test.''
: patterns: PatternSeq - ''Pattern sequence to test against.''
;Examples
: <code>Atoms().Filter(lambda a: a.IsConnectedTo(Rings()))</code>
:: ''Finds all atoms that are connected to a ring they do not belong to.''
----
=== IsNotConnectedTo ===
<code>IsNotConnectedTo(what: Pattern, patterns: PatternSeq) -> Bool</code> 
''Checks if a particular pattern is not connected to any other specified pattern. The patterns must have empty intersection for this function to return true.'' 
;Arguments
: what: Pattern - ''A pattern to test.''
: patterns: PatternSeq - ''Pattern sequence to test against.''
;Examples
: <code>Residues().Filter(lambda r: r.IsNotConnectedTo(Atoms("Ca")))</code>
:: ''Finds all residues that are not connected to Ca atoms. The residue itself can still contain Ca atoms.''
----
=== NearestDistanceTo ===
<code>NearestDistanceTo(where: Pattern, patterns: PatternSeq) -> Real</code> 
''Finds the distance to a particular pattern.'' 
;Arguments
: where: Pattern - ''A pattern to test.''
: patterns: PatternSeq - ''Pattern sequence to test against.''
;Examples
: <code>Atoms().Filter(lambda m: m.NearestDistanceTo(Residues("ASP")) >= 5)</code>
:: ''Finds all atoms that are at least 5 (angstroms) away from any ASP residue.''
----
=== SeqCount ===
<code>SeqCount(what: PatternSeq) -> Integer</code> 
''Counts the length of a sequence of motifs.'' 
;Arguments
: what: PatternSeq - ''What pattern sequence to count.''
;Examples
: <code>Atoms("Zn").AmbientResidues(3).Filter(lambda m: m.Find(Residues("HIS")).SeqCount() > 1)</code>
:: ''Returns a sequence of patterns with Zn atom and residues within 3ang if the pattern contains at least 2 HIS residues.''
 
== Topology Functions ==
''Functions that rely on the topology of patterns.''
=== ConnectedAtoms ===
<code>ConnectedAtoms(pattern: PatternSeq, n: Integer) -> PatternSeq</code> 
''Surrounds the inner pattern by n layers of atoms.'' 
;Arguments
: pattern: PatternSeq - ''Basic pattern.''
: n: Integer - ''Number of atom layers to connect.''
;Options
: YieldNamedDuplicates: Bool = False - ''Yield duplicate patterns if they have a different name.''
;Examples
: <code>Residues("MAN").ConnectedAtoms(2)</code>
:: ''Finds all MAN residues and then adds two connected levels of atoms to them.''
----
=== ConnectedResidues ===
<code>ConnectedResidues(pattern: PatternSeq, n: Integer) -> PatternSeq</code> 
''Surrounds the inner pattern by n layers of residues.'' 
;Arguments
: pattern: PatternSeq - ''Basic pattern.''
: n: Integer - ''Number of residue layers to connect.''
;Options
: YieldNamedDuplicates: Bool = False - ''Yield duplicate patterns if they have a different name.''
;Examples
: <code>Atoms("Zn").ConnectedResidues(1)</code>
:: ''Finds all Zn atoms and adds all residues that are connected to them.''
----
=== Path ===
<code>Path(patterns: PatternSeq+) -> PatternSeq</code> 
''Creates a new pattern from 'connected' parts.'' 
;Arguments
: patterns: PatternSeq+ - ''Patterns to path.''
;Examples
: <code>Path(Atoms("O"), Atoms("C"), Atoms("O"))</code>
:: ''Finds patterns with two O and one C atoms where the C atoms is connected to the O ones.''
----
=== Star ===
<code>Star(center: PatternSeq, patterns: PatternSeq+) -> PatternSeq</code> 
''Creates a new pattern from a central one and connected parts.'' 
;Arguments
: center: PatternSeq - ''Center pattern.''
: patterns: PatternSeq+ - ''Patterns to chain.''
;Examples
: <code>Star(Atoms("C"), Atoms("O"), Atoms("O"))</code>
:: ''Finds patterns with two O atoms and one C atom in the center.''
: <code>Atoms("C").Star(Atoms("O"), Atoms("O"))</code>
:: ''Finds patterns with two O atoms and one C atom in the center.''
 
== Geometry Functions ==
''Functions that rely on the geometry of patterns.''
=== AmbientAtoms ===
<code>AmbientAtoms(pattern: PatternSeq, r: Number) -> PatternSeq</code> 
''Surrounds the inner pattern by atoms that within the given radius from the inner pattern.'' 
;Arguments
: pattern: PatternSeq - ''Basic pattern.''
: r: Number - ''Radius.''
;Options
: ExcludeBase: Bool = False - ''Exclude the central original pattern.''
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
: YieldNamedDuplicates: Bool = False - ''Yield duplicate patterns if they have a different name.''
;Examples
: <code>Atoms("Fe").AmbientAtoms(4)</code>
:: ''Finds Fe atoms and all atoms within 4 (angstroms) from each of them.''
----
=== AmbientResidues ===
<code>AmbientResidues(pattern: PatternSeq, r: Number) -> PatternSeq</code> 
''Surrounds the inner pattern by residues that have at least one atom within the given radius from the inner pattern.'' 
;Arguments
: pattern: PatternSeq - ''Basic pattern.''
: r: Number - ''Radius.''
;Options
: ExcludeBase: Bool = False - ''Exclude the central original pattern.''
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
: YieldNamedDuplicates: Bool = False - ''Yield duplicate patterns if they have a different name.''
;Examples
: <code>Rings(6 * ["C"]).AmbientResidues(4)</code>
:: ''Finds rings with 6C atoms and all residues within 4 (angstroms) from each of them.''
----
=== Cluster ===
<code>Cluster(r: Number, patterns: PatternSeq+) -> PatternSeq</code> 
''Clusters all patterns that are pairwise closer than r (angstroms).'' 
;Arguments
: r: Number - ''Maximum distance between two patterns in the cluster.''
: patterns: PatternSeq+ - ''Patterns to cluster.''
;Examples
: <code>Cluster(4, Atoms("Ca"), Rings(5 * ["C"] + ["O"]))</code>
:: ''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 ===
<code>Filled(pattern: PatternSeq) -> PatternSeq</code> 
''Adds all atoms that fall within the circumsphere (with radius multiplied by the factor) of the basic pattern.'' 
;Arguments
: pattern: PatternSeq - ''Basic pattern.''
;Options
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
: RadiusFactor: Number = 0.75 - ''Circumsphere radius factor.''
;Examples
: <code>Cluster(4, Residues("HIS")).Filled(RadiusFactor = 0.75)</code>
:: ''Finds clusters of HIS residues and all atoms within the circumsphere.''
----
=== Near ===
<code>Near(r: Number, patterns: PatternSeq+) -> PatternSeq</code> 
''Clusters all patterns that are pairwise closer than r (angstroms) and checks if the "counts" match.'' 
;Arguments
: r: Number - ''Maximum distance between two sub-patterns in the pattern.''
: patterns: PatternSeq+ - ''Patterns to 'cluster'.''
;Examples
: <code>Near(4, Atoms("Ca"), Atoms("Ca"), Rings(5 * ["C"] + ["O"]))</code>
:: ''Finds all instance of a single ring with 5C and O atoms and two Ca atoms that are closer than 4 (angstroms).''
 
== Meta-data Functions ==
''Functions dealing with meta-data about structures such as release date or authors.''
=== Authors ===
<code>Authors(pattern: Pattern) -> String</code> 
''Returns authors of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== ECNumbers ===
<code>ECNumbers(pattern: Pattern) -> String</code> 
''Returns Enzymatic Commission numbers assigned to enzymes in the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== EntitySources ===
<code>EntitySources(pattern: Pattern) -> String</code> 
''Returns entity sources of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== ExperimentMethod ===
<code>ExperimentMethod(pattern: Pattern) -> String</code> 
''Get the experiment method. The value is always an upper-case string. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ExperimentMethod() == "INFRARED SPECTROSCOPY")</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== HasAllAuthors ===
<code>HasAllAuthors(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given authors. The comparison is case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllAuthors("Holmes", "Watson"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllECNumbers ===
<code>HasAllECNumbers(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given Enzymatic Commission numbers. It is possible to enter just a number prefix without the '.'. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllECNumbers("3.2.1.18", "3.3"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllEntitySources ===
<code>HasAllEntitySources(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given entity sources. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllEntitySources("GMO", "Natural", "Synthetic"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllHostOrganismGenus ===
<code>HasAllHostOrganismGenus(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given host organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllHostOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllHostOrganismIds ===
<code>HasAllHostOrganismIds(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given host organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllHostOrganismIds("7108", "11244"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllHostOrganisms ===
<code>HasAllHostOrganisms(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given host organism names. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllHostOrganisms("Spodoptera frugiperda", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllKeywords ===
<code>HasAllKeywords(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given keywords. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllKeywords("membrane", "glycoprotein"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllOriginOrganismGenus ===
<code>HasAllOriginOrganismGenus(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given origin organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllOriginOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllOriginOrganismIds ===
<code>HasAllOriginOrganismIds(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given origin organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllOriginOrganismIds("121791", "10090"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllOriginOrganisms ===
<code>HasAllOriginOrganisms(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given origin organism names. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllOriginOrganisms("Nipah virus", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyAuthor ===
<code>HasAnyAuthor(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given authors. The comparison is case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyAuthor("Holmes", "Watson"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyECNumber ===
<code>HasAnyECNumber(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given Enzymatic Commission number. It is possible to enter just a number prefix without the '.'s. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyECNumber("3.2.1.19", "3.3"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyEntitySources ===
<code>HasAnyEntitySources(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given entity sources. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyEntitySources("GMO", "Natural", "Synthetic"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyHostOrganism ===
<code>HasAnyHostOrganism(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given host organism names. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyHostOrganism("Spodoptera frugiperda", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyHostOrganismGenus ===
<code>HasAnyHostOrganismGenus(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given host organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyHostOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyHostOrganismId ===
<code>HasAnyHostOrganismId(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given host organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyHostOrganismId("7108", "11244"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyKeyword ===
<code>HasAnyKeyword(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given keywords. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyKeyword("membrane", "glycoprotein"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyOriginOrganism ===
<code>HasAnyOriginOrganism(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given origin organism names. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyOriginOrganism("Nipah virus", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyOriginOrganismGenus ===
<code>HasAnyOriginOrganismGenus(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given origin organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyOriginOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyOriginOrganismId ===
<code>HasAnyOriginOrganismId(pattern: Pattern, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given origin organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyOriginOrganismId("121791", "10090"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HostOrganismGenus ===
<code>HostOrganismGenus(pattern: Pattern) -> String</code> 
''Returns host organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== HostOrganismIds ===
<code>HostOrganismIds(pattern: Pattern) -> String</code> 
''Returns host organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== HostOrganisms ===
<code>HostOrganisms(pattern: Pattern) -> String</code> 
''Returns host organism names of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== Keywords ===
<code>Keywords(pattern: Pattern) -> String</code> 
''Returns keywords of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== LatestRevisionDate ===
<code>LatestRevisionDate(pattern: Pattern) -> Value</code> 
''Get the latest revision date of the parent structure. The value has to be compared to the DateTime(year, month, day) object. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.LatestRevisionDate() >= DateTime(2008, 1, 1))</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== LatestRevisionYear ===
<code>LatestRevisionYear(pattern: Pattern) -> Integer</code> 
''Get the latest revision year of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.LatestRevisionYear() == 2006)</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== OriginOrganismGenus ===
<code>OriginOrganismGenus(pattern: Pattern) -> String</code> 
''Returns origin organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== OriginOrganismIds ===
<code>OriginOrganismIds(pattern: Pattern) -> String</code> 
''Returns origin organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== OriginOrganisms ===
<code>OriginOrganisms(pattern: Pattern) -> String</code> 
''Returns origin organism names of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== PolymerType ===
<code>PolymerType(pattern: Pattern) -> String</code> 
''Get the polymer type of the structure. Possible values are: NotAssigned, Protein, DNA, RNA, ProteinDNA, ProteinRNA, NucleicAcids, Mixture, Sugar, Other. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.PolymerType() == "ProteinDNA")</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== ProteinStoichiometry ===
<code>ProteinStoichiometry(pattern: Pattern) -> String</code> 
''Get the protein stoichiometry of the parent structure. Possible values are: NotAssigned, Monomer, Homomer, Heteromer. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ProteinStoichiometry() == "Heteromer")</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== ProteinStoichiometryString ===
<code>ProteinStoichiometryString(pattern: Pattern) -> String</code> 
''Get the protein stoichiometry string of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
----
=== ReleaseDate ===
<code>ReleaseDate(pattern: Pattern) -> Value</code> 
''Get the release date of the parent structure. The value has to be compared to the DateTime(year, month, day) object. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ReleaseDate() >= DateTime(2008, 1, 1))</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== ReleaseYear ===
<code>ReleaseYear(pattern: Pattern) -> Integer</code> 
''Get the release year of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ReleaseYear() == 2006)</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== Resolution ===
<code>Resolution(pattern: Pattern) -> Real</code> 
''Get the resolution in angstroms of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.Resolution() <= 2.4)</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== Weight ===
<code>Weight(pattern: Pattern) -> Real</code> 
''Get the weight of the molecule in kDa. If the value is not available, null is returned.'' 
;Arguments
: pattern: Pattern - ''Pattern.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.Weight() > 100000.0)</code>
:: ''Returns residues in structures that satisfy the property.''
 
== Miscellaneous Functions ==
''Various useful functions. These function often require a special setup (i.e. only useful in Scripting window or in specific applications).''
=== AminoSequenceString ===
<code>AminoSequenceString(pattern: Pattern) -> String</code> 
''Returns a string of single-letter amino acids contained in the pattern.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: pattern: Pattern - ''Pattern to convert.''
;Examples
: <code>Pattern("1tqn_12").AminoSequenceString()</code>
:: ''Returns a string representing amino acids in the pattern '1tqn_12'.''
: <code>RegularMotifs(Pattern("1tqn_12").AminoSequenceString())</code>
:: ''Returns all regular patterns that correspond to the AMK sequence in 1tqn_12.''
----
=== AtomProperty ===
<code>AtomProperty(atomPattern: Pattern, name: String) -> ?</code> 
''If the property exists and the pattern consists of a single atom, returns the property. Otherwise, returns Nothing.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: atomPattern: Pattern - ''Single atom pattern.''
: name: String - ''Property name.''
;Examples
: <code>a.AtomProperty("charge")</code>
:: ''Gets the 'charge' property of the atom a. Where a is a single atom Pattern. This example will not work directly.''
: <code>Atoms().Filter(lambda a: a.AtomProperty("charge") >= 2)</code>
:: ''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 ===
<code>AtomSimilarity(a: Pattern, b: Pattern) -> Real</code> 
''Computes Jaccard/Tanimoto coefficient on atoms (element symbols) of both structures.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: a: Pattern - ''First pattern.''
: b: Pattern - ''Second pattern.''
;Examples
: <code>AtomSimilarity(Current(),Pattern("1tqn_12"))</code>
:: ''Computes the atom similarity between the current pattern and 1tqn_12. This example can be used in SiteBinder to create a descriptor (assuming a structure with id '1tqn_12' is loaded).''
----
=== CommonAtoms ===
<code>CommonAtoms(modelId: String) -> PatternSeq</code> 
''Returns a single pattern with atoms common with the model. Properties checked: atom id, element symbol, chain, residue number. This query is useful for example for atom selection in SiteBinder.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: modelId: String - ''Id of the model.''
;Examples
: <code>CommonAtoms("1tqn_12")</code>
:: ''Returns a pattern formed by atoms common with the '1tqn_12' structure.''
----
=== CSA ===
<code>CSA() -> PatternSeq</code> 
''Entries from Catalytic Site Atlas represented as patterns. Works only if used from the command line version of Queries and property configured.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Examples
: <code>CSA()</code>
:: ''All CSA sites for the given structure. This example will only work if used from the command line version of Queries and property configured.''
----
=== Current ===
<code>Current() -> Pattern</code> 
''A variable that is assigned by the application environment.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Examples
: <code>AtomSimilarity(Current(), Pattern("model"))</code>
:: ''Returns the atom similarity of the current pattern 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 ===
<code>Descriptor(pattern: Pattern, name: String) -> ?</code> 
''Returns the descriptor. If the descriptor does not exist, 'null' is returned.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: pattern: Pattern - ''Pattern that represents entire structure.''
: name: String - ''Descriptor name.''
;Examples
: <code>Current().Descriptor("similarity") >= 0.75</code>
:: ''Returns True if 'similarity' descriptor of the current pattern is at least 0.75. This example will work for example in SiteBinder's structure selection if the 'similarity' descriptor has been previously defined.''
----
=== DynamicInvoke ===
<code>DynamicInvoke(value: Value, name: String, isProperty: Bool, args: Value) -> Value</code> 
''Dynamically invoke a member. (internal)'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: value: Value - ''InnerQuery.''
: name: String - ''Member name.''
: isProperty: Bool - ''Is this a property.''
: args: Value - ''Array of arguments.''
----
=== Find ===
<code>Find(source: Pattern, patterns: PatternSeq) -> PatternSeq</code> 
''Converts the source pattern to a structure and finds patterns within it.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: source: Pattern - ''Where to look.''
: patterns: PatternSeq - ''Patterns to find.''
;Examples
: <code>AtomSimilarity(Current().Find(NotAtoms("N")).ToPattern(), Pattern("model").Find(NotAtoms("N")).ToPattern())</code>
:: ''Computes the atom similarity of the 'current' and 'model' patterns, but ignores N atoms. This example can be used in SiteBinder to create a descriptor (assuming a structure with id 'model' is loaded).''
----
=== GroupedAtoms ===
<code>GroupedAtoms(symbols: String*) -> PatternSeq</code> 
''Groups atoms using the element symbol and then returns each group as a single pattern.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: symbols: String* - ''Allowed element symbols.''
;Examples
: <code>GroupedAtoms()</code>
:: ''Returns groups of all atom types. For example if the input has atoms 5xC-1xO, patterns with 5xC and 1xO atoms are returned.''
: <code>GroupedAtoms('C', 'O')</code>
:: ''Returns groups of all atom types. For example if the input has atoms 5xC-1xO-6xH, patterns with 5xC and 1xO atoms are returned (but the H atoms are ignored).''
----
=== Pattern ===
<code>Pattern(structureName: String) -> Pattern</code> 
''Returns a structure represented as a pattern.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: structureName: String - ''Name of a structure.''
;Examples
: <code>Pattern("1tqn_12")</code>
:: ''Returns the structure '1tqn_12' represented as a pattern. Usable in defining descriptors or in Scripting window (using MQ.Execute).''
----
=== ResidueSimilarity ===
<code>ResidueSimilarity(a: Pattern, b: Pattern) -> Real</code> 
''Computes Jaccard/Tanimoto coefficient on residue names of both structures.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: a: Pattern - ''First pattern.''
: b: Pattern - ''Second pattern.''
;Examples
: <code>ResidueSimilarity(Current(), Pattern("1tqn_12"))</code>
:: ''Computes the residue similarity between the current pattern and '1tqn_12'. This example can be used in SiteBinder to create a descriptor (assuming a structure with id '1tqn_12' is loaded).''
----
=== ToPattern ===
<code>ToPattern(patterns: PatternSeq) -> Pattern</code> 
''Converts a sequence of Patterns (AtomSetSeq) to a single Pattern by merging all atoms into a single atom set. The Pattern type is required by some function such as AtomSimilarity.'' 
''Note:'' This function cannot be used directly to query patterns from MotiveExplorer or Queries service. 
;Arguments
: patterns: PatternSeq - ''Patterns to convert.''
;Examples
: <code>Residues("HIS").ToPattern()</code>
:: ''Converts a sequence of HIS residue Patterns to a single Pattern.''
: <code>AtomSimilarity(Current().Find(NotAtoms("N")).ToPattern(), Pattern("model").Find(NotAtoms("N")).ToPattern())</code>
:: ''Computes the atom similarity of the 'current' and 'model' patterns, but ignores N atoms.''
 
== Value Functions ==
''Functions such as addition or comparison of numbers.''
=== Abs ===
<code>Abs(x: Number) -> Number</code> 
''Computes the 'Abs' function of the argument.'' 
;Arguments
: x: Number - ''Argument.''
;Examples
: <code>Abs(x)</code>
:: ''Evaluates the expression.''
----
=== Divide (/) ===
<code>Divide(x: Number, y: Number) -> Number</code> 
''Computes the 'Divide' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x / y</code>
:: ''Evaluates the expression.''
----
=== Equal (==) ===
<code>Equal(x: Value, y: Value) -> Bool</code> 
''Determines the 'Equal' relation between two values.'' 
;Arguments
: x: Value - ''Left argument.''
: y: Value - ''Right argument.''
;Examples
: <code>x == y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== Greater (>) ===
<code>Greater(x: Number, y: Number) -> Bool</code> 
''Determines the 'Greater' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x > y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== GreaterEqual (>=) ===
<code>GreaterEqual(x: Number, y: Number) -> Bool</code> 
''Determines the 'GreaterEqual' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x >= y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== Less (<) ===
<code>Less(x: Number, y: Number) -> Bool</code> 
''Determines the 'Less' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x < y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== LessEqual (<=) ===
<code>LessEqual(x: Number, y: Number) -> Bool</code> 
''Determines the 'LessEqual' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x <= y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== LogicalAnd (&) ===
<code>LogicalAnd(xs: Bool+) -> Bool</code> 
''Computes 'LogicalAnd' of the input values.'' 
;Arguments
: xs: Bool+ - ''Arguments.''
;Examples
: <code>x & y</code>
:: ''Evaluates to True or False based on the values of x and y.''
----
=== LogicalNot (Not) ===
<code>LogicalNot(x: Bool) -> Bool</code> 
''Computes 'LogicalNot' of the input value. This function can be called using the shorthand 'Not'.'' 
;Arguments
: x: Bool - ''Argument.''
;Examples
: <code>LogicalNot(x)</code>
:: ''Evaluates to True or False based on the value of x.''
: <code>x.Not()</code>
:: ''Evaluates to True or False based on the value of x.''
----
=== LogicalOr (|) ===
<code>LogicalOr(xs: Bool+) -> Bool</code> 
''Computes 'LogicalOr' of the input values.'' 
;Arguments
: xs: Bool+ - ''Arguments.''
;Examples
: <code>x | y</code>
:: ''Evaluates to True or False based on the values of x and y.''
----
=== LogicalXor (Xor) ===
<code>LogicalXor(xs: Bool+) -> Bool</code> 
''Computes 'LogicalXor' of the input values. This function can be called using the shorthand 'Xor'.'' 
;Arguments
: xs: Bool+ - ''Arguments.''
;Examples
: <code>LogicalXor(x, y)</code>
:: ''Evaluates to True or False based on the values of x and y.''
: <code>Xor(x, y)</code>
:: ''Evaluates to True or False based on the values of x and y.''
----
=== Minus (-) ===
<code>Minus(x: Number) -> Number</code> 
''Computes the arithmetic negation of the argument.'' 
;Arguments
: x: Number - ''Argument.''
;Examples
: <code>-x</code>
:: ''Arithmetic negation of x.''
----
=== NotEqual (!=) ===
<code>NotEqual(x: Value, y: Value) -> Bool</code> 
''Determines the 'NotEqual' relation between two values.'' 
;Arguments
: x: Value - ''Left argument.''
: y: Value - ''Right argument.''
;Examples
: <code>x != y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== Plus (+) ===
<code>Plus(x: Number, y: Number) -> Number</code> 
''Computes the 'Plus' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x + y</code>
:: ''Evaluates the expression.''
----
=== Power (^) ===
<code>Power(x: Number, y: Number) -> Number</code> 
''Computes the 'Power' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x ^ y</code>
:: ''Evaluates the expression.''
----
=== Subtract (-) ===
<code>Subtract(x: Number, y: Number) -> Number</code> 
''Computes the 'Subtract' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x - y</code>
:: ''Evaluates the expression.''
----
=== Times (*) ===
<code>Times(x: Number, y: Number) -> Number</code> 
''Computes the 'Times' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x * y</code>
:: ''Evaluates the expression.''

PatternQuery:Command Line

2015-04-23T20:34:37Z

Dave: /* MotiveQuery Specific Structure */

This is help for version 1.0.15.4.22 or newer. The help text for other versions can be viewed using the ''--help'' command when running the application.

=Technical details=
===Where to find PatternQuery===
'''PatternQuery''' is freely available online since May 2014 at http://ncbr.muni.cz/PatternQuery. There is no login requirement for accessing '''PatternQuery'''.

===What you need in order to run PatternQuery===
* Up to date internet browser with WebGL support.
* JavaScript enabled.

Check if your browser is [http://get.webgl.org WebGL] and [http://www.enable-javascript.com/ Javascript] compliant.

Note that you can run '''PatternQuery''' and download the results even if your browser doesn't support WebGL.
WebGL is only necessary for the 3D visualization functionality.

In some older browsers, the interactive user guide which provides help for the GUI interface does not work optimally.

= Running the Offline Service =
-----------------------
Just download the latest release of [http://webchem.ncbr.muni.cz/Platform/PatternQuery/DownloadService PatternQuery application]. The service can be executed using the command (latest .NET Framework required):
<pre>WebChemistry.Queries.Service.exe workingFolder configuration.json</pre>
In Linux (where available) and MacOS, the latest version the Mono Framework (http://mono-project.com/) must be used to run the application:
<pre>mono WebChemistry.Queries.Service.exe workingFolder configuration.json</pre>

== Configuration ==
The configuration is specified using the JSON format.

=== Configuration Example ===
This is the general shape of the JSON input configuration.
<pre>{
"InputFolders": [
"c:\\TestData\\PDB\\SampleSet1"
],
"Queries": [
{
"Id": "NAGs",
"QueryString": "Residues(\"NAG\")"
},
{
"Id": "MANs",
"QueryString": "Residues('MAN')"
}
],
"StatisticsOnly": false,
"CSAPath": "c:\\data\\csa.dat",
"MaxParallelism": 8
}</pre>

There has to be exactly one configuration file for each validation run. Every value, as well as settings' names, is surrounded in quotation marks (" " or ' '). Backslashes (\) have to be escaped (\\). File system paths can be absolute as well as relative (/ works as well in paths).

=== Attributes ===
* '''InputFolders''' [ String[] ]
: ''A list of folders containing the input structures.''

* '''Queries''' [ [[#QueryInfo_details|QueryInfo]] ]
: ''A list of queries.''

* '''StatisticsOnly''' [ Boolean ]
: ''If `true`, the files with fragments are not exported.''

* '''CSAPath''' [ String ]
: ''Optional path to a file with CSA database that allows the CSA() query to work. The file is a CSV file that must contain the columns `PdbID, SiteNumber, ResidueName, ChainId, ResidueNumber, ...`''

* '''MaxParallelism''' [ Int32 ], Default value = 8
: ''The maximum number of structures that can be processed simultaneously.''

=== Descriptions ===
===== QueryInfo =====
* '''Id''' [ String ]
: ''A unique identifier of the query.''

* '''QueryString''' [ String ]
: ''The query expression.''

== Output Description ==

=== General Structure ===
* '''[WorkingDirectory]''' - ''Working directory of the application.''
:* '''result''' - ''Contains the result of the computation.''
:: '''log.txt''' - ''Contains the console output of the application.''
:: '''status.json''' - ''Contains general information of the computation (running time, version, etc.).''

=== MotiveQuery Specific Structure ===
* '''result''' - ''Folder with computation result''
:* '''query_id''' - ''Folder for each query named by its unique id.''
::* '''patterns''' - ''Folder with patterns stored in PDB format.''
:::: '''data.json''' - ''Information about the result in JSON format.''
:::: '''patterns.csv''' - ''Information about the patterns in CSV format.''
:::: '''metadata_summary.csv''' - ''Information about the metadata (origin organism, EC number, etc.) in CSV format.''
:::: '''structures.csv''' - ''Information about structures that contain the given patterns in CSV format.''
:: '''structures.csv''' - ''Information about all structures that were queried in CSV format.''
:: '''structures.json''' - ''Information about all structures that were queried in JSON format.''
:: '''summary.json''' - ''Summary information (number of found patterns, etc.) about the computation in JSON format.''

PatternQuery:Command Line

2015-04-23T20:34:10Z

Dave: /* What you need in order to run MotiveQuery */

This is help for version 1.0.15.4.22 or newer. The help text for other versions can be viewed using the ''--help'' command when running the application.

=Technical details=
===Where to find PatternQuery===
'''PatternQuery''' is freely available online since May 2014 at http://ncbr.muni.cz/PatternQuery. There is no login requirement for accessing '''PatternQuery'''.

===What you need in order to run PatternQuery===
* Up to date internet browser with WebGL support.
* JavaScript enabled.

Check if your browser is [http://get.webgl.org WebGL] and [http://www.enable-javascript.com/ Javascript] compliant.

Note that you can run '''PatternQuery''' and download the results even if your browser doesn't support WebGL.
WebGL is only necessary for the 3D visualization functionality.

In some older browsers, the interactive user guide which provides help for the GUI interface does not work optimally.

= Running the Offline Service =
-----------------------
Just download the latest release of [http://webchem.ncbr.muni.cz/Platform/PatternQuery/DownloadService PatternQuery application]. The service can be executed using the command (latest .NET Framework required):
<pre>WebChemistry.Queries.Service.exe workingFolder configuration.json</pre>
In Linux (where available) and MacOS, the latest version the Mono Framework (http://mono-project.com/) must be used to run the application:
<pre>mono WebChemistry.Queries.Service.exe workingFolder configuration.json</pre>

== Configuration ==
The configuration is specified using the JSON format.

=== Configuration Example ===
This is the general shape of the JSON input configuration.
<pre>{
"InputFolders": [
"c:\\TestData\\PDB\\SampleSet1"
],
"Queries": [
{
"Id": "NAGs",
"QueryString": "Residues(\"NAG\")"
},
{
"Id": "MANs",
"QueryString": "Residues('MAN')"
}
],
"StatisticsOnly": false,
"CSAPath": "c:\\data\\csa.dat",
"MaxParallelism": 8
}</pre>

There has to be exactly one configuration file for each validation run. Every value, as well as settings' names, is surrounded in quotation marks (" " or ' '). Backslashes (\) have to be escaped (\\). File system paths can be absolute as well as relative (/ works as well in paths).

=== Attributes ===
* '''InputFolders''' [ String[] ]
: ''A list of folders containing the input structures.''

* '''Queries''' [ [[#QueryInfo_details|QueryInfo]] ]
: ''A list of queries.''

* '''StatisticsOnly''' [ Boolean ]
: ''If `true`, the files with fragments are not exported.''

* '''CSAPath''' [ String ]
: ''Optional path to a file with CSA database that allows the CSA() query to work. The file is a CSV file that must contain the columns `PdbID, SiteNumber, ResidueName, ChainId, ResidueNumber, ...`''

* '''MaxParallelism''' [ Int32 ], Default value = 8
: ''The maximum number of structures that can be processed simultaneously.''

=== Descriptions ===
===== QueryInfo =====
* '''Id''' [ String ]
: ''A unique identifier of the query.''

* '''QueryString''' [ String ]
: ''The query expression.''

== Output Description ==

=== General Structure ===
* '''[WorkingDirectory]''' - ''Working directory of the application.''
:* '''result''' - ''Contains the result of the computation.''
:: '''log.txt''' - ''Contains the console output of the application.''
:: '''status.json''' - ''Contains general information of the computation (running time, version, etc.).''

=== MotiveQuery Specific Structure ===
* '''result''' - ''Folder with computation result''
:* '''query_id''' - ''Folder for each query named by its unique id.''
::* '''patterns''' - ''Folder with patterns stored in PDB format.''
:::: '''data.json''' - ''Information about the result in JSON format.''
:::: '''patterns.csv''' - ''Information about the patterns in CSV format.''
:::: '''metadata_summary.csv''' - ''Information about the metadata (origin organism, EC number, etc.) in CSV format.''
:::: '''structures.csv''' - ''Information about structures that contain the given fragments in CSV format.''
:: '''structures.csv''' - ''Information about all structures that were queried in CSV format.''
:: '''structures.json''' - ''Information about all structures that were queried in JSON format.''
:: '''summary.json''' - ''Summary information (number of found patterns, etc.) about the computation in JSON format.''

PatternQuery:Command Line

2015-04-23T20:33:58Z

Dave: /* Where to find MotiveQuery */

This is help for version 1.0.15.4.22 or newer. The help text for other versions can be viewed using the ''--help'' command when running the application.

=Technical details=
===Where to find PatternQuery===
'''PatternQuery''' is freely available online since May 2014 at http://ncbr.muni.cz/PatternQuery. There is no login requirement for accessing '''PatternQuery'''.

===What you need in order to run MotiveQuery===
* Up to date internet browser with WebGL support.
* JavaScript enabled.

Check if your browser is [http://get.webgl.org WebGL] and [http://www.enable-javascript.com/ Javascript] compliant.

Note that you can run '''PatternQuery''' and download the results even if your browser doesn't support WebGL.
WebGL is only necessary for the 3D visualization functionality.

In some older browsers, the interactive user guide which provides help for the GUI interface does not work optimally.

= Running the Offline Service =
-----------------------
Just download the latest release of [http://webchem.ncbr.muni.cz/Platform/PatternQuery/DownloadService PatternQuery application]. The service can be executed using the command (latest .NET Framework required):
<pre>WebChemistry.Queries.Service.exe workingFolder configuration.json</pre>
In Linux (where available) and MacOS, the latest version the Mono Framework (http://mono-project.com/) must be used to run the application:
<pre>mono WebChemistry.Queries.Service.exe workingFolder configuration.json</pre>

== Configuration ==
The configuration is specified using the JSON format.

=== Configuration Example ===
This is the general shape of the JSON input configuration.
<pre>{
"InputFolders": [
"c:\\TestData\\PDB\\SampleSet1"
],
"Queries": [
{
"Id": "NAGs",
"QueryString": "Residues(\"NAG\")"
},
{
"Id": "MANs",
"QueryString": "Residues('MAN')"
}
],
"StatisticsOnly": false,
"CSAPath": "c:\\data\\csa.dat",
"MaxParallelism": 8
}</pre>

There has to be exactly one configuration file for each validation run. Every value, as well as settings' names, is surrounded in quotation marks (" " or ' '). Backslashes (\) have to be escaped (\\). File system paths can be absolute as well as relative (/ works as well in paths).

=== Attributes ===
* '''InputFolders''' [ String[] ]
: ''A list of folders containing the input structures.''

* '''Queries''' [ [[#QueryInfo_details|QueryInfo]] ]
: ''A list of queries.''

* '''StatisticsOnly''' [ Boolean ]
: ''If `true`, the files with fragments are not exported.''

* '''CSAPath''' [ String ]
: ''Optional path to a file with CSA database that allows the CSA() query to work. The file is a CSV file that must contain the columns `PdbID, SiteNumber, ResidueName, ChainId, ResidueNumber, ...`''

* '''MaxParallelism''' [ Int32 ], Default value = 8
: ''The maximum number of structures that can be processed simultaneously.''

=== Descriptions ===
===== QueryInfo =====
* '''Id''' [ String ]
: ''A unique identifier of the query.''

* '''QueryString''' [ String ]
: ''The query expression.''

== Output Description ==

=== General Structure ===
* '''[WorkingDirectory]''' - ''Working directory of the application.''
:* '''result''' - ''Contains the result of the computation.''
:: '''log.txt''' - ''Contains the console output of the application.''
:: '''status.json''' - ''Contains general information of the computation (running time, version, etc.).''

=== MotiveQuery Specific Structure ===
* '''result''' - ''Folder with computation result''
:* '''query_id''' - ''Folder for each query named by its unique id.''
::* '''patterns''' - ''Folder with patterns stored in PDB format.''
:::: '''data.json''' - ''Information about the result in JSON format.''
:::: '''patterns.csv''' - ''Information about the patterns in CSV format.''
:::: '''metadata_summary.csv''' - ''Information about the metadata (origin organism, EC number, etc.) in CSV format.''
:::: '''structures.csv''' - ''Information about structures that contain the given fragments in CSV format.''
:: '''structures.csv''' - ''Information about all structures that were queried in CSV format.''
:: '''structures.json''' - ''Information about all structures that were queried in JSON format.''
:: '''summary.json''' - ''Summary information (number of found patterns, etc.) about the computation in JSON format.''

PatternQuery:Command Line

2015-04-23T20:33:41Z

Dave:

This is help for version 1.0.15.4.22 or newer. The help text for other versions can be viewed using the ''--help'' command when running the application.

=Technical details=
===Where to find MotiveQuery===
'''PatternQuery''' is freely available online since May 2014 at http://ncbr.muni.cz/PatternQuery. There is no login requirement for accessing '''PatternQuery'''.

===What you need in order to run MotiveQuery===
* Up to date internet browser with WebGL support.
* JavaScript enabled.

Check if your browser is [http://get.webgl.org WebGL] and [http://www.enable-javascript.com/ Javascript] compliant.

Note that you can run '''PatternQuery''' and download the results even if your browser doesn't support WebGL.
WebGL is only necessary for the 3D visualization functionality.

In some older browsers, the interactive user guide which provides help for the GUI interface does not work optimally.

= Running the Offline Service =
-----------------------
Just download the latest release of [http://webchem.ncbr.muni.cz/Platform/PatternQuery/DownloadService PatternQuery application]. The service can be executed using the command (latest .NET Framework required):
<pre>WebChemistry.Queries.Service.exe workingFolder configuration.json</pre>
In Linux (where available) and MacOS, the latest version the Mono Framework (http://mono-project.com/) must be used to run the application:
<pre>mono WebChemistry.Queries.Service.exe workingFolder configuration.json</pre>

== Configuration ==
The configuration is specified using the JSON format.

=== Configuration Example ===
This is the general shape of the JSON input configuration.
<pre>{
"InputFolders": [
"c:\\TestData\\PDB\\SampleSet1"
],
"Queries": [
{
"Id": "NAGs",
"QueryString": "Residues(\"NAG\")"
},
{
"Id": "MANs",
"QueryString": "Residues('MAN')"
}
],
"StatisticsOnly": false,
"CSAPath": "c:\\data\\csa.dat",
"MaxParallelism": 8
}</pre>

There has to be exactly one configuration file for each validation run. Every value, as well as settings' names, is surrounded in quotation marks (" " or ' '). Backslashes (\) have to be escaped (\\). File system paths can be absolute as well as relative (/ works as well in paths).

=== Attributes ===
* '''InputFolders''' [ String[] ]
: ''A list of folders containing the input structures.''

* '''Queries''' [ [[#QueryInfo_details|QueryInfo]] ]
: ''A list of queries.''

* '''StatisticsOnly''' [ Boolean ]
: ''If `true`, the files with fragments are not exported.''

* '''CSAPath''' [ String ]
: ''Optional path to a file with CSA database that allows the CSA() query to work. The file is a CSV file that must contain the columns `PdbID, SiteNumber, ResidueName, ChainId, ResidueNumber, ...`''

* '''MaxParallelism''' [ Int32 ], Default value = 8
: ''The maximum number of structures that can be processed simultaneously.''

=== Descriptions ===
===== QueryInfo =====
* '''Id''' [ String ]
: ''A unique identifier of the query.''

* '''QueryString''' [ String ]
: ''The query expression.''

== Output Description ==

=== General Structure ===
* '''[WorkingDirectory]''' - ''Working directory of the application.''
:* '''result''' - ''Contains the result of the computation.''
:: '''log.txt''' - ''Contains the console output of the application.''
:: '''status.json''' - ''Contains general information of the computation (running time, version, etc.).''

=== MotiveQuery Specific Structure ===
* '''result''' - ''Folder with computation result''
:* '''query_id''' - ''Folder for each query named by its unique id.''
::* '''patterns''' - ''Folder with patterns stored in PDB format.''
:::: '''data.json''' - ''Information about the result in JSON format.''
:::: '''patterns.csv''' - ''Information about the patterns in CSV format.''
:::: '''metadata_summary.csv''' - ''Information about the metadata (origin organism, EC number, etc.) in CSV format.''
:::: '''structures.csv''' - ''Information about structures that contain the given fragments in CSV format.''
:: '''structures.csv''' - ''Information about all structures that were queried in CSV format.''
:: '''structures.json''' - ''Information about all structures that were queried in JSON format.''
:: '''summary.json''' - ''Summary information (number of found patterns, etc.) about the computation in JSON format.''

PatternQuery:Principles

2015-02-24T10:38:20Z

Dave: /* A More Formal Description */

'''A new paradigm for describing structural fragments in molecules'''

This text describes the basic principles of the '''MotiveQuery''' language for describing structural fragments in molecules. First, the text puts two approaches for identifying molecular fragments in contrast: the imperative approach, and the declarative one, taken by the '''MotiveQuery''' language. Next, basic principles of the language are illustrated on several examples and later described in a more formal way. Finally, the original example is revisited and explained in the terms of the newly introduced concepts.

==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>[[MotiveQuery: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 fragment becomes simply:

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

==Basic Principles of the Language==

===Intuitive Description===

As we've seen in the example above, it is very easy to ''compose'' our ideas about the final shape of the fragment we are interested in. The way this works is that the input molecule is decomposed into a stream of fragments. These streams can then be modified and combined into new streams, which can be modified and combined again.

As an example, take the query <code>Atoms('Ca')</code>. What the '''MotiveQuery''' language does is to extract all calcium atoms from the input molecule and represent them as a stream of sets containing one atom each as illustrated on the image below:

[[Image:MotiveQuery-Principles Atoms(Ca).png|center|600px]]

Now, each element of this stream can be modified, for example to include all atoms 4A within the original calcium atom. Now we have a stream of sets of atoms, where each set contains the original Ca atom and the atoms within the given radius. This would be represented by the query <code>Atoms('Ca').AmbientAtoms(4)</code> and is illustrated on the image bellow:

[[Image:MotiveQuery-Principles Atoms(Ca) surr.png|center|600px]]

In the next step, we might wish to keep only these fragments that contain at least 6 atoms. This is achieved by looking at each fragment, counting the number of atoms and throwing away these fragments that do not meet the criteria. Written as a query, this could be represented as <code>Atoms('Ca').AmbientAtoms(4).Filter(lambda m: m.Count(Atoms()) >= 6)</code>. In the graphical form:

[[Image:MotiveQuery-Principles Atoms(Ca) surr filt.png|center|600px]]

The previous filter query also demonstrates another interesting concept of the language: the ability to identify fragments within fragments, which is what the expression <code>m.Count(Atoms())</code> does - the <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> query is executed for each fragment from the original input sequence provided by the expression <code>Atoms('Ca').AmbientAtoms(4)</code>, and creates a new sequence of fragments that each contain a single atom. Then the Count function takes over and returns the number of fragments produced by its argument. In this way, the query <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> inside the Count function can be replaced by any function that also produces a sequence of fragments, for example <code>[[MotiveQuery:Language_Reference#Rings | Rings()]]</code>.

Finally, streams of fragments can be combined. For example, let’s say we want to find all pairs of calcium atoms that are no further than 4A within each other. This can be achieved using the query <code>Near(4, Atoms('Ca'), Atoms('Ca'))</code>. So this query takes as the input two identical streams of calcium atoms and for each pair of them determines if the atoms are closer than 4A to each other. For each pair that satisfies this condition, a new fragment from the 2 atoms is created. Therefore, the result of the above <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code> query is a stream of sets of atoms (fragments) that each contain two calcium atoms that are no further than 4A from each other:

[[Image:Near.png|center|600px]]

With these basic types of queries outlined in the previous paragraphs, the sky's the limit. Due to the composable nature of the language if a new type of motif emerges, only a single function needs to be added to the language for it to work with all its other parts. As an example, assume we didn’t know that proteins had secondary structure called “sheet” and we just discovered it and a fancy algorithm to identify these "sheets". Now we would be interested in how this new type of protein substructure interacts with other parts of the molecule. All that would be needed is to add a function called <code>[[MotiveQuery:Language_Reference#Sheets | Sheets()]]</code> to the language and immediately we would be able to analyze and filter it’s neighborhood using the functions <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code> and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.

===A More Formal Description===
There are two basic data structures that the language is built upon. These are:
* '''Fragment'''. A fragment is simply an arbitrary set of atoms.
* '''Fragment Sequence'''. A sequence of fragments. In mathematical terms, can be understood as a "set of fragments" which is another way of saying "set of sets of atoms".

And on these data structures, there are three basic types of queries:
* '''Generator queries'''. Generator queries, as the name suggests, generate sequences of fragments from the original input. They are the tool that transforms the input molecule into a stream of fragments that can be later modified or combined. Examples of these queries include <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code>, <code>[[MotiveQuery:Language_Reference#Residues | Residues()]]</code>, and <code>[[MotiveQuery:Language_Reference#RegularMotifs | RegularMotifs()]]</code>.
* '''Modifier queries'''. These queries operate on individual fragments and modify them or throw them away. Examples include <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code>, <code>[[MotiveQuery:Language_Reference#ConnectedResidues | ConnectedResidues()]]</code>, and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.
* '''Combinator queries'''. Combinatorial queries take as input two or more sequence of fragments and combine them into a single new sequence that satisfies given criteria. Examples include <code>[[MotiveQuery:Language_Reference#Or | Or()]]</code>, <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code>, and <code>[[MotiveQuery:Language_Reference#Path | Path()]]</code>.

==Example, Revised==
Now that we know the basic building blocks of the language, let’s go back to our original example and analyze it:

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

This corresponds to the following process.

# A generator query <code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code> is executed that produces a sequence of fragments that are composed of atoms corresponding to HET residues.
# Next, the original sequence is modified by adding atoms within 3 angstrom from any original atom to each fragment.
# Finally, each fragment in the modified sequence is examined: all “calcium atom fragments” are identified and counted. Only these fragments that contain at least 1 Ca atom are kept.

Graphically:

<code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code>
[[Image:MotiveQuery-Principles-HetResidues.png|none|500px]]

<code>[[MotiveQuery:Language_Reference#AmbientAtoms | .AmbientAtoms(3)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms.png|none|500px]]

<code>[[MotiveQuery:Language_Reference#Filter | .Filter(lambda l: l.Count(Atoms('Ca')) > 0)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms-filter.png|none|500px]]

PatternQuery:Language Reference

2015-01-07T21:35:02Z

Dave: /* RegularMotifs */

== Introduction ==

MotiveQuery (MQ) is a user friendly chemical language primarily designed for defining structural fragments. MQ combines the clarity and brevity of programming languages with the versatility of natural language, aiming for an efficient inclusion of chemical and biochemical knowledge into the definition of structural fragments. MQ allows definitions based on chemical connectivity and three-dimensional structure at the same time. Additionally, in the case of molecules based on residue chains (such as proteins, nucleic acids, saccharides, etc.), MQ allows the user to include any amount of information regarding the residue level structure directly into the definition of the fragments.

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 '''<code>FragmentSeq</code>''' while other return '''<code>Fragment</code>'''.
* '''<code>Fragment</code>''' is a set of atoms.
* '''<code>FragmentSeq</code>''' is a sequence of '''<code>Fragment</code>''' (the sets of atoms).

When a molecule is queried, say using the expression <code>Rings(5 * ["C"] + ["O"])</code> a sequences of fragments each containing 6 atoms (5 C and 1 O) is returned. However, some functions such as <code>Filter</code> need to operate on a single fragment (the set of atoms) - not the whole sequences. The query <code>Filter(Residues(), lambda r: r.Count(Atoms()) > 10)</code> first finds all residue '''<code>Fragments</code>''' (sequence) and then passes every single '''<code>Fragment</code>''' (set of atoms) to a function that counts the atoms in the fragment 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 <code>MQ.Execute</code> 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.

<pre>q = Atoms("Zn").ConnectedAtoms(2)
MQ.Execute(q)</pre>
: ''This command finds all fragments specified by the query q in all loaded structures.''

<pre>MQ.Execute(Residues("HEM"), [ Session.StructureMap["1tqn"], Session.StructureMap["2wer"] ])</pre>
: ''This command finds all HEM residues in structures 1tqn and 2wer (provided structures with these names are loaded).''

<pre>q = AtomSimilarity(Fragment("model"), Fragment("1gtz_0"))
MQ.Execute(q)</pre>
: ''This command computes the atom similarity (Jaccard coefficient) for structures model and 1gtz_0.''

<pre>q = ResidueSimilarity(Fragment("model"), Current())
MQ.Execute(q, Session.Structures)</pre>
: ''This command computes the residue similarity (Jaccard coefficient) for the structure with id 'model' (which is loaded using the Fragment 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 ===
<code>AminoAcids() -> Residues</code> 
''Sequence of all residues with the 20 basic amino acid names.'' 
;Options
: ChargeType: String = "" - ''Specify type of the charge. Allowed values: Positive, Negative, Aromatic, Polar, NonPolar.''
;Examples
: <code>AminoAcids()</code>
:: ''All amino acids.''
: <code>AminoAcids(ChargeType = "Polar")</code>
:: ''Amino acids with polar charge.''
----
=== AtomIdRange ===
<code>AtomIdRange(minId: Integer, maxId: ?Integer) -> Atoms</code> 
''Sequence of atoms with minId <= atomId <= maxId.'' 
;Arguments
: minId: Integer - ''Minimum id.''
: maxId: ?Integer - ''Maximum id. If not specified, maxId = minId.''
;Examples
: <code>AtomIdRange(152, 161)</code>
:: ''Returns all atoms with id between 152 and 161 inclusive.''
----
=== AtomIds ===
<code>AtomIds(ids: Integer+) -> Atoms</code> 
''Sequence of atoms with specified identifiers.'' 
;Arguments
: ids: Integer+ - ''Identifiers.''
;Examples
: <code>AtomIds(1, 2, 3)</code>
:: ''Returns atoms with ids 1, 2, 3.''
----
=== AtomNames ===
<code>AtomNames(names: String+) -> Atoms</code> 
''Sequence of atoms with specified names.'' 
;Arguments
: names: String+ - ''Allowed names.''
;Examples
: <code>AtomNames("O1","NH1")</code>
:: ''Returns all atoms with names O1 or NH1.''
----
=== Atoms ===
<code>Atoms(symbols: String*) -> Atoms</code> 
''Sequence of atoms with specified element symbols. If no symbols are specified, yields all atoms one by one.'' 
;Arguments
: symbols: String* - ''Allowed element symbols.''
;Examples
: <code>Atoms("Zn","Ca")</code>
:: ''Returns all atoms with element symbol Zn or Ca''
----
=== Helices ===
<code>Helices() -> FragmentSeq</code> 
''Returns all helices. This assumes the information about helices was present in the input structure.'' 
;Examples
: <code>Helices()</code>
:: ''Returns all helices.''
----
=== HetResidues ===
<code>HetResidues() -> Residues</code> 
''Sequence of all residues that contain HET atoms.'' 
;Options
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
;Examples
: <code>HetResidues()</code>
:: ''Returns all residues that contain HET atoms (ignores water).''
: <code>HetResidues(NoWaters=False)</code>
:: ''Returns all residues that contain HET atoms (includes water).''
----
=== Chains ===
<code>Chains(identifiers: Value*) -> FragmentSeq</code> 
''Splits the structures into chains. If no identifiers are specified, all chains are returned.'' 
;Arguments
: identifiers: Value* - ''Chain identifiers.''
;Examples
: <code>Chains()</code>
:: ''Returns all chains.''
: <code>Chains("")</code>
:: ''Returns chains without specific identifier.''
: <code>Chains("A", "B")</code>
:: ''Returns chains A and B.''
----
=== Named ===
<code>Named(fragments: FragmentSeq) -> FragmentSeq</code> 
'''Names' the fragment by its lowest atom id.'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to name.''
;Examples
: <code>Atoms("Zn").Named().AmbientAtoms(7)</code>
:: ''When exported, the result files will have names in the format '[parent id]_[pseudorandom number]_[zn atomid]'. If the Named function was not used, the name would be just '[parent id]_[pseudorandom number]'.''
----
=== NotAminoAcids ===
<code>NotAminoAcids() -> Residues</code> 
''Sequence of all residues that are not any of the 20 basic amino acids.'' 
;Options
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
;Examples
: <code>NotAminoAcids()</code>
:: ''Returns all residues that are not amino acids.''
----
=== NotAtomIds ===
<code>NotAtomIds(ids: Integer+) -> Atoms</code> 
''Sequence of atoms that do not have specified identifiers.'' 
;Arguments
: ids: Integer+ - ''Identifiers.''
;Examples
: <code>NotAtomIds(1, 2, 3)</code>
:: ''Returns atoms that do not have id 1, 2, nor 3.''
----
=== NotAtomNames ===
<code>NotAtomNames(names: String+) -> Atoms</code> 
''Sequence of atoms that do not have a specified name.'' 
;Arguments
: names: String+ - ''Forbidden names.''
;Examples
: <code>NotAtomNames("O4")</code>
:: ''Returns all atoms that are not called O4.''
----
=== NotAtoms ===
<code>NotAtoms(symbols: String+) -> Atoms</code> 
''Sequence of atoms that are not particular elements.'' 
;Arguments
: symbols: String+ - ''Forbidden element symbols.''
;Examples
: <code>NotAtoms("O")</code>
:: ''Returns all atoms that are not O.''
----
=== NotResidues ===
<code>NotResidues(names: Value+) -> Residues</code> 
''Sequence of residues that are not called by the specified names.'' 
;Arguments
: names: Value+ - ''Forbidden residue names.''
;Examples
: <code>NotResidues("THR","CYS")</code>
:: ''Returns all residues that are not THR or CYS.''
----
=== RegularMotifs ===
<code>RegularMotifs(regex: Value) -> FragmentSeq</code> 
''Identifies regular motifs. The protein is split into individual chains and the residues are sorted by their Sequence Number before the motifs are identified. The query does not check if adjacent residues have consecutive Sequence Numbers. The query works in two modes: Amino and Nucleotide, on amino acids and nucleotides respectively. In the Amino mode, all the derivatives of standard residues are treated as the standard residues, as long as this information is properly annotated in MODRES or _pdbx_struct_mod_residue field. The default mode is 'Amino''' 

;Arguments
: regex: Value - ''Regular expression on one letter abbreviations of amino acids.''
;Options
: Type: String = "Amino" - ''Determines the type of the query. Allowed values: Amino, Nucleotide.''
;Examples
: <code>RegularMotifs("RGD")</code>
:: ''Finds all RGD motifs.''
: <code>RegularMotifs("ACGTU", Type = 'Nucleotide')</code>
:: ''Finds all consecutive occurrences of the ACGTU nucleotides.''
: <code>RegularMotifs(".HC.").Filter(lambda m: m.IsConnected())</code>
:: ''Finds all 4 residue motifs with ?-HIS-CYS-? that are connected.''
----

=== ResidueIdRange ===
<code>ResidueIdRange(chain: String, min: Integer, max: ?Integer) -> Residues</code> 
''Sequence of residues with specific chain and min <= sequence number <= max.'' 
;Arguments
: chain: String - ''Chain identifier. Case sensitive (a != A).''
: min: Integer - ''Minimum sequence number.''
: max: ?Integer - ''Maximum sequence number. If not specified, max = min.''
;Examples
: <code>ResidueIdRange("A", 161, 165)</code>
:: ''Returns all residues on chain A with seq. number between 161 and 165 inclusive.''
----
=== ResidueIds ===
<code>ResidueIds(ids: String+) -> Residues</code> 
''Sequence of residues with specific identifiers. If the structure does not contain a residue with the given identifier, it is skipped.'' 
;Arguments
: ids: String+ - ''One or more identifiers in the format 'NUMBER [CHAIN] [i:INSERTIONCODE]' (parameters in [] are optional, for example '175 i:12' or '143 B'). Case sensitive (a != A).''
;Examples
: <code>ResidueIds("132 A", "178 A")</code>
:: ''Returns residues A 123 and A 178 (provided the input structure contains them).''
----
=== Residues ===
<code>Residues(names: String*) -> Residues</code> 
''Sequence of residues with specified names. If no names are specified, yields all residues one by one.'' 
;Arguments
: names: String* - ''Allowed residue names.''
;Examples
: <code>Residues("HIS", "CYS")</code>
:: ''Returns all HIS or CYS residues.''
----
=== RingAtoms ===
<code>RingAtoms(atom: Atoms, ring: ?Rings) -> Atoms</code> 
''Returns all rings atoms.'' 
;Arguments
: atom: Atoms - ''Atom types.''
: ring: ?Rings - ''Specific ring.''
;Examples
: <code>RingAtoms(Atoms("C"), Rings(4 * ["C"] + ["O"]))</code>
:: ''Returns all C atoms on a ring with 4C and O.''
----
=== Rings ===
<code>Rings(atoms: Value*) -> Rings</code> 
''Sequence of rings with particular atoms. If no atoms are specified, yields all rings (cycles) one by one. The order of atoms matters.'' 
;Arguments
: atoms: Value* - ''Ring atoms.''
;Examples
: <code>Rings()</code>
:: ''Returns all rings.''
: <code>Rings(5 * ["C"] + ["O"])</code>
:: ''Returns all rings with 5C and 1O atoms.''
: <code>Rings(["C", "C", "N", "C", "N"])</code>
:: ''Returns all rings with C-C-N-C-N atoms.''
: <code>Or(Rings(["C", "C", "N", "C", "N"]), Rings(["C", "C", "C", "N", "N"]))</code>
:: ''Returns all rings with C-C-N-C-N or C-C-C-N-N atoms.''
----
=== Sheets ===
<code>Sheets() -> FragmentSeq</code> 
''Returns all sheets. This assumes the information about sheets was present in the input structure.'' 
;Examples
: <code>Sheets()</code>
:: ''Returns all sheets.''
 

== Advanced Query Functions ==
''Advanced building blocks of the language.''
=== Flatten ===
<code>Flatten(fragments: FragmentSeq, selector: Fragment->FragmentSeq) -> FragmentSeq</code> 
''Converts a sequence of sequence of fragments into a single 'flat' sequence.'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to project.''
: selector: Fragment->FragmentSeq - ''The selector.''
;Examples
: <code>Residues("HIS").Flatten(lambda m: m.Find(Atoms("C")))</code>
:: ''Returns all C atoms on HIS residues.''
----
=== Inside ===
<code>Inside(fragments: FragmentSeq, where: FragmentSeq) -> FragmentSeq</code> 
''Finds fragments within another fragment. Equivalent to where.Flatten(lambda m: m.Find(fragments))'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to find.''
: where: FragmentSeq - ''Where to find them.''
;Examples
: <code>Atoms("C").Inside(Residues("HIS"))</code>
:: ''Returns all C atoms on HIS residues.''
----
=== Or ===
<code>Or(fragments: FragmentSeq+) -> FragmentSeq</code> 
''Merges several fragment sequences into one.'' 
;Arguments
: fragments: FragmentSeq+ - ''Fragments to merge.''
;Examples
: <code>Or(Atoms("Zn").ConnectedResidues(1), Rings())</code>
:: ''Finds all zincs and their connected residues or rings.''
----
=== ToAtoms ===
<code>ToAtoms(fragments: FragmentSeq) -> FragmentSeq</code> 
''Collects all 'inner' fragments and yields all unique atoms one by one.'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to split.''
;Examples
: <code>Residues("HIS").ToAtoms()</code>
:: ''Returns all atoms on HIS residues one by one.''
----
=== ToResidues ===
<code>ToResidues(fragments: FragmentSeq) -> FragmentSeq</code> 
''Collects all 'inner' fragments and yields all unique residues one by one. The residues contain only the atoms that have been yielded by the inner query.'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to split.''
;Examples
: <code>Atoms("C").ToResidues()</code>
:: ''Returns all C atoms grouped by residues.''
----
=== Union ===
<code>Union(fragments: FragmentSeq) -> FragmentSeq</code> 
''Collects all 'inner' fragments and yields one created from their unique atoms.'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to merge.''
;Examples
: <code>Rings().Union()</code>
:: ''Creates a single fragment that contains all rings.''
 
== Filter Functions ==
''Functions useful for filtering fragments.''
=== Contains ===
<code>Contains(where: Fragment, what: FragmentSeq) -> Bool</code> 
''Checks if a fragment is contained within another one. Equivalent to where.Count(what) > 0.'' 
;Arguments
: where: Fragment - ''Where to look.''
: what: FragmentSeq - ''What to find.''
;Examples
: <code>HetResidues().Filter(lambda m: m.Contains(Rings(5*['C']+['O'])).Not())</code>
:: ''Returns all HET residues that do not contain a 5CO ring.''
----
=== Count ===
<code>Count(where: Fragment, what: FragmentSeq) -> Integer</code> 
''Counts all occurrences of fragment 'what' in fragment 'where'.'' 
;Arguments
: where: Fragment - ''Where to count it.''
: what: FragmentSeq - ''What fragment to count.''
;Examples
: <code>m.Count(Residues("HIS"))</code>
:: ''Returns the count of HIS residues in the fragment m. Where m is a Fragment (for example when using the Filter function or returned by the ToFragment() function). This example will not work directly and is here to illustrate a concept.''
: <code>Atoms("Zn").ConnectedResidues(1).Filter(lambda m: m.Count(Residues("HIS")) == 2)</code>
:: ''Fragments with Zn atoms and its connected residues with exactly 2 HIS residues.''
----
=== ExecuteIf ===
<code>ExecuteIf(query: FragmentSeq, condition: Fragment->Bool) -> FragmentSeq</code> 
''Executes a query only if the condition is met. Otherwise, return an empty sequence of fragments.'' 
;Arguments
: query: FragmentSeq - ''Query to execute.''
: condition: Fragment->Bool - ''Condition that must be satisfied for the parent structure/fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.Resolution() <= 2.4)</code>
:: ''Returns residues in structures that have resolution lower than 2.4ang.''
: <code>AminoAcids().ExecuteIf(lambda p: p.Count(Atoms('Fe')) > 3)</code>
:: ''Returns all amino acids in structures that have at least 3 Fe atoms.''
----
=== Filter ===
<code>Filter(fragments: FragmentSeq, filter: Fragment->Bool) -> FragmentSeq</code> 
''Filters a sequence of fragments with a given predicate.'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to filter.''
: filter: Fragment->Bool - ''Filter predicate.''
;Examples
: <code>Residues().Filter(lambda m: m.Count(Atoms("C")) >= 3)</code>
:: ''Returns all residues that contain at least 3 C atoms.''
----
=== IsConnected ===
<code>IsConnected(fragment: Fragment) -> Bool</code> 
''Checks if a particular fragment is a connected graph.'' 
;Arguments
: fragment: Fragment - ''A fragment to test.''
;Examples
: <code>Atoms("Zn").AmbientResidues(3).Filter(lambda m: m.IsConnected())</code>
:: ''Finds all fragments with a Zn and residues within 3 ang, where all the ambient residues are connected to the central atom.''
----
=== IsConnectedTo ===
<code>IsConnectedTo(where: Fragment, fragments: FragmentSeq) -> Bool</code> 
''Checks if a particular fragment is connected to any other specified fragment. The fragments must have empty intersection for this function to return true.'' 
;Arguments
: where: Fragment - ''A fragment to test.''
: fragments: FragmentSeq - ''Fragment sequence to test against.''
;Examples
: <code>Atoms().Filter(lambda a: a.IsConnectedTo(Rings()))</code>
:: ''Finds all atoms that are connected to a ring they do not belong to.''
----
=== IsNotConnectedTo ===
<code>IsNotConnectedTo(what: Fragment, fragments: FragmentSeq) -> Bool</code> 
''Checks if a particular fragment is not connected to any other specified fragment. The fragments must have empty intersection for this function to return true.'' 
;Arguments
: what: Fragment - ''A fragment to test.''
: fragments: FragmentSeq - ''Fragment sequence to test against.''
;Examples
: <code>Residues().Filter(lambda r: r.IsNotConnectedTo(Atoms("Ca")))</code>
:: ''Finds all residues that are not connected to Ca atoms. The residue itself can still contain Ca atoms.''
----
=== NearestDistanceTo ===
<code>NearestDistanceTo(where: Fragment, fragments: FragmentSeq) -> Real</code> 
''Finds the distance to a particular fragment.'' 
;Arguments
: where: Fragment - ''A fragment to test.''
: fragments: FragmentSeq - ''Fragment sequence to test against.''
;Examples
: <code>Atoms().Filter(lambda m: m.NearestDistanceTo(Residues("ASP")) >= 5)</code>
:: ''Finds all atoms that are at least 5 (angstroms) away from any ASP residue.''
----
=== SeqCount ===
<code>SeqCount(what: FragmentSeq) -> Integer</code> 
''Counts the length of a sequence of motifs.'' 
;Arguments
: what: FragmentSeq - ''What fragment sequence to count.''
;Examples
: <code>Atoms("Zn").AmbientResidues(3).Filter(lambda m: m.Find(Residues("HIS")).SeqCount() > 1)</code>
:: ''Returns a sequence of fragments with Zn atom and residues within 3ang if the fragment contains at least 2 HIS residues.''
 
== Topology Functions ==
''Functions that rely on the topology of fragments.''
=== ConnectedAtoms ===
<code>ConnectedAtoms(fragment: FragmentSeq, n: Integer) -> FragmentSeq</code> 
''Surrounds the inner fragment by n layers of atoms.'' 
;Arguments
: fragment: FragmentSeq - ''Basic fragment.''
: n: Integer - ''Number of atom layers to connect.''
;Options
: YieldNamedDuplicates: Bool = False - ''Yield duplicate fragments if they have a different name.''
;Examples
: <code>Residues("MAN").ConnectedAtoms(2)</code>
:: ''Finds all MAN residues and then adds two connected levels of atoms to them.''
----
=== ConnectedResidues ===
<code>ConnectedResidues(fragment: FragmentSeq, n: Integer) -> FragmentSeq</code> 
''Surrounds the inner fragment by n layers of residues.'' 
;Arguments
: fragment: FragmentSeq - ''Basic fragment.''
: n: Integer - ''Number of residue layers to connect.''
;Options
: YieldNamedDuplicates: Bool = False - ''Yield duplicate fragments if they have a different name.''
;Examples
: <code>Atoms("Zn").ConnectedResidues(1)</code>
:: ''Finds all Zn atoms and adds all residues that are connected to them.''
----
=== Path ===
<code>Path(fragments: FragmentSeq+) -> FragmentSeq</code> 
''Creates a new fragment from 'connected' parts.'' 
;Arguments
: fragments: FragmentSeq+ - ''Fragments to path.''
;Examples
: <code>Path(Atoms("O"), Atoms("C"), Atoms("O"))</code>
:: ''Finds fragments with two O and one C atoms where the C atoms is connected to the O ones.''
----
=== Star ===
<code>Star(center: FragmentSeq, fragments: FragmentSeq+) -> FragmentSeq</code> 
''Creates a new fragment from a central one and connected parts.'' 
;Arguments
: center: FragmentSeq - ''Center fragment.''
: fragments: FragmentSeq+ - ''Fragments to chain.''
;Examples
: <code>Star(Atoms("C"), Atoms("O"), Atoms("O"))</code>
:: ''Finds fragments with two O atoms and one C atom in the center.''
: <code>Atoms("C").Star(Atoms("O"), Atoms("O"))</code>
:: ''Finds fragments with two O atoms and one C atom in the center.''
 
== Geometry Functions ==
''Functions that rely on the geometry of fragments.''
=== AmbientAtoms ===
<code>AmbientAtoms(fragment: FragmentSeq, r: Number) -> FragmentSeq</code> 
''Surrounds the inner fragment by atoms that within the given radius from the inner fragment.'' 
;Arguments
: fragment: FragmentSeq - ''Basic fragment.''
: r: Number - ''Radius.''
;Options
: ExcludeBase: Bool = False - ''Exclude the central original fragment.''
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
: YieldNamedDuplicates: Bool = False - ''Yield duplicate fragments if they have a different name.''
;Examples
: <code>Atoms("Fe").AmbientAtoms(4)</code>
:: ''Finds Fe atoms and all atoms within 4 (angstroms) from each of them.''
----
=== AmbientResidues ===
<code>AmbientResidues(fragment: FragmentSeq, r: Number) -> FragmentSeq</code> 
''Surrounds the inner fragment by residues that have at least one atom within the given radius from the inner fragment.'' 
;Arguments
: fragment: FragmentSeq - ''Basic fragment.''
: r: Number - ''Radius.''
;Options
: ExcludeBase: Bool = False - ''Exclude the central original fragment.''
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
: YieldNamedDuplicates: Bool = False - ''Yield duplicate fragments if they have a different name.''
;Examples
: <code>Rings(6 * ["C"]).AmbientResidues(4)</code>
:: ''Finds rings with 6C atoms and all residues within 4 (angstroms) from each of them.''
----
=== Cluster ===
<code>Cluster(r: Number, fragments: FragmentSeq+) -> FragmentSeq</code> 
''Clusters all fragments that are pairwise closer than r (angstroms).'' 
;Arguments
: r: Number - ''Maximum distance between two fragments in the cluster.''
: fragments: FragmentSeq+ - ''Fragments to cluster.''
;Examples
: <code>Cluster(4, Atoms("Ca"), Rings(5 * ["C"] + ["O"]))</code>
:: ''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 ===
<code>Filled(fragment: FragmentSeq) -> FragmentSeq</code> 
''Adds all atoms that fall within the circumsphere (with radius multiplied by the factor) of the basic fragment.'' 
;Arguments
: fragment: FragmentSeq - ''Basic fragment.''
;Options
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
: RadiusFactor: Number = 0.75 - ''Circumsphere radius factor.''
;Examples
: <code>Cluster(4, Residues("HIS")).Filled(RadiusFactor = 0.75)</code>
:: ''Finds clusters of HIS residues and all atoms within the circumsphere.''
----
=== Near ===
<code>Near(r: Number, fragments: FragmentSeq+) -> FragmentSeq</code> 
''Clusters all fragments that are pairwise closer than r (angstroms) and checks if the "counts" match.'' 
;Arguments
: r: Number - ''Maximum distance between two sub-fragments in the fragment.''
: fragments: FragmentSeq+ - ''Fragments to 'cluster'.''
;Examples
: <code>Near(4, Atoms("Ca"), Atoms("Ca"), Rings(5 * ["C"] + ["O"]))</code>
:: ''Finds all instance of a single ring with 5C and O atoms and two Ca atoms that are closer than 4 (angstroms).''
 
== Meta-data Functions ==
''Functions dealing with meta-data about structures such as release date or authors.''
=== Authors ===
<code>Authors(fragment: Fragment) -> String</code> 
''Returns authors of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== ECNumbers ===
<code>ECNumbers(fragment: Fragment) -> String</code> 
''Returns Enzymatic Commission numbers assigned to enzymes in the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== EntitySources ===
<code>EntitySources(fragment: Fragment) -> String</code> 
''Returns entity sources of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== ExperimentMethod ===
<code>ExperimentMethod(fragment: Fragment) -> String</code> 
''Get the experiment method. The value is always an upper-case string. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ExperimentMethod() == "INFRARED SPECTROSCOPY")</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== HasAllAuthors ===
<code>HasAllAuthors(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given authors. The comparison is case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllAuthors("Holmes", "Watson"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllECNumbers ===
<code>HasAllECNumbers(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given Enzymatic Commission numbers. It is possible to enter just a number prefix without the '.'. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllECNumbers("3.2.1.18", "3.3"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllEntitySources ===
<code>HasAllEntitySources(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given entity sources. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllEntitySources("GMO", "Natural", "Synthetic"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllHostOrganismGenus ===
<code>HasAllHostOrganismGenus(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given host organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllHostOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllHostOrganismIds ===
<code>HasAllHostOrganismIds(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given host organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllHostOrganismIds("7108", "11244"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllHostOrganisms ===
<code>HasAllHostOrganisms(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given host organism names. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllHostOrganisms("Spodoptera frugiperda", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllKeywords ===
<code>HasAllKeywords(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given keywords. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllKeywords("membrane", "glycoprotein"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllOriginOrganismGenus ===
<code>HasAllOriginOrganismGenus(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given origin organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllOriginOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllOriginOrganismIds ===
<code>HasAllOriginOrganismIds(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given origin organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllOriginOrganismIds("121791", "10090"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllOriginOrganisms ===
<code>HasAllOriginOrganisms(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given origin organism names. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllOriginOrganisms("Nipah virus", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyAuthor ===
<code>HasAnyAuthor(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given authors. The comparison is case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyAuthor("Holmes", "Watson"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyECNumber ===
<code>HasAnyECNumber(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given Enzymatic Commission number. It is possible to enter just a number prefix without the '.'s. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyECNumber("3.2.1.19", "3.3"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyEntitySources ===
<code>HasAnyEntitySources(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given entity sources. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyEntitySources("GMO", "Natural", "Synthetic"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyHostOrganism ===
<code>HasAnyHostOrganism(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given host organism names. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyHostOrganism("Spodoptera frugiperda", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyHostOrganismGenus ===
<code>HasAnyHostOrganismGenus(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given host organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyHostOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyHostOrganismId ===
<code>HasAnyHostOrganismId(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given host organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyHostOrganismId("7108", "11244"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyKeyword ===
<code>HasAnyKeyword(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given keywords. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyKeyword("membrane", "glycoprotein"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyOriginOrganism ===
<code>HasAnyOriginOrganism(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given origin organism names. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyOriginOrganism("Nipah virus", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyOriginOrganismGenus ===
<code>HasAnyOriginOrganismGenus(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given origin organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyOriginOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyOriginOrganismId ===
<code>HasAnyOriginOrganismId(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given origin organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyOriginOrganismId("121791", "10090"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HostOrganismGenus ===
<code>HostOrganismGenus(fragment: Fragment) -> String</code> 
''Returns host organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== HostOrganismIds ===
<code>HostOrganismIds(fragment: Fragment) -> String</code> 
''Returns host organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== HostOrganisms ===
<code>HostOrganisms(fragment: Fragment) -> String</code> 
''Returns host organism names of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== Keywords ===
<code>Keywords(fragment: Fragment) -> String</code> 
''Returns keywords of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== LatestRevisionDate ===
<code>LatestRevisionDate(fragment: Fragment) -> Value</code> 
''Get the latest revision date of the parent structure. The value has to be compared to the DateTime(year, month, day) object. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.LatestRevisionDate() >= DateTime(2008, 1, 1))</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== LatestRevisionYear ===
<code>LatestRevisionYear(fragment: Fragment) -> Integer</code> 
''Get the latest revision year of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.LatestRevisionYear() == 2006)</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== OriginOrganismGenus ===
<code>OriginOrganismGenus(fragment: Fragment) -> String</code> 
''Returns origin organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== OriginOrganismIds ===
<code>OriginOrganismIds(fragment: Fragment) -> String</code> 
''Returns origin organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== OriginOrganisms ===
<code>OriginOrganisms(fragment: Fragment) -> String</code> 
''Returns origin organism names of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== PolymerType ===
<code>PolymerType(fragment: Fragment) -> String</code> 
''Get the polymer type of the structure. Possible values are: NotAssigned, Protein, DNA, RNA, ProteinDNA, ProteinRNA, NucleicAcids, Mixture, Sugar, Other. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.PolymerType() == "ProteinDNA")</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== ProteinStoichiometry ===
<code>ProteinStoichiometry(fragment: Fragment) -> String</code> 
''Get the protein stoichiometry of the parent structure. Possible values are: NotAssigned, Monomer, Homomer, Heteromer. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ProteinStoichiometry() == "Heteromer")</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== ProteinStoichiometryString ===
<code>ProteinStoichiometryString(fragment: Fragment) -> String</code> 
''Get the protein stoichiometry string of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== ReleaseDate ===
<code>ReleaseDate(fragment: Fragment) -> Value</code> 
''Get the release date of the parent structure. The value has to be compared to the DateTime(year, month, day) object. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ReleaseDate() >= DateTime(2008, 1, 1))</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== ReleaseYear ===
<code>ReleaseYear(fragment: Fragment) -> Integer</code> 
''Get the release year of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ReleaseYear() == 2006)</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== Resolution ===
<code>Resolution(fragment: Fragment) -> Real</code> 
''Get the resolution in angstroms of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.Resolution() <= 2.4)</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== Weight ===
<code>Weight(fragment: Fragment) -> Real</code> 
''Get the weight of the molecule in kDa. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.Weight() > 100000.0)</code>
:: ''Returns residues in structures that satisfy the property.''
 
== Miscellaneous Functions ==
''Various useful functions. These function often require a special setup (i.e. only useful in Scripting window or in specific applications).''
=== AminoSequenceString ===
<code>AminoSequenceString(fragment: Fragment) -> String</code> 
''Returns a string of single-letter amino acids contained in the fragment.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: fragment: Fragment - ''Fragment to convert.''
;Examples
: <code>Fragment("1tqn_12").AminoSequenceString()</code>
:: ''Returns a string representing amino acids in the fragment '1tqn_12'.''
: <code>RegularMotifs(Fragment("1tqn_12").AminoSequenceString())</code>
:: ''Returns all regular fragments that correspond to the AMK sequence in 1tqn_12.''
----
=== AtomProperty ===
<code>AtomProperty(atomFragment: Fragment, name: String) -> ?</code> 
''If the property exists and the fragment consists of a single atom, returns the property. Otherwise, returns Nothing.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: atomFragment: Fragment - ''Single atom fragment.''
: name: String - ''Property name.''
;Examples
: <code>a.AtomProperty("charge")</code>
:: ''Gets the 'charge' property of the atom a. Where a is a single atom Fragment. This example will not work directly.''
: <code>Atoms().Filter(lambda a: a.AtomProperty("charge") >= 2)</code>
:: ''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 ===
<code>AtomSimilarity(a: Fragment, b: Fragment) -> Real</code> 
''Computes Jaccard/Tanimoto coefficient on atoms (element symbols) of both structures.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: a: Fragment - ''First fragment.''
: b: Fragment - ''Second fragment.''
;Examples
: <code>AtomSimilarity(Current(),Fragment("1tqn_12"))</code>
:: ''Computes the atom similarity between the current fragment and 1tqn_12. This example can be used in SiteBinder to create a descriptor (assuming a structure with id '1tqn_12' is loaded).''
----
=== CommonAtoms ===
<code>CommonAtoms(modelId: String) -> FragmentSeq</code> 
''Returns a single fragment with atoms common with the model. Properties checked: atom id, element symbol, chain, residue number. This query is useful for example for atom selection in SiteBinder.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: modelId: String - ''Id of the model.''
;Examples
: <code>CommonAtoms("1tqn_12")</code>
:: ''Returns a fragment formed by atoms common with the '1tqn_12' structure.''
----
=== CSA ===
<code>CSA() -> FragmentSeq</code> 
''Entries from Catalytic Site Atlas represented as fragments. Works only if used from the command line version of MotiveQuery and property configured.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Examples
: <code>CSA()</code>
:: ''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 ===
<code>Current() -> Fragment</code> 
''A variable that is assigned by the application environment.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Examples
: <code>AtomSimilarity(Current(), Fragment("model"))</code>
:: ''Returns the atom similarity of the current fragment 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 ===
<code>Descriptor(fragment: Fragment, name: String) -> ?</code> 
''Returns the descriptor. If the descriptor does not exist, 'null' is returned.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: fragment: Fragment - ''Fragment that represents entire structure.''
: name: String - ''Descriptor name.''
;Examples
: <code>Current().Descriptor("similarity") >= 0.75</code>
:: ''Returns True if 'similarity' descriptor of the current fragment is at least 0.75. This example will work for example in SiteBinder's structure selection if the 'similarity' descriptor has been previously defined.''
----
=== DynamicInvoke ===
<code>DynamicInvoke(value: Value, name: String, isProperty: Bool, args: Value) -> Value</code> 
''Dynamically invoke a member. (internal)'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: value: Value - ''InnerQuery.''
: name: String - ''Member name.''
: isProperty: Bool - ''Is this a property.''
: args: Value - ''Array of arguments.''
----
=== Find ===
<code>Find(source: Fragment, fragments: FragmentSeq) -> FragmentSeq</code> 
''Converts the source fragment to a structure and finds fragments within it.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: source: Fragment - ''Where to look.''
: fragments: FragmentSeq - ''Fragments to find.''
;Examples
: <code>AtomSimilarity(Current().Find(NotAtoms("N")).ToFragment(), Fragment("model").Find(NotAtoms("N")).ToFragment())</code>
:: ''Computes the atom similarity of the 'current' and 'model' fragments, but ignores N atoms. This example can be used in SiteBinder to create a descriptor (assuming a structure with id 'model' is loaded).''
----
=== Fragment ===
<code>Fragment(structureName: String) -> Fragment</code> 
''Returns a structure represented as a fragment.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: structureName: String - ''Name of a structure.''
;Examples
: <code>Fragment("1tqn_12")</code>
:: ''Returns the structure '1tqn_12' represented as a fragment. Usable in defining descriptors or in Scripting window (using MQ.Execute).''
----
=== GroupedAtoms ===
<code>GroupedAtoms(symbols: String*) -> FragmentSeq</code> 
''Groups atoms using the element symbol and then returns each group as a single fragment.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: symbols: String* - ''Allowed element symbols.''
;Examples
: <code>GroupedAtoms()</code>
:: ''Returns groups of all atom types. For example if the input has atoms 5xC-1xO, fragments with 5xC and 1xO atoms are returned.''
: <code>GroupedAtoms('C', 'O')</code>
:: ''Returns groups of all atom types. For example if the input has atoms 5xC-1xO-6xH, fragments with 5xC and 1xO atoms are returned (but the H atoms are ignored).''
----
=== ResidueSimilarity ===
<code>ResidueSimilarity(a: Fragment, b: Fragment) -> Real</code> 
''Computes Jaccard/Tanimoto coefficient on residue names of both structures.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: a: Fragment - ''First fragment.''
: b: Fragment - ''Second fragment.''
;Examples
: <code>ResidueSimilarity(Current(), Fragment("1tqn_12"))</code>
:: ''Computes the residue similarity between the current fragment and '1tqn_12'. This example can be used in SiteBinder to create a descriptor (assuming a structure with id '1tqn_12' is loaded).''
----
=== ToFragment ===
<code>ToFragment(fragments: FragmentSeq) -> Fragment</code> 
''Converts a sequence of Fragments (FragmentSeq) to a single Fragment by merging all atoms into a single atom set. The Fragment type is required by some function such as AtomSimilarity.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: fragments: FragmentSeq - ''Fragments to convert.''
;Examples
: <code>Residues("HIS").ToFragment()</code>
:: ''Converts a sequence of HIS residue Fragments to a single Fragment.''
: <code>AtomSimilarity(Current().Find(NotAtoms("N")).ToFragment(), Fragment("model").Find(NotAtoms("N")).ToFragment())</code>
:: ''Computes the atom similarity of the 'current' and 'model' fragments, but ignores N atoms.''
 
== Value Functions ==
''Functions such as addition or comparison of numbers.''
=== Abs ===
<code>Abs(x: Number) -> Number</code> 
''Computes the 'Abs' function of the argument.'' 
;Arguments
: x: Number - ''Argument.''
;Examples
: <code>Abs(x)</code>
:: ''Evaluates the expression.''
----
=== Divide (/) ===
<code>Divide(x: Number, y: Number) -> Number</code> 
''Computes the 'Divide' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x / y</code>
:: ''Evaluates the expression.''
----
=== Equal (==) ===
<code>Equal(x: Value, y: Value) -> Bool</code> 
''Determines the 'Equal' relation between two values.'' 
;Arguments
: x: Value - ''Left argument.''
: y: Value - ''Right argument.''
;Examples
: <code>x == y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== Greater (>) ===
<code>Greater(x: Number, y: Number) -> Bool</code> 
''Determines the 'Greater' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x > y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== GreaterEqual (>=) ===
<code>GreaterEqual(x: Number, y: Number) -> Bool</code> 
''Determines the 'GreaterEqual' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x >= y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== Less (<) ===
<code>Less(x: Number, y: Number) -> Bool</code> 
''Determines the 'Less' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x < y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== LessEqual (<=) ===
<code>LessEqual(x: Number, y: Number) -> Bool</code> 
''Determines the 'LessEqual' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x <= y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== LogicalAnd (&) ===
<code>LogicalAnd(xs: Bool+) -> Bool</code> 
''Computes 'LogicalAnd' of the input values.'' 
;Arguments
: xs: Bool+ - ''Arguments.''
;Examples
: <code>x & y</code>
:: ''Evaluates to True or False based on the values of x and y.''
----
=== LogicalNot (Not) ===
<code>LogicalNot(x: Bool) -> Bool</code> 
''Computes 'LogicalNot' of the input value. This function can be called using the shorthand 'Not'.'' 
;Arguments
: x: Bool - ''Argument.''
;Examples
: <code>LogicalNot(x)</code>
:: ''Evaluates to True or False based on the value of x.''
: <code>x.Not()</code>
:: ''Evaluates to True or False based on the value of x.''
----
=== LogicalOr (|) ===
<code>LogicalOr(xs: Bool+) -> Bool</code> 
''Computes 'LogicalOr' of the input values.'' 
;Arguments
: xs: Bool+ - ''Arguments.''
;Examples
: <code>x | y</code>
:: ''Evaluates to True or False based on the values of x and y.''
----
=== LogicalXor (Xor) ===
<code>LogicalXor(xs: Bool+) -> Bool</code> 
''Computes 'LogicalXor' of the input values. This function can be called using the shorthand 'Xor'.'' 
;Arguments
: xs: Bool+ - ''Arguments.''
;Examples
: <code>LogicalXor(x, y)</code>
:: ''Evaluates to True or False based on the values of x and y.''
: <code>Xor(x, y)</code>
:: ''Evaluates to True or False based on the values of x and y.''
----
=== Minus (-) ===
<code>Minus(x: Number) -> Number</code> 
''Computes the arithmetic negation of the argument.'' 
;Arguments
: x: Number - ''Argument.''
;Examples
: <code>-x</code>
:: ''Arithmetic negation of x.''
----
=== NotEqual (!=) ===
<code>NotEqual(x: Value, y: Value) -> Bool</code> 
''Determines the 'NotEqual' relation between two values.'' 
;Arguments
: x: Value - ''Left argument.''
: y: Value - ''Right argument.''
;Examples
: <code>x != y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== Plus (+) ===
<code>Plus(x: Number, y: Number) -> Number</code> 
''Computes the 'Plus' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x + y</code>
:: ''Evaluates the expression.''
----
=== Power (^) ===
<code>Power(x: Number, y: Number) -> Number</code> 
''Computes the 'Power' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x ^ y</code>
:: ''Evaluates the expression.''
----
=== Subtract (-) ===
<code>Subtract(x: Number, y: Number) -> Number</code> 
''Computes the 'Subtract' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x - y</code>
:: ''Evaluates the expression.''
----
=== Times (*) ===
<code>Times(x: Number, y: Number) -> Number</code> 
''Computes the 'Times' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x * y</code>
:: ''Evaluates the expression.''

PatternQuery:Explorer

2014-12-28T22:23:42Z

Dave: /* Launch MotiveQuery Explorer app */

When mining the whole Protein Data Bank for structural fragments it is always better to look before you leap. This is one of the purposes of the '''MotiveQuery Explorer''' application. This JavaScript/HTML is tailored for:
# Querying user submitted data (up to 100 structures).
# Query smaller subsets of the Protein Data Bank
# '''Tweaking queries before mining the PDB database'''.

The last point would be probably of the most interest for the wide-range of users. In the following visual you will learn how to work with '''MotiveQuery Explorer'''.

If the service is not working the way it should, please check your browser compliances in the [[MotiveQuery:Command_Line#Technical details | technical details section]].

==Launch MotiveQuery Explorer app==

{| class="wikitable" border="1" style="margin: 1em 1em 1em 1em;" width="650px"
|-
| [[File:MotiveQuery-Explorer1.png| 650px]]
| [[File:MotiveQuery-Explorer1b.png| 650px]]
|-
| Follow either '''Explorer''' link or '''Query Playground''' tab at the '''Synopsis''' page, in order to launch the application.
| Create a new session or load a previous one.
|}

==Get started with MotiveQuery Explorer==

{| class="wikitable" border="1" style="margin: 1em 1em 1em 1em;" width="650px"
|-
| [[File:MotiveQuery-Explorer2.png| 650px]]
| [[File:MotiveQuery-Explorer3.png| 650px]]
|-
| The UI of the '''MotiveQuery Explorer''' consists of several elements. At the top of the page you can find a link and a date until when all the results will be stored. Start with loading your data...
| Upload your own structures in a numerous of supported formats (*.pdb, *.cif, *.pqr, *.mol, *.mol2). It is possible to upload multiple files at the same time or use a single ZIP file (*.zip) containing multiple files inside it. Similarly you can load entries from the Protein Data Bank.
|-
| [[File:MotiveQuery-Explorer4.png| 650px]]
| [[File:MotiveQuery-Explorer5.png| 650px]]
|-
| You can to query a subset of Protein Data Bank based on numerous metadata. At first select a property you would like to filter by, then select a comparison method and finally fill in the demanded value. Please read carefully hints and examples below each selected property. Different properties can have different means of providing input values. Note that you can also include a logical expressions. For example: '''S & !N''' in ''Atom'' property means that just structures containing a sulfur atom and none nitrogen will be considered. Multiple filters can be applied at the same time.
| Once you are happy with the specified filters, you can view a subset of the PDB. Either the '''First 15 entries''' based on their id or '''Random 15 entries'''.
|-
| [[File:MotiveQuery-Explorer6.png| 650px]]
| [[File:MotiveQuery-Explorer7.png| 650px]]
|-
| This list highlights a fraction of the PDB structures satisfying your criteria. You can also check, how many structures these conditions apply to. Browse structures and tick them to add to the dataset you would like to query. Do not forget to '''+ Add Selected''' when you are happy with your selection. You can periodically ''fetch'' random structures satisfying your criteria and select those you would like to '''add''' to your dataset as well.
| After loading structures, browse the list of loaded entries in order to inspect further details in the PDB.org or see their validation reports in '''ValidatorDB'''. You can easily modify the list as well. Either by further adding new entries or deleting the present ones. Also note the '''Log panel''' at the bottom of the web page, since it contains valuable information from the process of loading structures.
|}

==Executing Query & interpreting results==

{| class="wikitable" border="1" style="margin: 1em 1em 1em 1em;" width="650px"
|-
| [[File:MotiveQuery-Explorer8.png| 650px]]
| [[File:MotiveQuery-Explorer9.png| 650px]]
|-
| When you have loaded at least a single structure, you can immediately start typing queries in the query box at the top of the page. If you are unsure on how to create query, first browse the principles behind the [[MotiveQuery:Principles | '''MotiveQuery''' language]] and learn how to [[MotiveQuery:How_to_build_a_query | build a query]]. [[MotiveQuery:Use_Cases | Case studies]] and [[MotiveQuery:Language_Reference | language reference]] might come handy as well.
| After the query is executed, which usually takes no more than a few seconds, you can inspect them in the browser or download them for further processing. You cab come back to this session later using it's web address, the results are kept for at least a month.
|}

PatternQuery:Principles

2014-12-28T22:21:54Z

Dave: /* Basic Principles of the Language */

'''A new paradigm for describing structural fragments in molecules'''

This text describes the basic principles of the '''MotiveQuery''' language for describing structural fragments in molecules. First, the text puts two approaches for identifying molecular fragments in contrast: the imperative approach, and the declarative one, taken by the '''MotiveQuery''' language. Next, basic principles of the language are illustrated on several examples and later described in a more formal way. Finally, the original example is revisited and explained in the terms of the newly introduced concepts.

==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>[[MotiveQuery: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 fragment becomes simply:

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

==Basic Principles of the Language==

===Intuitive Description===

As we've seen in the example above, it is very easy to ''compose'' our ideas about the final shape of the fragment we are interested in. The way this works is that the input molecule is decomposed into a stream of fragments. These streams can then be modified and combined into new streams, which can be modified and combined again.

As an example, take the query <code>Atoms('Ca')</code>. What the '''MotiveQuery''' language does is to extract all calcium atoms from the input molecule and represent them as a stream of sets containing one atom each as illustrated on the image below:

[[Image:MotiveQuery-Principles Atoms(Ca).png|center|600px]]

Now, each element of this stream can be modified, for example to include all atoms 4A within the original calcium atom. Now we have a stream of sets of atoms, where each set contains the original Ca atom and the atoms within the given radius. This would be represented by the query <code>Atoms('Ca').AmbientAtoms(4)</code> and is illustrated on the image bellow:

[[Image:MotiveQuery-Principles Atoms(Ca) surr.png|center|600px]]

In the next step, we might wish to keep only these fragments that contain at least 6 atoms. This is achieved by looking at each fragment, counting the number of atoms and throwing away these fragments that do not meet the criteria. Written as a query, this could be represented as <code>Atoms('Ca').AmbientAtoms(4).Filter(lambda m: m.Count(Atoms()) >= 6)</code>. In the graphical form:

[[Image:MotiveQuery-Principles Atoms(Ca) surr filt.png|center|600px]]

The previous filter query also demonstrates another interesting concept of the language: the ability to identify fragments within fragments, which is what the expression <code>m.Count(Atoms())</code> does - the <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> query is executed for each fragment from the original input sequence provided by the expression <code>Atoms('Ca').AmbientAtoms(4)</code>, and creates a new sequence of fragments that each contain a single atom. Then the Count function takes over and returns the number of fragments produced by its argument. In this way, the query <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> inside the Count function can be replaced by any function that also produces a sequence of fragments, for example <code>[[MotiveQuery:Language_Reference#Rings | Rings()]]</code>.

Finally, streams of fragments can be combined. For example, let’s say we want to find all pairs of calcium atoms that are no further than 4A within each other. This can be achieved using the query <code>Near(4, Atoms('Ca'), Atoms('Ca'))</code>. So this query takes as the input two identical streams of calcium atoms and for each pair of them determines if the atoms are closer than 4A to each other. For each pair that satisfies this condition, a new fragment from the 2 atoms is created. Therefore, the result of the above <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code> query is a stream of sets of atoms (fragments) that each contain two calcium atoms that are no further than 4A from each other:

[[Image:Near.png|center|600px]]

With these basic types of queries outlined in the previous paragraphs, the sky's the limit. Due to the composable nature of the language if a new type of motif emerges, only a single function needs to be added to the language for it to work with all its other parts. As an example, assume we didn’t know that proteins had secondary structure called “sheet” and we just discovered it and a fancy algorithm to identify these "sheets". Now we would be interested in how this new type of protein substructure interacts with other parts of the molecule. All that would be needed is to add a function called <code>[[MotiveQuery:Language_Reference#Sheets | Sheets()]]</code> to the language and immediately we would be able to analyze and filter it’s neighborhood using the functions <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code> and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.

===A More Formal Description===
There are two basic data structures that the language is built upon. These are:
* '''Fragment'''. A fragment is simple an arbitrary set of atoms.
* '''Fragment Sequence'''. A sequence of fragments. In mathematical terms, can be understood as a "set of fragments" which is another way of saying "set of sets of atoms".

And on these data structures, there are three basic types of queries:
* '''Generator queries'''. Generator queries, as the name suggests, generate sequences of fragments from the original input. They are the tool that transforms the input molecule into a stream of fragments that can be later modified or combined. Examples of these queries include <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code>, <code>[[MotiveQuery:Language_Reference#Residues | Residues()]]</code>, and <code>[[MotiveQuery:Language_Reference#RegularMotifs | RegularMotifs()]]</code>.
* '''Modifier queries'''. These queries operate on individual fragments and modify them or throw them away. Examples include <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code>, <code>[[MotiveQuery:Language_Reference#ConnectedResidues | ConnectedResidues()]]</code>, and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.
* '''Combinator queries'''. Combinatorial queries take as input two or more sequence of fragments and combine them into a single new sequence that satisfies given criteria. Examples include <code>[[MotiveQuery:Language_Reference#Or | Or()]]</code>, <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code>, and <code>[[MotiveQuery:Language_Reference#Path | Path()]]</code>.

==Example, Revised==
Now that we know the basic building blocks of the language, let’s go back to our original example and analyze it:

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

This corresponds to the following process.

# A generator query <code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code> is executed that produces a sequence of fragments that are composed of atoms corresponding to HET residues.
# Next, the original sequence is modified by adding atoms within 3 angstrom from any original atom to each fragment.
# Finally, each fragment in the modified sequence is examined: all “calcium atom fragments” are identified and counted. Only these fragments that contain at least 1 Ca atom are kept.

Graphically:

<code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code>
[[Image:MotiveQuery-Principles-HetResidues.png|none|500px]]

<code>[[MotiveQuery:Language_Reference#AmbientAtoms | .AmbientAtoms(3)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms.png|none|500px]]

<code>[[MotiveQuery:Language_Reference#Filter | .Filter(lambda l: l.Count(Atoms('Ca')) > 0)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms-filter.png|none|500px]]

PatternQuery:Principles

2014-12-28T22:21:16Z

Dave: /* Intuitive Description */

'''A new paradigm for describing structural fragments in molecules'''

This text describes the basic principles of the '''MotiveQuery''' language for describing structural fragments in molecules. First, the text puts two approaches for identifying molecular fragments in contrast: the imperative approach, and the declarative one, taken by the '''MotiveQuery''' language. Next, basic principles of the language are illustrated on several examples and later described in a more formal way. Finally, the original example is revisited and explained in the terms of the newly introduced concepts.

==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>[[MotiveQuery: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 fragment becomes simply:

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

==Basic Principles of the Language==

===Intuitive Description===

As we've seen in the example above, it is very easy to ''compose'' our ideas about the final shape of the fragment we are interested in. The way this works is that the input molecule is decomposed into a stream of fragments. These streams can then be modified and combined into new streams, which can be modified and combined again.

As an example, take the query <code>Atoms('Ca')</code>. What the '''MotiveQuery''' language does is to extract all calcium atoms from the input molecule and represent them as a stream of sets containing one atom each as illustrated on the image below:

[[Image:MotiveQuery-Principles Atoms(Ca).png|center|600px]]

Now, each element of this stream can be modified, for example to include all atoms 4A within the original calcium atom. Now we have a stream of sets of atoms, where each set contains the original Ca atom and the atoms within the given radius. This would be represented by the query <code>Atoms('Ca').AmbientAtoms(4)</code> and is illustrated on the image bellow:

[[Image:MotiveQuery-Principles Atoms(Ca) surr.png|center|600px]]

In the next step, we might wish to keep only these fragments that contain at least 6 atoms. This is achieved by looking at each fragment, counting the number of atoms and throwing away these fragments that do not meet the criteria. Written as a query, this could be represented as <code>Atoms('Ca').AmbientAtoms(4).Filter(lambda m: m.Count(Atoms()) >= 6)</code>. In the graphical form:

[[Image:MotiveQuery-Principles Atoms(Ca) surr filt.png|center|600px]]

The previous filter query also demonstrates another interesting concept of the language: ability to identify fragments within fragments, which is what the expression <code>m.Count(Atoms())</code> does - the <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> query is executed for each fragment from the original input sequence provided by the expression <code>Atoms('Ca').AmbientAtoms(4)</code>, and creates a new sequence of fragments that each contain a single atom. Then the Count function takes over and returns the number of fragments produced by its argument. In this way, the query <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> inside the Count function can be replaced by any function that also produces a sequence of fragments, for example <code>[[MotiveQuery:Language_Reference#Rings | Rings()]]</code>.

Finally, streams of fragments can be combined. For example, let’s say we want to find all pairs of calcium atoms that are no further than 4A within each other. This can be achieved using the query <code>Near(4, Atoms('Ca'), Atoms('Ca'))</code>. So this query takes as the input two identical streams of calcium atoms and for each pair of them determines if the atoms are closer than 4A to each other. For each pair that satisfies this condition, a new fragment from the 2 atoms is created. Therefore, the result of the above <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code> query is a stream of sets of atoms (fragments) that each contain two calcium atoms that are no further than 4A from each other:

[[Image:Near.png|center|600px]]

With these basic types of queries outlined in the previous paragraphs, the sky's the limit. Due to the composable nature of the language if a new type of motif emerges, only a single function needs to be added to the language for it to work with all its other parts. As an example, assume we didn’t know that proteins had secondary structure called “sheet” and we just discovered it and a fancy algorithm to identify these "sheets". Now we would be interested in how this new type of protein substructure interacts with other parts of the molecule. All that would be needed is to add a function called <code>[[MotiveQuery:Language_Reference#Sheets | Sheets()]]</code> to the language and immediately we would be able to analyze and filter it’s neighborhood using the functions <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code> and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.

===A More Formal Description===
There are two basic data structures that the language is built upon. These are:
* '''Fragment'''. A fragment is simple an arbitrary set of atoms.
* '''Fragment Sequence'''. A sequence of fragments. In mathematical terms, can be understood as a "set of fragments" which is another way of saying "set of sets of atoms".

And on these data structures, there are three basic types of queries:
* '''Generator queries'''. Generator queries, as the name suggests, generate sequences of fragments from the original input. They are the tool that transforms the input molecule into a stream of fragments that can be later modified or combined. Examples of these queries include <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code>, <code>[[MotiveQuery:Language_Reference#Residues | Residues()]]</code>, and <code>[[MotiveQuery:Language_Reference#RegularMotifs | RegularMotifs()]]</code>.
* '''Modifier queries'''. These queries operate on individual fragments and modify them or throw them away. Examples include <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code>, <code>[[MotiveQuery:Language_Reference#ConnectedResidues | ConnectedResidues()]]</code>, and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.
* '''Combinator queries'''. Combinatorial queries take as input two or more sequence of fragments and combine them into a single new sequence that satisfies given criteria. Examples include <code>[[MotiveQuery:Language_Reference#Or | Or()]]</code>, <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code>, and <code>[[MotiveQuery:Language_Reference#Path | Path()]]</code>.

==Example, Revised==
Now that we know the basic building blocks of the language, let’s go back to our original example and analyze it:

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

This corresponds to the following process.

# A generator query <code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code> is executed that produces a sequence of fragments that are composed of atoms corresponding to HET residues.
# Next, the original sequence is modified by adding atoms within 3 angstrom from any original atom to each fragment.
# Finally, each fragment in the modified sequence is examined: all “calcium atom fragments” are identified and counted. Only these fragments that contain at least 1 Ca atom are kept.

Graphically:

<code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code>
[[Image:MotiveQuery-Principles-HetResidues.png|none|500px]]

<code>[[MotiveQuery:Language_Reference#AmbientAtoms | .AmbientAtoms(3)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms.png|none|500px]]

<code>[[MotiveQuery:Language_Reference#Filter | .Filter(lambda l: l.Count(Atoms('Ca')) > 0)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms-filter.png|none|500px]]

PatternQuery:Terminology

2014-12-28T22:19:18Z

Dave: /* Residue */

The key terms used within the '''MotiveQuery (MQ)''' environment are defined below. It is important to establish these terms before moving on the description of the principles on which '''MQ''' is built. Any input file containing biomolecular structures is parsed and interpreted at several levels. Any of them can be successfully used when creating queries.

=Atom=
All biomolecules are made up of a set of atoms. In the '''MQ''' environment, each atom is uniquely identified in the input file by its ''atom name'', ''id'', ''chemical element'', ''chain and a residue details the atom belongs to (''residue name'' and ''id'').

=Residue=
The term residues is generally used to refer to any component of a biomolecule. Within the '''MQ''' environment, any collection of atoms bound by chemical bonds (covalent, coordinative or ionic) is considered a residue if this fact is appropriately indicated in the input file. Specifically, all the atoms that make up a residue should have the same ''residue name'' (3-letter code) , ''residue serial number'' and ''chain identifier''.

=Fragment=
Fragment is a subset of atoms of the input biomolecule. It can also be understood as an arrangement of either atoms or residues. Therefore, individual atoms and residues can be considered as fragments as well.

=Query=
Query is a single declarative expression of the '''MQ''' language which describes one or more structural fragments inside an input biomolecule.

PatternQuery:Terminology

2014-12-28T22:18:48Z

Dave: /* Atom */

The key terms used within the '''MotiveQuery (MQ)''' environment are defined below. It is important to establish these terms before moving on the description of the principles on which '''MQ''' is built. Any input file containing biomolecular structures is parsed and interpreted at several levels. Any of them can be successfully used when creating queries.

=Atom=
All biomolecules are made up of a set of atoms. In the '''MQ''' environment, each atom is uniquely identified in the input file by its ''atom name'', ''id'', ''chemical element'', ''chain and a residue details the atom belongs to (''residue name'' and ''id'').

=Residue=
We generally use the term residue to refer to any component of a biomolecule. Within the '''MQ''' environment, any collection of atoms bound by chemical bonds (covalent, coordinative or ionic) is considered a residue if this fact is appropriately indicated in the input file. Specifically, all the atoms that make up a residue should have the same ''residue name'' (3-letter code) , ''residue serial number'' and ''chain identifier''.

=Fragment=
Fragment is a subset of atoms of the input biomolecule. It can also be understood as an arrangement of either atoms or residues. Therefore, individual atoms and residues can be considered as fragments as well.

=Query=
Query is a single declarative expression of the '''MQ''' language which describes one or more structural fragments inside an input biomolecule.

PatternQuery:Terminology

2014-12-28T22:18:21Z

Dave: /* Query */

The key terms used within the '''MotiveQuery (MQ)''' environment are defined below. It is important to establish these terms before moving on the description of the principles on which '''MQ''' is built. Any input file containing biomolecular structures is parsed and interpreted at several levels. Any of them can be successfully used when creating queries.

=Atom=
All biomolecules are made up of a set of atoms. In the '''MQ''' environment, each atom is uniquely identified in the input file by its ''atom name'', ''id'', ''chemical element'', ''chain and a residue details the atom belong to (''residue name'' and ''id'').

=Residue=
We generally use the term residue to refer to any component of a biomolecule. Within the '''MQ''' environment, any collection of atoms bound by chemical bonds (covalent, coordinative or ionic) is considered a residue if this fact is appropriately indicated in the input file. Specifically, all the atoms that make up a residue should have the same ''residue name'' (3-letter code) , ''residue serial number'' and ''chain identifier''.

=Fragment=
Fragment is a subset of atoms of the input biomolecule. It can also be understood as an arrangement of either atoms or residues. Therefore, individual atoms and residues can be considered as fragments as well.

=Query=
Query is a single declarative expression of the '''MQ''' language which describes one or more structural fragments inside an input biomolecule.

PatternQuery:Terminology

2014-12-28T22:17:50Z

Dave: /* Fragment */

The key terms used within the '''MotiveQuery (MQ)''' environment are defined below. It is important to establish these terms before moving on the description of the principles on which '''MQ''' is built. Any input file containing biomolecular structures is parsed and interpreted at several levels. Any of them can be successfully used when creating queries.

=Atom=
All biomolecules are made up of a set of atoms. In the '''MQ''' environment, each atom is uniquely identified in the input file by its ''atom name'', ''id'', ''chemical element'', ''chain and a residue details the atom belong to (''residue name'' and ''id'').

=Residue=
We generally use the term residue to refer to any component of a biomolecule. Within the '''MQ''' environment, any collection of atoms bound by chemical bonds (covalent, coordinative or ionic) is considered a residue if this fact is appropriately indicated in the input file. Specifically, all the atoms that make up a residue should have the same ''residue name'' (3-letter code) , ''residue serial number'' and ''chain identifier''.

=Fragment=
Fragment is a subset of atoms of the input biomolecule. It can also be understood as an arrangement of either atoms or residues. Therefore, individual atoms and residues can be considered as fragments as well.

=Query=
Query is a single declarative expression of the '''MQ''' language which describes a structural fragment.

PatternQuery:Terminology

2014-12-28T22:15:47Z

Dave: /* Query */

The key terms used within the '''MotiveQuery (MQ)''' environment are defined below. It is important to establish these terms before moving on the description of the principles on which '''MQ''' is built. Any input file containing biomolecular structures is parsed and interpreted at several levels. Any of them can be successfully used when creating queries.

=Atom=
All biomolecules are made up of a set of atoms. In the '''MQ''' environment, each atom is uniquely identified in the input file by its ''atom name'', ''id'', ''chemical element'', ''chain and a residue details the atom belong to (''residue name'' and ''id'').

=Residue=
We generally use the term residue to refer to any component of a biomolecule. Within the '''MQ''' environment, any collection of atoms bound by chemical bonds (covalent, coordinative or ionic) is considered a residue if this fact is appropriately indicated in the input file. Specifically, all the atoms that make up a residue should have the same ''residue name'' (3-letter code) , ''residue serial number'' and ''chain identifier''.

=Fragment=
Fragment is a subset of biomolecule defined by a query. Basically, it is any arrangement of either atoms or residues. Therefore, both atoms and also residues can be considered as fragments too.

=Query=
Query is a single declarative expression of the '''MQ''' language which describes a structural fragment.

PatternQuery:Explorer

2014-12-28T22:14:16Z

Dave: /* Executing Query & interpreting results */

When mining the whole Protein Data Bank for structural fragments it is always better to look before you leap. This is one of the purposes of the '''MotiveQuery Explorer''' application. This JavaScript/HTML is tailored for:
# Querying user submitted data (up to 100 structures).
# Query smaller subsets of the Protein Data Bank
# '''Tweaking queries before mining the PDB database'''.

The last point would be probably of the most interest for the wide-range of users. In the following visual you will learn how to work with '''MotiveQuery Explorer'''.

If the service is not working the way it should, please check your browser compliances in the [[MotiveQuery:Command_Line#Technical details | technical details section]].

==Launch MotiveQuery Explorer app==

{| class="wikitable" border="1" style="margin: 1em 1em 1em 1em;" width="650px"
|-
| [[File:MotiveQuery-Explorer1.png| 650px]]
| [[File:MotiveQuery-Explorer1b.png| 650px]]
|-
| Follow either '''Explorer''' link or '''Query Playground''' tab at the '''Synopsis''' page, in order to launch the application.
| Create a new session or load the previous one.
|}

==Get started with MotiveQuery Explorer==

{| class="wikitable" border="1" style="margin: 1em 1em 1em 1em;" width="650px"
|-
| [[File:MotiveQuery-Explorer2.png| 650px]]
| [[File:MotiveQuery-Explorer3.png| 650px]]
|-
| The UI of the '''MotiveQuery Explorer''' consists of several elements. At the top of the page you can find a link and a date until when all the results will be stored. Start with loading your data...
| Upload your own structures in a numerous of supported formats (*.pdb, *.cif, *.pqr, *.mol, *.mol2). It is possible to upload multiple files at the same time or use a single ZIP file (*.zip) containing multiple files inside it. Similarly you can load entries from the Protein Data Bank.
|-
| [[File:MotiveQuery-Explorer4.png| 650px]]
| [[File:MotiveQuery-Explorer5.png| 650px]]
|-
| You can to query a subset of Protein Data Bank based on numerous metadata. At first select a property you would like to filter by, then select a comparison method and finally fill in the demanded value. Please read carefully hints and examples below each selected property. Different properties can have different means of providing input values. Note that you can also include a logical expressions. For example: '''S & !N''' in ''Atom'' property means that just structures containing a sulfur atom and none nitrogen will be considered. Multiple filters can be applied at the same time.
| Once you are happy with the specified filters, you can view a subset of the PDB. Either the '''First 15 entries''' based on their id or '''Random 15 entries'''.
|-
| [[File:MotiveQuery-Explorer6.png| 650px]]
| [[File:MotiveQuery-Explorer7.png| 650px]]
|-
| This list highlights a fraction of the PDB structures satisfying your criteria. You can also check, how many structures these conditions apply to. Browse structures and tick them to add to the dataset you would like to query. Do not forget to '''+ Add Selected''' when you are happy with your selection. You can periodically ''fetch'' random structures satisfying your criteria and select those you would like to '''add''' to your dataset as well.
| After loading structures, browse the list of loaded entries in order to inspect further details in the PDB.org or see their validation reports in '''ValidatorDB'''. You can easily modify the list as well. Either by further adding new entries or deleting the present ones. Also note the '''Log panel''' at the bottom of the web page, since it contains valuable information from the process of loading structures.
|}

==Executing Query & interpreting results==

{| class="wikitable" border="1" style="margin: 1em 1em 1em 1em;" width="650px"
|-
| [[File:MotiveQuery-Explorer8.png| 650px]]
| [[File:MotiveQuery-Explorer9.png| 650px]]
|-
| When you have loaded at least a single structure, you can immediately start typing queries in the query box at the top of the page. If you are unsure on how to create query, first browse the principles behind the [[MotiveQuery:Principles | '''MotiveQuery''' language]] and learn how to [[MotiveQuery:How_to_build_a_query | build a query]]. [[MotiveQuery:Use_Cases | Case studies]] and [[MotiveQuery:Language_Reference | language reference]] might come handy as well.
| After the query is executed, which usually takes no more than a few seconds, you can inspect them in the browser or download them for further processing. You cab come back to this session later using it's web address, the results are kept for at least a month.
|}

PatternQuery:Explorer

2014-12-28T22:12:18Z

Dave: /* Get started with MotiveQuery Explorer */

When mining the whole Protein Data Bank for structural fragments it is always better to look before you leap. This is one of the purposes of the '''MotiveQuery Explorer''' application. This JavaScript/HTML is tailored for:
# Querying user submitted data (up to 100 structures).
# Query smaller subsets of the Protein Data Bank
# '''Tweaking queries before mining the PDB database'''.

The last point would be probably of the most interest for the wide-range of users. In the following visual you will learn how to work with '''MotiveQuery Explorer'''.

If the service is not working the way it should, please check your browser compliances in the [[MotiveQuery:Command_Line#Technical details | technical details section]].

==Launch MotiveQuery Explorer app==

{| class="wikitable" border="1" style="margin: 1em 1em 1em 1em;" width="650px"
|-
| [[File:MotiveQuery-Explorer1.png| 650px]]
| [[File:MotiveQuery-Explorer1b.png| 650px]]
|-
| Follow either '''Explorer''' link or '''Query Playground''' tab at the '''Synopsis''' page, in order to launch the application.
| Create a new session or load the previous one.
|}

==Get started with MotiveQuery Explorer==

{| class="wikitable" border="1" style="margin: 1em 1em 1em 1em;" width="650px"
|-
| [[File:MotiveQuery-Explorer2.png| 650px]]
| [[File:MotiveQuery-Explorer3.png| 650px]]
|-
| The UI of the '''MotiveQuery Explorer''' consists of several elements. At the top of the page you can find a link and a date until when all the results will be stored. Start with loading your data...
| Upload your own structures in a numerous of supported formats (*.pdb, *.cif, *.pqr, *.mol, *.mol2). It is possible to upload multiple files at the same time or use a single ZIP file (*.zip) containing multiple files inside it. Similarly you can load entries from the Protein Data Bank.
|-
| [[File:MotiveQuery-Explorer4.png| 650px]]
| [[File:MotiveQuery-Explorer5.png| 650px]]
|-
| You can to query a subset of Protein Data Bank based on numerous metadata. At first select a property you would like to filter by, then select a comparison method and finally fill in the demanded value. Please read carefully hints and examples below each selected property. Different properties can have different means of providing input values. Note that you can also include a logical expressions. For example: '''S & !N''' in ''Atom'' property means that just structures containing a sulfur atom and none nitrogen will be considered. Multiple filters can be applied at the same time.
| Once you are happy with the specified filters, you can view a subset of the PDB. Either the '''First 15 entries''' based on their id or '''Random 15 entries'''.
|-
| [[File:MotiveQuery-Explorer6.png| 650px]]
| [[File:MotiveQuery-Explorer7.png| 650px]]
|-
| This list highlights a fraction of the PDB structures satisfying your criteria. You can also check, how many structures these conditions apply to. Browse structures and tick them to add to the dataset you would like to query. Do not forget to '''+ Add Selected''' when you are happy with your selection. You can periodically ''fetch'' random structures satisfying your criteria and select those you would like to '''add''' to your dataset as well.
| After loading structures, browse the list of loaded entries in order to inspect further details in the PDB.org or see their validation reports in '''ValidatorDB'''. You can easily modify the list as well. Either by further adding new entries or deleting the present ones. Also note the '''Log panel''' at the bottom of the web page, since it contains valuable information from the process of loading structures.
|}

==Executing Query & interpreting results==

{| class="wikitable" border="1" style="margin: 1em 1em 1em 1em;" width="650px"
|-
| [[File:MotiveQuery-Explorer8.png| 650px]]
| [[File:MotiveQuery-Explorer9.png| 650px]]
|-
| When you have loaded at least a single structure, you can immediately start typing queries in the query box at the top of the page. If you are unsure on how to create query, first browse the principles behind the [[MotiveQuery:Principles | '''MotiveQuery''' language]] and learn how to [[MotiveQuery:How_to_build_a_query | build a query]]. [[MotiveQuery:Use_Cases | Case studies]] and [[MotiveQuery:Language_Reference | language reference]] might come handy as well.
| After the query is executed, the results are visualized in no time, you can inspect them in the browser or download them for further processing. You are free to come back to this web address later, the results are kept for at least a month.
|}

PatternQuery:Explorer

2014-12-28T22:08:59Z

Dave:

When mining the whole Protein Data Bank for structural fragments it is always better to look before you leap. This is one of the purposes of the '''MotiveQuery Explorer''' application. This JavaScript/HTML is tailored for:
# Querying user submitted data (up to 100 structures).
# Query smaller subsets of the Protein Data Bank
# '''Tweaking queries before mining the PDB database'''.

The last point would be probably of the most interest for the wide-range of users. In the following visual you will learn how to work with '''MotiveQuery Explorer'''.

If the service is not working the way it should, please check your browser compliances in the [[MotiveQuery:Command_Line#Technical details | technical details section]].

==Launch MotiveQuery Explorer app==

{| class="wikitable" border="1" style="margin: 1em 1em 1em 1em;" width="650px"
|-
| [[File:MotiveQuery-Explorer1.png| 650px]]
| [[File:MotiveQuery-Explorer1b.png| 650px]]
|-
| Follow either '''Explorer''' link or '''Query Playground''' tab at the '''Synopsis''' page, in order to launch the application.
| Create a new session or load the previous one.
|}

==Get started with MotiveQuery Explorer==

{| class="wikitable" border="1" style="margin: 1em 1em 1em 1em;" width="650px"
|-
| [[File:MotiveQuery-Explorer2.png| 650px]]
| [[File:MotiveQuery-Explorer3.png| 650px]]
|-
| The UI of the '''MotiveQuery Explorer''' consists of several elements. At the top of the page you can find a link and a date until when all the results will be stored. Start with loading your data...
| Upload your own structures in a numerous of supported formats (*.pdb, *.cif, *.pqr, *.mol, *.mol2), multiple files can be uploaded at time, in case they are zipped (*.zip). Similarly you can load entries from the Protein Data Bank.
|-
| [[File:MotiveQuery-Explorer4.png| 650px]]
| [[File:MotiveQuery-Explorer5.png| 650px]]
|-
| You can to query a subset of Protein Data Bank based on numerous metadata. At first select a property you would like to filter by, then select a comparison method and finally fill in the demanded value. Please read carefully hints and examples below each selected property. Different properties can have different means of providing input values. Note that you can also include a logical expressions. For example: '''S & !N''' in ''Atom'' property means that just structures containing a sulfur atom and none nitrogen will be considered. Multiple filters can be applied at the same time.
| Once you are happy with the specified filters, you can view a subset of the PDB. Either the '''First 15 entries''' based on their id or '''Random 15 entries'''.
|-
| [[File:MotiveQuery-Explorer6.png| 650px]]
| [[File:MotiveQuery-Explorer7.png| 650px]]
|-
| This list highlights a fraction of the PDB structures satisfying your criteria. You can also check, how many structures these conditions apply to. Browse structures and tick them to add to the dataset you would like to query. Do not forget to '''+ Add Selected''' when you are happy with your selection. You can periodically ''fetch'' random structures satisfying your criteria and select those you would like to '''add''' to your dataset as well.
| After loading structures, browse the list of loaded entries in order to inspect further details in the PDB.org or see their validation reports in '''ValidatorDB'''. You can easily modify the list as well. Either by further adding new entries or deleting the present ones. Also note the '''Status bar''' at the bottom of the web page, since it contains valuable information from the process of loading structures.
|}

==Executing Query & interpreting results==

{| class="wikitable" border="1" style="margin: 1em 1em 1em 1em;" width="650px"
|-
| [[File:MotiveQuery-Explorer8.png| 650px]]
| [[File:MotiveQuery-Explorer9.png| 650px]]
|-
| When you have loaded at least a single structure, you can immediately start typing queries in the query box at the top of the page. If you are unsure on how to create query, first browse the principles behind the [[MotiveQuery:Principles | '''MotiveQuery''' language]] and learn how to [[MotiveQuery:How_to_build_a_query | build a query]]. [[MotiveQuery:Use_Cases | Case studies]] and [[MotiveQuery:Language_Reference | language reference]] might come handy as well.
| After the query is executed, the results are visualized in no time, you can inspect them in the browser or download them for further processing. You are free to come back to this web address later, the results are kept for at least a month.
|}

PatternQuery:Service Organization

2014-12-28T20:16:55Z

Dave:

'''Motive Query''' service is aimed for querying large datasets of structures from the [http://www.rcsb.org/pdb/home/home.do Protein Data Bank]. For the perfecting your query or querying smaller datasets or even user-uploaded data, please use [[MotiveQuery:MotiveExplorer | MotiveQuery Explorer]] instead.

If you would like to run '''MotiveQuery''' at your home institution, please download a [[MotiveQuery:Command_Line | command-line]] version. The following visual will guide you through the process of submitting you calculation so as the interpreting results.

=Synopsis Page=
[[File:MotiveQuery-Service0.png | right | thumb | 650px| '''MotiveQuery Service''' UI]]
The '''MotiveQuery''' synopsis page is divided into a number of tabs:
* '''Quick Help''' and '''Samples''' tab provides information to help you orient better.
* '''Support''' provides a simple user interface for asking questions related to a '''MotiveQuery''' language or service. We do our best to come back to your questions as soon as possible. '''Query Playground''' represents an interface for the [[MotiveQuery:MotiveExplorer | MotiveQuery Explorer]] application where you can tune up your queries before doing the database-wide searches.
* '''Query Protein Data Bank''' is a simple interface for creating a database wide '''MotiveQuery''' calculation.
* '''Command Line Version''' enables you to download a MotiveQuery service and run it at your home institution over your in-house database in a supported format (*.pdb, *.cif, *.pqr, *.mol and *.sdf).
 

=Job Submission=

{| class="wikitable" border="1" style="margin: 1em 1em 1em 1em;" width="650px"
|-
| [[File:MotiveQuery-Service1.png| 650px]]
| [[File:MotiveQuery-Service2.png| 650px]]
|-
| The UI of the '''MotiveQuery Service''' job submission page allows user to submit a new query calculation. First time user can take a look at some of the example queries. If you have run any calculations with '''MotiveQuery''' already, you can browse the results.
| At first, decide whether you would like to query an entire Protein Data Bank, its subset based on a variety of different properties, or you have a list of PDB entries of your interest.
|-
| [[File:MotiveQuery-Service3.png| 650px]]
| [[File:MotiveQuery-Service4.png| 650px]]
|-
| You can to query a subset of Protein Data Bank based on numerous metadata. At first select a property you would like to filter by, then select a comparison method and finally fill in the demanded value. Please read carefully hints and examples below each selected property. Different properties can have different means of providing input values. Note that you can also include a logical expressions. For example: '''S & !N''' in ''Atom'' property means that just structures containing a sulfur atom and none nitrogen atom will be considered. Multiple filters can be applied at the same time.
| Once you select a data set, you can specify multiple queries which will be executed. If you are unsure on how to compose a query, try one of the provided examples. You can also take a look into our [[MotiveQuery:How_to_build_a_query | case studies]] or consult the [[MotiveQuery:Language_Reference | language reference]]. In case none of these help, ask us a question via '''Support''' tab. We will be happy to answer you in the shortest possible time. Do '''not forget''' to click '''+ Add''' after you finish composing query.
|-
| [[File:MotiveQuery-Service5.png| 650px]]
|-
| As soon as you specify a query or queries and so data set, you can tick an option to validate all the ligands and non-standard residues for their structure integrity using [[ValidatorDB:UserManual | ValidatorDB]] and, finally, submit the calculation. Based on the number of processed structures, the execution time can be in the range of minutes (thousands of structures) to an hour (whole Protein Data Bank). Bookmark the newly generated web address as the results will be available here upon the calculation finishes.
|}
 

'''Please continue reading to the [[MotiveQuery:Specifics Page | Specifics page]], where you can find additional info on downloading and inspecting your results.

PatternQuery:UserManual

2014-12-26T12:47:19Z

Dave:

__NOTOC__

'''MotiveQuery''' ('''MQ''') is interactive, user-friendly and platform independent web service enabling user to effectively define, extract and analyze biomolecular structural fragments using '''MotiveQuery language'''. Such analysis is particularly useful not only in a structural and functional assignment of uncharacterized or newly determined proteins, but also represents a key point in rational design and engineering of novel functional sites and comparative protein structural analyses.

The '''MQ''' is provided as a web service for mining the whole [http://pdb.org/pdb/home/home.do PDB database], however it can also be restricted based on numerous metadata, such as the ''Release date'', ''Resolution'', ''EC number'' and so on. Therefore, only structures relevant for your research are processed. Additionally, smaller amount of user structures can be processed in the [[MotiveQuery:MotiveExplorer | MotiveExplorer]] application. Larger in-house databases can be processed with the [[MotiveQuery:Command Line | command line application]].

Below you can find the '''MQ''' user manual, which contains all the information you need in order to make efficient use of '''MQ'''. Additional support is provided on the [http://webchem.ncbr.muni.cz/Platform/MotiveQuery/Index '''MQ''' web pages]. When you first access the '''MQ''' page, you will find basic information in the Quick Help tab, and useful examples in the Samples tab. Follow the green ? buttons to access the embedded interactive guides that assist you in setting up your calculations and interpreting the results. Many tool tips are available when hovering over various elements of the interface.
----
===[[MotiveQuery:Introduction | Introduction]]===
----
===[[MotiveQuery:Terminology | Terminology]]===
#[[MotiveQuery:Terminology#Atom | Atom]]
#[[MotiveQuery:Terminology#Residue | Residue]]
#[[MotiveQuery:Terminology#Fragment | Fragment]]
#[[MotiveQuery:Terminology#Query | Query]]

----
===[[MotiveQuery:Principles | Principles of the MQ language]]===
#[[MotiveQuery:Principles#Example, Part One | Example - introduction]]
#[[MotiveQuery:Principles#Basic Principles of the Language | Basic Principle]]
#[[MotiveQuery:Principles#Example, Part One | Example - revised]]
----
===[[MotiveQuery:How to build a query | How to build a query]]===
#[[MotiveQuery:How to build a query#How to think about queries | How to think about query]]
#[[MotiveQuery:How to build a query#Ready-to-use examples | Ready-to-use examples]]
----
===[[MotiveQuery:Use Cases | Biological use cases]]===
#[[MotiveQuery:Use Cases#Find all post-translational modified amino acids | Post-translational modified aminoacids]]
#[[MotiveQuery:Use Cases#Identify Zinc fingers | Zinc fingers]]
#[[MotiveQuery:Use Cases#Identify all the residues, which contain a sugar ring | Residue containing carbohydrate moiety]]
----
===[[MotiveQuery:MotiveExplorer | MotiveQuery Explorer]]===
----

===[[MotiveQuery:Service Organization | Using MotiveQuery service]]===
----
===[[MotiveQuery:Language_Reference | Language reference]]===
----
===[[MotiveQuery:Command Line | Command line version & Technical details]]===
----

Main Page

2014-12-24T17:31:51Z

Dave:

__NOTOC__
=== [[MotiveQuery:UserManual | MotiveQuery]] ===
=== [[MotiveValidator]] ===
=== [[ValidatorDB:UserManual | ValidatorDB]] ===
=== [[ChargeCalculator:UserManual | AtomicChargeCalculator]] ===

PatternQuery:Principles

2014-12-24T17:03:35Z

Dave: /* Example, Part One */

'''A new paradigm for describing structural fragments in molecules'''

This text describes the basic principles of the '''MotiveQuery''' language for describing structural fragments in molecules. First, the text puts two approaches for identifying molecular fragments in contrast: the imperative approach, and the declarative one, taken by the '''MotiveQuery''' language. Next, basic principles of the language are illustrated on several examples and later described in a more formal way. Finally, the original example is revisited and explained in the terms of the newly introduced concepts.

==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>[[MotiveQuery: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 fragment becomes simply:

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

==Basic Principles of the Language==

===Intuitive Description===

As we've seen in the example above, it is very easy to ''compose'' our ideas about the final shape of the fragment we are interested in. The way this works is that the input molecule is decomposed into a stream of fragments. These streams can then be modified and combined into new streams, which can be modified and combined again.

As an example, take the query <code>Atoms('Ca')</code>. What the '''MotiveQuery''' language does is to extract all calcium atoms from the input molecule and represent them as a stream of sets containing one atom each as illustrated on the image below:

[[Image:MotiveQuery-Principles Atoms(Ca).png|center|600px]]

Now, each element of this stream can be modified, for example to include all atoms 4A within the original calcium atom. Now we have a stream of sets of atoms, where each set contains the original Ca atom and the atoms within the given radius. This would be represented by the query <code>Atoms('Ca').AmbientAtoms(4)</code> and is illustrated on the image bellow:

[[Image:MotiveQuery-Principles Atoms(Ca) surr.png|center|600px]]

In the next step, we might wish to keep only these fragments that contain at least 6 atoms. This is achieved by looking at each fragment, counting the number of atoms and throwing away these fragments that do not meet the criteria. Written as a query, this could be represented as <code>Atoms('Ca').AmbientAtoms(4).Filter(lambda m: m.Count(Atoms()) >= 6)</code>. In the graphical form:

[[Image:MotiveQuery-Principles Atoms(Ca) surr filt.png|center|600px]]

The previous filter query also demonstrates another interesting concept of the language: ability to identify fragments within fragments, which is what the expression <code>m.Count(Atoms())</code> does - the <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> query is executed for each fragment from the original input sequence provided by the expression <code>Atoms('Ca').AmbientAtoms(4)</code>, and creates a new sequence of fragments that each contain a single atom. Then the Count function takes over and returns the number of fragments produced by its argument. In this way, the query <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> inside the Count function can be replaced by any function that also produces a sequence of fragments, for example <code>[[MotiveQuery:Language_Reference#Rings | Rings()]]</code>.

Finally, streams of fragments can be combined. For example, let’s say we want to find all pairs of calcium atoms that are no further than 4A within each other. This can be achieved using the query <code>Near(4, Atoms('Ca'), Atoms('Ca'))</code>. So this query takes as the input two identical streams of calcium atoms and for each pair of them determines if the atoms are closer than 4A to each other. For each pair that satisfies this condition, a new fragment from the 2 atoms is created. Therefore, the result of the above <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code> query is a stream of sets of atoms (fragments) that each contain two calcium atoms that are no further than 4A from each other:

[[Image:Near.png|center|600px]]

With these basic types queries outline in the previous paragraphs, the sky's the limit. Due to the composable nature of the language if a new type of motif emerges, only a single function needs to be added to the language for it to work with all its other parts. As an example, assume we didn’t know that proteins had secondary structure called “sheet” and we just discovered it and a fancy algorithm to identify these "sheets". Now we would be interested in how this new type of protein substructure interacts with other parts of the molecule. All that would be needed is to add a function called <code>[[MotiveQuery:Language_Reference#Sheets | Sheets()]]</code> to the language and immediately we would be able to analyze and filter it’s neighborhood using the functions <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code> and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.

===A More Formal Description===
There are two basic data structures that the language is built upon. These are:
* '''Fragment'''. A fragment is simple an arbitrary set of atoms.
* '''Fragment Sequence'''. A sequence of fragments. In mathematical terms, can be understood as a "set of fragments" which is another way of saying "set of sets of atoms".

And on these data structures, there are three basic types of queries:
* '''Generator queries'''. Generator queries, as the name suggests, generate sequences of fragments from the original input. They are the tool that transforms the input molecule into a stream of fragments that can be later modified or combined. Examples of these queries include <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code>, <code>[[MotiveQuery:Language_Reference#Residues | Residues()]]</code>, and <code>[[MotiveQuery:Language_Reference#RegularMotifs | RegularMotifs()]]</code>.
* '''Modifier queries'''. These queries operate on individual fragments and modify them or throw them away. Examples include <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code>, <code>[[MotiveQuery:Language_Reference#ConnectedResidues | ConnectedResidues()]]</code>, and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.
* '''Combinator queries'''. Combinatorial queries take as input two or more sequence of fragments and combine them into a single new sequence that satisfies given criteria. Examples include <code>[[MotiveQuery:Language_Reference#Or | Or()]]</code>, <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code>, and <code>[[MotiveQuery:Language_Reference#Path | Path()]]</code>.

==Example, Revised==
Now that we know the basic building blocks of the language, let’s go back to our original example and analyze it:

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

This corresponds to the following process.

# A generator query <code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code> is executed that produces a sequence of fragments that are composed of atoms corresponding to HET residues.
# Next, the original sequence is modified by adding atoms within 3 angstrom from any original atom to each fragment.
# Finally, each fragment in the modified sequence is examined: all “calcium atom fragments” are identified and counted. Only these fragments that contain at least 1 Ca atom are kept.

Graphically:

<code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code>
[[Image:MotiveQuery-Principles-HetResidues.png|none|500px]]

<code>[[MotiveQuery:Language_Reference#AmbientAtoms | .AmbientAtoms(3)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms.png|none|500px]]

<code>[[MotiveQuery:Language_Reference#Filter | .Filter(lambda l: l.Count(Atoms('Ca')) > 0)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms-filter.png|none|500px]]

PatternQuery:Command Line

2014-12-23T14:56:01Z

Dave:

This is help for version 1.0.14.11.28 or newer. The help text for other versions can be viewed using the ''--help'' command when running the application.

=Technical details=
===Where to find MotiveQuery===
'''MotiveQuery''' is freely available online since May 2014 at http://ncbr.muni.cz/MotiveQuery. There is no login requirement for accessing '''MotiveQuery'''.

===What you need in order to run MotiveQuery===
* Up to date internet browser with WebGL support.
* JavaScript enabled.

Check if your browser is [http://get.webgl.org WebGL] and [http://www.enable-javascript.com/ Javascript] compliant.

Note that you can run '''MotiveQuery''' and download the results even if your browser doesn't support WebGL.
WebGL is only necessary for the 3D visualization functionality.

In some older browsers, the interactive user guide which provides help for the GUI interface does not work optimally.

= Running the Offline Service =
-----------------------
The service can be executed using the command (latest .NET Framework required):
<pre>WebChemistry.MotiveQuery.Service.exe workingFolder configuration.json</pre>
In Linux (where available) and MacOS, the latest version the Mono Framework (http://mono-project.com/) must be used to run the application:
<pre>mono WebChemistry.MotiveQuery.Service.exe workingFolder configuration.json</pre>
Alternatively, on Linux and MacOS, an official version of .NET Framework should become available during 2015.

== Configuration ==
The configuration is specified using the JSON format.

=== Configuration Example ===
This is the general shape of the JSON input configuration.
<pre>{
"InputFolders": [
"c:\\TestData\\PDB\\SampleSet1"
],
"Queries": [
{
"Id": "NAGs",
"QueryString": "Residues(\"NAG\")"
},
{
"Id": "MANs",
"QueryString": "Residues('MAN')"
}
],
"StatisticsOnly": false,
"CSAPath": "c:\\data\\csa.dat",
"MaxParallelism": 8
}</pre>

There has to be exactly one configuration file for each validation run. Every value, as well as settings' names, is surrounded in quotation marks (" " or ' '). Backslashes (\) have to be escaped (\\). File system paths can be absolute as well as relative (/ works as well in paths).

=== Attributes ===
* '''InputFolders''' [ String[] ]
: ''A list of folders containing the input structures.''

* '''Queries''' [ [[#QueryInfo_details|QueryInfo]] ]
: ''A list of queries.''

* '''StatisticsOnly''' [ Boolean ]
: ''If `true`, the files with fragments are not exported.''

* '''CSAPath''' [ String ]
: ''Optional path to a file with CSA database that allows the CSA() query to work. The file is a CSV file that must contain the columns `PdbID, SiteNumber, ?, ?, ChainId, ResidueNumber, ...`''

* '''MaxParallelism''' [ Int32 ], Default value = 8
: ''The maximum number of structures that can be processed simultaneously.''

=== Descriptions ===
===== QueryInfo =====
* '''Id''' [ String ]
: ''A unique identifier of the query.''

* '''QueryString''' [ String ]
: ''The query expression.''

== Output Description ==

=== General Structure ===
* '''[WorkingDirectory]''' - ''Working directory of the application.''
:* '''result''' - ''Contains the result of the computation.''
:: '''log.txt''' - ''Contains the console output of the application.''
:: '''status.json''' - ''Contains general information of the computation (running time, version, etc.).''

=== MotiveQuery Specific Structure ===
* '''result''' - ''Folder with computation result''
:* '''query_id''' - ''Folder for each query named by its unique id.''
::* '''fragments''' - ''Folder with fragments stored in PDB format.''
:::: '''data.json''' - ''Information about the result in JSON format.''
:::: '''fragments.csv''' - ''Information about the fragments in CSV format.''
:::: '''metadata_summary.csv''' - ''Information about the metadata (origin organism, EC number, etc.) in CSV format.''
:::: '''structures.csv''' - ''Information about structures that contain the given fragments in CSV format.''
:: '''structures.csv''' - ''Information about all structures that were queried in CSV format.''
:: '''structures.json''' - ''Information about all structures that were queried in JSON format.''
:: '''summary.json''' - ''Summary information (number of found fragments, etc.) about the computation in JSON format.''

PatternQuery:Principles

2014-12-23T05:26:03Z

Dave: /* A More Formal Description */

'''A new paradigm for describing structural fragments in molecules'''

This text describes the basic principles of the '''MotiveQuery''' language for describing structural fragments in molecules. First, the text puts two approaches for identifying molecular fragments in contrast: the imperative approach, and the declarative one, taken by the '''MotiveQuery''' language. Next, basic principles of the language are illustrated on several examples and later described in a more formal way. Finally, the original example is revisited and explained in the terms of the newly introduced concepts.

==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>[[MotiveQuery: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 fragment becomes simply:

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

==Basic Principles of the Language==

===Intuitive Description===

As we've seen in the example above, it is very easy to ''compose'' our ideas about the final shape of the fragment we are interested in. The way this works is that the input molecule is decomposed into a stream of fragments. These streams can then be modified and combined into new streams, which can be modified and combined again.

As an example, take the query <code>Atoms('Ca')</code>. What the '''MotiveQuery''' language does is to extract all calcium atoms from the input molecule and represent them as a stream of sets containing one atom each as illustrated on the image below:

[[Image:MotiveQuery-Principles Atoms(Ca).png|center|600px]]

Now, each element of this stream can be modified, for example to include all atoms 4A within the original calcium atom. Now we have a stream of sets of atoms, where each set contains the original Ca atom and the atoms within the given radius. This would be represented by the query <code>Atoms('Ca').AmbientAtoms(4)</code> and is illustrated on the image bellow:

[[Image:MotiveQuery-Principles Atoms(Ca) surr.png|center|600px]]

In the next step, we might wish to keep only these fragments that contain at least 6 atoms. This is achieved by looking at each fragment, counting the number of atoms and throwing away these fragments that do not meet the criteria. Written as a query, this could be represented as <code>Atoms('Ca').AmbientAtoms(4).Filter(lambda m: m.Count(Atoms()) >= 6)</code>. In the graphical form:

[[Image:MotiveQuery-Principles Atoms(Ca) surr filt.png|center|600px]]

The previous filter query also demonstrates another interesting concept of the language: ability to identify fragments within fragments, which is what the expression <code>m.Count(Atoms())</code> does - the <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> query is executed for each fragment from the original input sequence provided by the expression <code>Atoms('Ca').AmbientAtoms(4)</code>, and creates a new sequence of fragments that each contain a single atom. Then the Count function takes over and returns the number of fragments produced by its argument. In this way, the query <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> inside the Count function can be replaced by any function that also produces a sequence of fragments, for example <code>[[MotiveQuery:Language_Reference#Rings | Rings()]]</code>.

Finally, streams of fragments can be combined. For example, let’s say we want to find all pairs of calcium atoms that are no further than 4A within each other. This can be achieved using the query <code>Near(4, Atoms('Ca'), Atoms('Ca'))</code>. So this query takes as the input two identical streams of calcium atoms and for each pair of them determines if the atoms are closer than 4A to each other. For each pair that satisfies this condition, a new fragment from the 2 atoms is created. Therefore, the result of the above <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code> query is a stream of sets of atoms (fragments) that each contain two calcium atoms that are no further than 4A from each other:

[[Image:Near.png|center|600px]]

With these basic types queries outline in the previous paragraphs, the sky's the limit. Due to the composable nature of the language if a new type of motif emerges, only a single function needs to be added to the language for it to work with all its other parts. As an example, assume we didn’t know that proteins had secondary structure called “sheet” and we just discovered it and a fancy algorithm to identify these "sheets". Now we would be interested in how this new type of protein substructure interacts with other parts of the molecule. All that would be needed is to add a function called <code>[[MotiveQuery:Language_Reference#Sheets | Sheets()]]</code> to the language and immediately we would be able to analyze and filter it’s neighborhood using the functions <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code> and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.

===A More Formal Description===
There are two basic data structures that the language is built upon. These are:
* '''Fragment'''. A fragment is simple an arbitrary set of atoms.
* '''Fragment Sequence'''. A sequence of fragments. In mathematical terms, can be understood as a "set of fragments" which is another way of saying "set of sets of atoms".

And on these data structures, there are three basic types of queries:
* '''Generator queries'''. Generator queries, as the name suggests, generate sequences of fragments from the original input. They are the tool that transforms the input molecule into a stream of fragments that can be later modified or combined. Examples of these queries include <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code>, <code>[[MotiveQuery:Language_Reference#Residues | Residues()]]</code>, and <code>[[MotiveQuery:Language_Reference#RegularMotifs | RegularMotifs()]]</code>.
* '''Modifier queries'''. These queries operate on individual fragments and modify them or throw them away. Examples include <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code>, <code>[[MotiveQuery:Language_Reference#ConnectedResidues | ConnectedResidues()]]</code>, and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.
* '''Combinator queries'''. Combinatorial queries take as input two or more sequence of fragments and combine them into a single new sequence that satisfies given criteria. Examples include <code>[[MotiveQuery:Language_Reference#Or | Or()]]</code>, <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code>, and <code>[[MotiveQuery:Language_Reference#Path | Path()]]</code>.

==Example, Revised==
Now that we know the basic building blocks of the language, let’s go back to our original example and analyze it:

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

This corresponds to the following process.

# A generator query <code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code> is executed that produces a sequence of fragments that are composed of atoms corresponding to HET residues.
# Next, the original sequence is modified by adding atoms within 3 angstrom from any original atom to each fragment.
# Finally, each fragment in the modified sequence is examined: all “calcium atom fragments” are identified and counted. Only these fragments that contain at least 1 Ca atom are kept.

Graphically:

<code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code>
[[Image:MotiveQuery-Principles-HetResidues.png|none|500px]]

<code>[[MotiveQuery:Language_Reference#AmbientAtoms | .AmbientAtoms(3)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms.png|none|500px]]

<code>[[MotiveQuery:Language_Reference#Filter | .Filter(lambda l: l.Count(Atoms('Ca')) > 0)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms-filter.png|none|500px]]

PatternQuery:Principles

2014-12-23T05:25:21Z

Dave: /* A More Formal Description */

'''A new paradigm for describing structural fragments in molecules'''

This text describes the basic principles of the '''MotiveQuery''' language for describing structural fragments in molecules. First, the text puts two approaches for identifying molecular fragments in contrast: the imperative approach, and the declarative one, taken by the '''MotiveQuery''' language. Next, basic principles of the language are illustrated on several examples and later described in a more formal way. Finally, the original example is revisited and explained in the terms of the newly introduced concepts.

==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>[[MotiveQuery: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 fragment becomes simply:

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

==Basic Principles of the Language==

===Intuitive Description===

As we've seen in the example above, it is very easy to ''compose'' our ideas about the final shape of the fragment we are interested in. The way this works is that the input molecule is decomposed into a stream of fragments. These streams can then be modified and combined into new streams, which can be modified and combined again.

As an example, take the query <code>Atoms('Ca')</code>. What the '''MotiveQuery''' language does is to extract all calcium atoms from the input molecule and represent them as a stream of sets containing one atom each as illustrated on the image below:

[[Image:MotiveQuery-Principles Atoms(Ca).png|center|600px]]

Now, each element of this stream can be modified, for example to include all atoms 4A within the original calcium atom. Now we have a stream of sets of atoms, where each set contains the original Ca atom and the atoms within the given radius. This would be represented by the query <code>Atoms('Ca').AmbientAtoms(4)</code> and is illustrated on the image bellow:

[[Image:MotiveQuery-Principles Atoms(Ca) surr.png|center|600px]]

In the next step, we might wish to keep only these fragments that contain at least 6 atoms. This is achieved by looking at each fragment, counting the number of atoms and throwing away these fragments that do not meet the criteria. Written as a query, this could be represented as <code>Atoms('Ca').AmbientAtoms(4).Filter(lambda m: m.Count(Atoms()) >= 6)</code>. In the graphical form:

[[Image:MotiveQuery-Principles Atoms(Ca) surr filt.png|center|600px]]

The previous filter query also demonstrates another interesting concept of the language: ability to identify fragments within fragments, which is what the expression <code>m.Count(Atoms())</code> does - the <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> query is executed for each fragment from the original input sequence provided by the expression <code>Atoms('Ca').AmbientAtoms(4)</code>, and creates a new sequence of fragments that each contain a single atom. Then the Count function takes over and returns the number of fragments produced by its argument. In this way, the query <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> inside the Count function can be replaced by any function that also produces a sequence of fragments, for example <code>[[MotiveQuery:Language_Reference#Rings | Rings()]]</code>.

Finally, streams of fragments can be combined. For example, let’s say we want to find all pairs of calcium atoms that are no further than 4A within each other. This can be achieved using the query <code>Near(4, Atoms('Ca'), Atoms('Ca'))</code>. So this query takes as the input two identical streams of calcium atoms and for each pair of them determines if the atoms are closer than 4A to each other. For each pair that satisfies this condition, a new fragment from the 2 atoms is created. Therefore, the result of the above <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code> query is a stream of sets of atoms (fragments) that each contain two calcium atoms that are no further than 4A from each other:

[[Image:Near.png|center|600px]]

With these basic types queries outline in the previous paragraphs, the sky's the limit. Due to the composable nature of the language if a new type of motif emerges, only a single function needs to be added to the language for it to work with all its other parts. As an example, assume we didn’t know that proteins had secondary structure called “sheet” and we just discovered it and a fancy algorithm to identify these "sheets". Now we would be interested in how this new type of protein substructure interacts with other parts of the molecule. All that would be needed is to add a function called <code>[[MotiveQuery:Language_Reference#Sheets | Sheets()]]</code> to the language and immediately we would be able to analyze and filter it’s neighborhood using the functions <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code> and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.

===A More Formal Description===
There are two basic data structures that the language is built upon. These are:
* '''Fragment'''. A fragment is simple an arbitrary set of atoms.
* '''Fragment Sequence'''. A sequence of fragments. In mathematical terms, can be understood as a "set of fragments" which is another way of saying "set of sets of atoms".

And on these data structures, there are three basic types of queries:
* '''Generator queries'''. Generator queries, as the name suggests, generate sequences of fragments from the original input. They are the tool that transforms the input molecule into a stream of fragments that can be later modified or combined. Examples of these queries include <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code>, <code>[[MotiveQuery:Language_Reference#Residues | Residues()]]</code>, and <code>[[MotiveQuery:Language_Reference#RegularMotifs | RegularMotifs()]]</code>.
* '''Modifier queries'''. These queries operate on individual fragments and modify them or throw them away. Examples include <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code>, <code>[[MotiveQuery:Language_Reference#ConnectedResidues | ConnectedResidues()]]</code>, and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.
* '''Combinator queries'''. Combinatorial queries take as input two or more sequence of fragments and combine them into a single new sequence that satisfies given criteria. Examples include <code>[[MotiveQuery:Language_Reference#Or | Or()]]</code>, <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code>, and <code>[[MotiveQuery:Language_Reference#Star | Star()]]</code>.

==Example, Revised==
Now that we know the basic building blocks of the language, let’s go back to our original example and analyze it:

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

This corresponds to the following process.

# A generator query <code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code> is executed that produces a sequence of fragments that are composed of atoms corresponding to HET residues.
# Next, the original sequence is modified by adding atoms within 3 angstrom from any original atom to each fragment.
# Finally, each fragment in the modified sequence is examined: all “calcium atom fragments” are identified and counted. Only these fragments that contain at least 1 Ca atom are kept.

Graphically:

<code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code>
[[Image:MotiveQuery-Principles-HetResidues.png|none|500px]]

<code>[[MotiveQuery:Language_Reference#AmbientAtoms | .AmbientAtoms(3)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms.png|none|500px]]

<code>[[MotiveQuery:Language_Reference#Filter | .Filter(lambda l: l.Count(Atoms('Ca')) > 0)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms-filter.png|none|500px]]

PatternQuery:Language Reference

2014-12-17T20:23:38Z

Dave:

== Introduction ==

MotiveQuery (MQ) is a user friendly chemical language primarily designed for defining structural fragments. MQ combines the clarity and brevity of programming languages with the versatility of natural language, aiming for an efficient inclusion of chemical and biochemical knowledge into the definition of structural fragments. MQ allows definitions based on chemical connectivity and three-dimensional structure at the same time. Additionally, in the case of molecules based on residue chains (such as proteins, nucleic acids, saccharides, etc.), MQ allows the user to include any amount of information regarding the residue level structure directly into the definition of the fragments.

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 '''<code>FragmentSeq</code>''' while other return '''<code>Fragment</code>'''.
* '''<code>Fragment</code>''' is a set of atoms.
* '''<code>FragmentSeq</code>''' is a sequence of '''<code>Fragment</code>''' (the sets of atoms).

When a molecule is queried, say using the expression <code>Rings(5 * ["C"] + ["O"])</code> a sequences of fragments each containing 6 atoms (5 C and 1 O) is returned. However, some functions such as <code>Filter</code> need to operate on a single fragment (the set of atoms) - not the whole sequences. The query <code>Filter(Residues(), lambda r: r.Count(Atoms()) > 10)</code> first finds all residue '''<code>Fragments</code>''' (sequence) and then passes every single '''<code>Fragment</code>''' (set of atoms) to a function that counts the atoms in the fragment 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 <code>MQ.Execute</code> 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.

<pre>q = Atoms("Zn").ConnectedAtoms(2)
MQ.Execute(q)</pre>
: ''This command finds all fragments specified by the query q in all loaded structures.''

<pre>MQ.Execute(Residues("HEM"), [ Session.StructureMap["1tqn"], Session.StructureMap["2wer"] ])</pre>
: ''This command finds all HEM residues in structures 1tqn and 2wer (provided structures with these names are loaded).''

<pre>q = AtomSimilarity(Fragment("model"), Fragment("1gtz_0"))
MQ.Execute(q)</pre>
: ''This command computes the atom similarity (Jaccard coefficient) for structures model and 1gtz_0.''

<pre>q = ResidueSimilarity(Fragment("model"), Current())
MQ.Execute(q, Session.Structures)</pre>
: ''This command computes the residue similarity (Jaccard coefficient) for the structure with id 'model' (which is loaded using the Fragment 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 ===
<code>AminoAcids() -> Residues</code> 
''Sequence of all residues with the 20 basic amino acid names.'' 
;Options
: ChargeType: String = "" - ''Specify type of the charge. Allowed values: Positive, Negative, Aromatic, Polar, NonPolar.''
;Examples
: <code>AminoAcids()</code>
:: ''All amino acids.''
: <code>AminoAcids(ChargeType = "Polar")</code>
:: ''Amino acids with polar charge.''
----
=== AtomIdRange ===
<code>AtomIdRange(minId: Integer, maxId: ?Integer) -> Atoms</code> 
''Sequence of atoms with minId <= atomId <= maxId.'' 
;Arguments
: minId: Integer - ''Minimum id.''
: maxId: ?Integer - ''Maximum id. If not specified, maxId = minId.''
;Examples
: <code>AtomIdRange(152, 161)</code>
:: ''Returns all atoms with id between 152 and 161 inclusive.''
----
=== AtomIds ===
<code>AtomIds(ids: Integer+) -> Atoms</code> 
''Sequence of atoms with specified identifiers.'' 
;Arguments
: ids: Integer+ - ''Identifiers.''
;Examples
: <code>AtomIds(1, 2, 3)</code>
:: ''Returns atoms with ids 1, 2, 3.''
----
=== AtomNames ===
<code>AtomNames(names: String+) -> Atoms</code> 
''Sequence of atoms with specified names.'' 
;Arguments
: names: String+ - ''Allowed names.''
;Examples
: <code>AtomNames("O1","NH1")</code>
:: ''Returns all atoms with names O1 or NH1.''
----
=== Atoms ===
<code>Atoms(symbols: String*) -> Atoms</code> 
''Sequence of atoms with specified element symbols. If no symbols are specified, yields all atoms one by one.'' 
;Arguments
: symbols: String* - ''Allowed element symbols.''
;Examples
: <code>Atoms("Zn","Ca")</code>
:: ''Returns all atoms with element symbol Zn or Ca''
----
=== Helices ===
<code>Helices() -> FragmentSeq</code> 
''Returns all helices. This assumes the information about helices was present in the input structure.'' 
;Examples
: <code>Helices()</code>
:: ''Returns all helices.''
----
=== HetResidues ===
<code>HetResidues() -> Residues</code> 
''Sequence of all residues that contain HET atoms.'' 
;Options
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
;Examples
: <code>HetResidues()</code>
:: ''Returns all residues that contain HET atoms (ignores water).''
: <code>HetResidues(NoWaters=False)</code>
:: ''Returns all residues that contain HET atoms (includes water).''
----
=== Chains ===
<code>Chains(identifiers: Value*) -> FragmentSeq</code> 
''Splits the structures into chains. If no identifiers are specified, all chains are returned.'' 
;Arguments
: identifiers: Value* - ''Chain identifiers.''
;Examples
: <code>Chains()</code>
:: ''Returns all chains.''
: <code>Chains("")</code>
:: ''Returns chains without specific identifier.''
: <code>Chains("A", "B")</code>
:: ''Returns chains A and B.''
----
=== Named ===
<code>Named(fragments: FragmentSeq) -> FragmentSeq</code> 
'''Names' the fragment by its lowest atom id.'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to name.''
;Examples
: <code>Atoms("Zn").Named().AmbientAtoms(7)</code>
:: ''When exported, the result files will have names in the format '[parent id]_[pseudorandom number]_[zn atomid]'. If the Named function was not used, the name would be just '[parent id]_[pseudorandom number]'.''
----
=== NotAminoAcids ===
<code>NotAminoAcids() -> Residues</code> 
''Sequence of all residues that are not any of the 20 basic amino acids.'' 
;Options
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
;Examples
: <code>NotAminoAcids()</code>
:: ''Returns all residues that are not amino acids.''
----
=== NotAtomIds ===
<code>NotAtomIds(ids: Integer+) -> Atoms</code> 
''Sequence of atoms that do not have specified identifiers.'' 
;Arguments
: ids: Integer+ - ''Identifiers.''
;Examples
: <code>NotAtomIds(1, 2, 3)</code>
:: ''Returns atoms that do not have id 1, 2, nor 3.''
----
=== NotAtomNames ===
<code>NotAtomNames(names: String+) -> Atoms</code> 
''Sequence of atoms that do not have a specified name.'' 
;Arguments
: names: String+ - ''Forbidden names.''
;Examples
: <code>NotAtomNames("O4")</code>
:: ''Returns all atoms that are not called O4.''
----
=== NotAtoms ===
<code>NotAtoms(symbols: String+) -> Atoms</code> 
''Sequence of atoms that are not particular elements.'' 
;Arguments
: symbols: String+ - ''Forbidden element symbols.''
;Examples
: <code>NotAtoms("O")</code>
:: ''Returns all atoms that are not O.''
----
=== NotResidues ===
<code>NotResidues(names: Value+) -> Residues</code> 
''Sequence of residues that are not called by the specified names.'' 
;Arguments
: names: Value+ - ''Forbidden residue names.''
;Examples
: <code>NotResidues("THR","CYS")</code>
:: ''Returns all residues that are not THR or CYS.''
----
=== RegularMotifs ===
<code>RegularMotifs(regex: Value) -> FragmentSeq</code> 
''Identifies regular motifs. The protein is split into individual chains and the residues are sorted by their Sequence Number before the motifs are identified. The query does not check if adjacent residues have consecutive Sequence Numbers. The query works in two modes: Amino and Nucleotide, on amino acids and nucleotides respectively. The default mode is 'Amino''' 
;Arguments
: regex: Value - ''Regular expression on one letter abbreviations of amino acids.''
;Options
: Type: String = "Amino" - ''Determines the type of the query. Allowed values: Amino, Nucleotide.''
;Examples
: <code>RegularMotifs("RGD")</code>
:: ''Finds all RGD motifs.''
: <code>RegularMotifs("ACGTU", Type = 'Nucleotide')</code>
:: ''Finds all consecutive occurrences of the ACGTU nucleotides.''
: <code>RegularMotifs(".HC.").Filter(lambda m: m.IsConnected())</code>
:: ''Finds all 4 residue motifs with ?-HIS-CYS-? that are connected.''
----
=== ResidueIdRange ===
<code>ResidueIdRange(chain: String, min: Integer, max: ?Integer) -> Residues</code> 
''Sequence of residues with specific chain and min <= sequence number <= max.'' 
;Arguments
: chain: String - ''Chain identifier. Case sensitive (a != A).''
: min: Integer - ''Minimum sequence number.''
: max: ?Integer - ''Maximum sequence number. If not specified, max = min.''
;Examples
: <code>ResidueIdRange("A", 161, 165)</code>
:: ''Returns all residues on chain A with seq. number between 161 and 165 inclusive.''
----
=== ResidueIds ===
<code>ResidueIds(ids: String+) -> Residues</code> 
''Sequence of residues with specific identifiers. If the structure does not contain a residue with the given identifier, it is skipped.'' 
;Arguments
: ids: String+ - ''One or more identifiers in the format 'NUMBER [CHAIN] [i:INSERTIONCODE]' (parameters in [] are optional, for example '175 i:12' or '143 B'). Case sensitive (a != A).''
;Examples
: <code>ResidueIds("132 A", "178 A")</code>
:: ''Returns residues A 123 and A 178 (provided the input structure contains them).''
----
=== Residues ===
<code>Residues(names: String*) -> Residues</code> 
''Sequence of residues with specified names. If no names are specified, yields all residues one by one.'' 
;Arguments
: names: String* - ''Allowed residue names.''
;Examples
: <code>Residues("HIS", "CYS")</code>
:: ''Returns all HIS or CYS residues.''
----
=== RingAtoms ===
<code>RingAtoms(atom: Atoms, ring: ?Rings) -> Atoms</code> 
''Returns all rings atoms.'' 
;Arguments
: atom: Atoms - ''Atom types.''
: ring: ?Rings - ''Specific ring.''
;Examples
: <code>RingAtoms(Atoms("C"), Rings(4 * ["C"] + ["O"]))</code>
:: ''Returns all C atoms on a ring with 4C and O.''
----
=== Rings ===
<code>Rings(atoms: Value*) -> Rings</code> 
''Sequence of rings with particular atoms. If no atoms are specified, yields all rings (cycles) one by one. The order of atoms matters.'' 
;Arguments
: atoms: Value* - ''Ring atoms.''
;Examples
: <code>Rings()</code>
:: ''Returns all rings.''
: <code>Rings(5 * ["C"] + ["O"])</code>
:: ''Returns all rings with 5C and 1O atoms.''
: <code>Rings(["C", "C", "N", "C", "N"])</code>
:: ''Returns all rings with C-C-N-C-N atoms.''
: <code>Or(Rings(["C", "C", "N", "C", "N"]), Rings(["C", "C", "C", "N", "N"]))</code>
:: ''Returns all rings with C-C-N-C-N or C-C-C-N-N atoms.''
----
=== Sheets ===
<code>Sheets() -> FragmentSeq</code> 
''Returns all sheets. This assumes the information about sheets was present in the input structure.'' 
;Examples
: <code>Sheets()</code>
:: ''Returns all sheets.''
 
== Advanced Query Functions ==
''Advanced building blocks of the language.''
=== Flatten ===
<code>Flatten(fragments: FragmentSeq, selector: Fragment->FragmentSeq) -> FragmentSeq</code> 
''Converts a sequence of sequence of fragments into a single 'flat' sequence.'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to project.''
: selector: Fragment->FragmentSeq - ''The selector.''
;Examples
: <code>Residues("HIS").Flatten(lambda m: m.Find(Atoms("C")))</code>
:: ''Returns all C atoms on HIS residues.''
----
=== Inside ===
<code>Inside(fragments: FragmentSeq, where: FragmentSeq) -> FragmentSeq</code> 
''Finds fragments within another fragment. Equivalent to where.Flatten(lambda m: m.Find(fragments))'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to find.''
: where: FragmentSeq - ''Where to find them.''
;Examples
: <code>Atoms("C").Inside(Residues("HIS"))</code>
:: ''Returns all C atoms on HIS residues.''
----
=== Or ===
<code>Or(fragments: FragmentSeq+) -> FragmentSeq</code> 
''Merges several fragment sequences into one.'' 
;Arguments
: fragments: FragmentSeq+ - ''Fragments to merge.''
;Examples
: <code>Or(Atoms("Zn").ConnectedResidues(1), Rings())</code>
:: ''Finds all zincs and their connected residues or rings.''
----
=== ToAtoms ===
<code>ToAtoms(fragments: FragmentSeq) -> FragmentSeq</code> 
''Collects all 'inner' fragments and yields all unique atoms one by one.'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to split.''
;Examples
: <code>Residues("HIS").ToAtoms()</code>
:: ''Returns all atoms on HIS residues one by one.''
----
=== ToResidues ===
<code>ToResidues(fragments: FragmentSeq) -> FragmentSeq</code> 
''Collects all 'inner' fragments and yields all unique residues one by one. The residues contain only the atoms that have been yielded by the inner query.'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to split.''
;Examples
: <code>Atoms("C").ToResidues()</code>
:: ''Returns all C atoms grouped by residues.''
----
=== Union ===
<code>Union(fragments: FragmentSeq) -> FragmentSeq</code> 
''Collects all 'inner' fragments and yields one created from their unique atoms.'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to merge.''
;Examples
: <code>Rings().Union()</code>
:: ''Creates a single fragment that contains all rings.''
 
== Filter Functions ==
''Functions useful for filtering fragments.''
=== Contains ===
<code>Contains(where: Fragment, what: FragmentSeq) -> Bool</code> 
''Checks if a fragment is contained within another one. Equivalent to where.Count(what) > 0.'' 
;Arguments
: where: Fragment - ''Where to look.''
: what: FragmentSeq - ''What to find.''
;Examples
: <code>HetResidues().Filter(lambda m: m.Contains(Rings(5*['C']+['O'])).Not())</code>
:: ''Returns all HET residues that do not contain a 5CO ring.''
----
=== Count ===
<code>Count(where: Fragment, what: FragmentSeq) -> Integer</code> 
''Counts all occurrences of fragment 'what' in fragment 'where'.'' 
;Arguments
: where: Fragment - ''Where to count it.''
: what: FragmentSeq - ''What fragment to count.''
;Examples
: <code>m.Count(Residues("HIS"))</code>
:: ''Returns the count of HIS residues in the fragment m. Where m is a Fragment (for example when using the Filter function or returned by the ToFragment() function). This example will not work directly and is here to illustrate a concept.''
: <code>Atoms("Zn").ConnectedResidues(1).Filter(lambda m: m.Count(Residues("HIS")) == 2)</code>
:: ''Fragments with Zn atoms and its connected residues with exactly 2 HIS residues.''
----
=== ExecuteIf ===
<code>ExecuteIf(query: FragmentSeq, condition: Fragment->Bool) -> FragmentSeq</code> 
''Executes a query only if the condition is met. Otherwise, return an empty sequence of fragments.'' 
;Arguments
: query: FragmentSeq - ''Query to execute.''
: condition: Fragment->Bool - ''Condition that must be satisfied for the parent structure/fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.Resolution() <= 2.4)</code>
:: ''Returns residues in structures that have resolution lower than 2.4ang.''
: <code>AminoAcids().ExecuteIf(lambda p: p.Count(Atoms('Fe')) > 3)</code>
:: ''Returns all amino acids in structures that have at least 3 Fe atoms.''
----
=== Filter ===
<code>Filter(fragments: FragmentSeq, filter: Fragment->Bool) -> FragmentSeq</code> 
''Filters a sequence of fragments with a given predicate.'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to filter.''
: filter: Fragment->Bool - ''Filter predicate.''
;Examples
: <code>Residues().Filter(lambda m: m.Count(Atoms("C")) >= 3)</code>
:: ''Returns all residues that contain at least 3 C atoms.''
----
=== IsConnected ===
<code>IsConnected(fragment: Fragment) -> Bool</code> 
''Checks if a particular fragment is a connected graph.'' 
;Arguments
: fragment: Fragment - ''A fragment to test.''
;Examples
: <code>Atoms("Zn").AmbientResidues(3).Filter(lambda m: m.IsConnected())</code>
:: ''Finds all fragments with a Zn and residues within 3 ang, where all the ambient residues are connected to the central atom.''
----
=== IsConnectedTo ===
<code>IsConnectedTo(where: Fragment, fragments: FragmentSeq) -> Bool</code> 
''Checks if a particular fragment is connected to any other specified fragment. The fragments must have empty intersection for this function to return true.'' 
;Arguments
: where: Fragment - ''A fragment to test.''
: fragments: FragmentSeq - ''Fragment sequence to test against.''
;Examples
: <code>Atoms().Filter(lambda a: a.IsConnectedTo(Rings()))</code>
:: ''Finds all atoms that are connected to a ring they do not belong to.''
----
=== IsNotConnectedTo ===
<code>IsNotConnectedTo(what: Fragment, fragments: FragmentSeq) -> Bool</code> 
''Checks if a particular fragment is not connected to any other specified fragment. The fragments must have empty intersection for this function to return true.'' 
;Arguments
: what: Fragment - ''A fragment to test.''
: fragments: FragmentSeq - ''Fragment sequence to test against.''
;Examples
: <code>Residues().Filter(lambda r: r.IsNotConnectedTo(Atoms("Ca")))</code>
:: ''Finds all residues that are not connected to Ca atoms. The residue itself can still contain Ca atoms.''
----
=== NearestDistanceTo ===
<code>NearestDistanceTo(where: Fragment, fragments: FragmentSeq) -> Real</code> 
''Finds the distance to a particular fragment.'' 
;Arguments
: where: Fragment - ''A fragment to test.''
: fragments: FragmentSeq - ''Fragment sequence to test against.''
;Examples
: <code>Atoms().Filter(lambda m: m.NearestDistanceTo(Residues("ASP")) >= 5)</code>
:: ''Finds all atoms that are at least 5 (angstroms) away from any ASP residue.''
----
=== SeqCount ===
<code>SeqCount(what: FragmentSeq) -> Integer</code> 
''Counts the length of a sequence of motifs.'' 
;Arguments
: what: FragmentSeq - ''What fragment sequence to count.''
;Examples
: <code>Atoms("Zn").AmbientResidues(3).Filter(lambda m: m.Find(Residues("HIS")).SeqCount() > 1)</code>
:: ''Returns a sequence of fragments with Zn atom and residues within 3ang if the fragment contains at least 2 HIS residues.''
 
== Topology Functions ==
''Functions that rely on the topology of fragments.''
=== ConnectedAtoms ===
<code>ConnectedAtoms(fragment: FragmentSeq, n: Integer) -> FragmentSeq</code> 
''Surrounds the inner fragment by n layers of atoms.'' 
;Arguments
: fragment: FragmentSeq - ''Basic fragment.''
: n: Integer - ''Number of atom layers to connect.''
;Options
: YieldNamedDuplicates: Bool = False - ''Yield duplicate fragments if they have a different name.''
;Examples
: <code>Residues("MAN").ConnectedAtoms(2)</code>
:: ''Finds all MAN residues and then adds two connected levels of atoms to them.''
----
=== ConnectedResidues ===
<code>ConnectedResidues(fragment: FragmentSeq, n: Integer) -> FragmentSeq</code> 
''Surrounds the inner fragment by n layers of residues.'' 
;Arguments
: fragment: FragmentSeq - ''Basic fragment.''
: n: Integer - ''Number of residue layers to connect.''
;Options
: YieldNamedDuplicates: Bool = False - ''Yield duplicate fragments if they have a different name.''
;Examples
: <code>Atoms("Zn").ConnectedResidues(1)</code>
:: ''Finds all Zn atoms and adds all residues that are connected to them.''
----
=== Path ===
<code>Path(fragments: FragmentSeq+) -> FragmentSeq</code> 
''Creates a new fragment from 'connected' parts.'' 
;Arguments
: fragments: FragmentSeq+ - ''Fragments to path.''
;Examples
: <code>Path(Atoms("O"), Atoms("C"), Atoms("O"))</code>
:: ''Finds fragments with two O and one C atoms where the C atoms is connected to the O ones.''
----
=== Star ===
<code>Star(center: FragmentSeq, fragments: FragmentSeq+) -> FragmentSeq</code> 
''Creates a new fragment from a central one and connected parts.'' 
;Arguments
: center: FragmentSeq - ''Center fragment.''
: fragments: FragmentSeq+ - ''Fragments to chain.''
;Examples
: <code>Star(Atoms("C"), Atoms("O"), Atoms("O"))</code>
:: ''Finds fragments with two O atoms and one C atom in the center.''
: <code>Atoms("C").Star(Atoms("O"), Atoms("O"))</code>
:: ''Finds fragments with two O atoms and one C atom in the center.''
 
== Geometry Functions ==
''Functions that rely on the geometry of fragments.''
=== AmbientAtoms ===
<code>AmbientAtoms(fragment: FragmentSeq, r: Number) -> FragmentSeq</code> 
''Surrounds the inner fragment by atoms that within the given radius from the inner fragment.'' 
;Arguments
: fragment: FragmentSeq - ''Basic fragment.''
: r: Number - ''Radius.''
;Options
: ExcludeBase: Bool = False - ''Exclude the central original fragment.''
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
: YieldNamedDuplicates: Bool = False - ''Yield duplicate fragments if they have a different name.''
;Examples
: <code>Atoms("Fe").AmbientAtoms(4)</code>
:: ''Finds Fe atoms and all atoms within 4 (angstroms) from each of them.''
----
=== AmbientResidues ===
<code>AmbientResidues(fragment: FragmentSeq, r: Number) -> FragmentSeq</code> 
''Surrounds the inner fragment by residues that have at least one atom within the given radius from the inner fragment.'' 
;Arguments
: fragment: FragmentSeq - ''Basic fragment.''
: r: Number - ''Radius.''
;Options
: ExcludeBase: Bool = False - ''Exclude the central original fragment.''
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
: YieldNamedDuplicates: Bool = False - ''Yield duplicate fragments if they have a different name.''
;Examples
: <code>Rings(6 * ["C"]).AmbientResidues(4)</code>
:: ''Finds rings with 6C atoms and all residues within 4 (angstroms) from each of them.''
----
=== Cluster ===
<code>Cluster(r: Number, fragments: FragmentSeq+) -> FragmentSeq</code> 
''Clusters all fragments that are pairwise closer than r (angstroms).'' 
;Arguments
: r: Number - ''Maximum distance between two fragments in the cluster.''
: fragments: FragmentSeq+ - ''Fragments to cluster.''
;Examples
: <code>Cluster(4, Atoms("Ca"), Rings(5 * ["C"] + ["O"]))</code>
:: ''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 ===
<code>Filled(fragment: FragmentSeq) -> FragmentSeq</code> 
''Adds all atoms that fall within the circumsphere (with radius multiplied by the factor) of the basic fragment.'' 
;Arguments
: fragment: FragmentSeq - ''Basic fragment.''
;Options
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
: RadiusFactor: Number = 0.75 - ''Circumsphere radius factor.''
;Examples
: <code>Cluster(4, Residues("HIS")).Filled(RadiusFactor = 0.75)</code>
:: ''Finds clusters of HIS residues and all atoms within the circumsphere.''
----
=== Near ===
<code>Near(r: Number, fragments: FragmentSeq+) -> FragmentSeq</code> 
''Clusters all fragments that are pairwise closer than r (angstroms) and checks if the "counts" match.'' 
;Arguments
: r: Number - ''Maximum distance between two sub-fragments in the fragment.''
: fragments: FragmentSeq+ - ''Fragments to 'cluster'.''
;Examples
: <code>Near(4, Atoms("Ca"), Atoms("Ca"), Rings(5 * ["C"] + ["O"]))</code>
:: ''Finds all instance of a single ring with 5C and O atoms and two Ca atoms that are closer than 4 (angstroms).''
 
== Meta-data Functions ==
''Functions dealing with meta-data about structures such as release date or authors.''
=== Authors ===
<code>Authors(fragment: Fragment) -> String</code> 
''Returns authors of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== ECNumbers ===
<code>ECNumbers(fragment: Fragment) -> String</code> 
''Returns Enzymatic Commission numbers assigned to enzymes in the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== EntitySources ===
<code>EntitySources(fragment: Fragment) -> String</code> 
''Returns entity sources of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== ExperimentMethod ===
<code>ExperimentMethod(fragment: Fragment) -> String</code> 
''Get the experiment method. The value is always an upper-case string. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ExperimentMethod() == "INFRARED SPECTROSCOPY")</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== HasAllAuthors ===
<code>HasAllAuthors(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given authors. The comparison is case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllAuthors("Holmes", "Watson"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllECNumbers ===
<code>HasAllECNumbers(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given Enzymatic Commission numbers. It is possible to enter just a number prefix without the '.'. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllECNumbers("3.2.1.18", "3.3"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllEntitySources ===
<code>HasAllEntitySources(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given entity sources. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllEntitySources("GMO", "Natural", "Synthetic"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllHostOrganismGenus ===
<code>HasAllHostOrganismGenus(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given host organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllHostOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllHostOrganismIds ===
<code>HasAllHostOrganismIds(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given host organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllHostOrganismIds("7108", "11244"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllHostOrganisms ===
<code>HasAllHostOrganisms(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given host organism names. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllHostOrganisms("Spodoptera frugiperda", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllKeywords ===
<code>HasAllKeywords(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given keywords. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllKeywords("membrane", "glycoprotein"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllOriginOrganismGenus ===
<code>HasAllOriginOrganismGenus(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given origin organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllOriginOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllOriginOrganismIds ===
<code>HasAllOriginOrganismIds(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given origin organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllOriginOrganismIds("121791", "10090"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllOriginOrganisms ===
<code>HasAllOriginOrganisms(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given origin organism names. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllOriginOrganisms("Nipah virus", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyAuthor ===
<code>HasAnyAuthor(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given authors. The comparison is case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyAuthor("Holmes", "Watson"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyECNumber ===
<code>HasAnyECNumber(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given Enzymatic Commission number. It is possible to enter just a number prefix without the '.'s. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyECNumber("3.2.1.19", "3.3"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyEntitySources ===
<code>HasAnyEntitySources(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given entity sources. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyEntitySources("GMO", "Natural", "Synthetic"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyHostOrganism ===
<code>HasAnyHostOrganism(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given host organism names. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyHostOrganism("Spodoptera frugiperda", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyHostOrganismGenus ===
<code>HasAnyHostOrganismGenus(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given host organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyHostOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyHostOrganismId ===
<code>HasAnyHostOrganismId(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given host organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyHostOrganismId("7108", "11244"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyKeyword ===
<code>HasAnyKeyword(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given keywords. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyKeyword("membrane", "glycoprotein"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyOriginOrganism ===
<code>HasAnyOriginOrganism(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given origin organism names. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyOriginOrganism("Nipah virus", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyOriginOrganismGenus ===
<code>HasAnyOriginOrganismGenus(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given origin organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyOriginOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyOriginOrganismId ===
<code>HasAnyOriginOrganismId(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given origin organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyOriginOrganismId("121791", "10090"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HostOrganismGenus ===
<code>HostOrganismGenus(fragment: Fragment) -> String</code> 
''Returns host organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== HostOrganismIds ===
<code>HostOrganismIds(fragment: Fragment) -> String</code> 
''Returns host organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== HostOrganisms ===
<code>HostOrganisms(fragment: Fragment) -> String</code> 
''Returns host organism names of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== Keywords ===
<code>Keywords(fragment: Fragment) -> String</code> 
''Returns keywords of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== LatestRevisionDate ===
<code>LatestRevisionDate(fragment: Fragment) -> Value</code> 
''Get the latest revision date of the parent structure. The value has to be compared to the DateTime(year, month, day) object. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.LatestRevisionDate() >= DateTime(2008, 1, 1))</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== LatestRevisionYear ===
<code>LatestRevisionYear(fragment: Fragment) -> Integer</code> 
''Get the latest revision year of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.LatestRevisionYear() == 2006)</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== OriginOrganismGenus ===
<code>OriginOrganismGenus(fragment: Fragment) -> String</code> 
''Returns origin organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== OriginOrganismIds ===
<code>OriginOrganismIds(fragment: Fragment) -> String</code> 
''Returns origin organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== OriginOrganisms ===
<code>OriginOrganisms(fragment: Fragment) -> String</code> 
''Returns origin organism names of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== PolymerType ===
<code>PolymerType(fragment: Fragment) -> String</code> 
''Get the polymer type of the structure. Possible values are: NotAssigned, Protein, DNA, RNA, ProteinDNA, ProteinRNA, NucleicAcids, Mixture, Sugar, Other. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.PolymerType() == "ProteinDNA")</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== ProteinStoichiometry ===
<code>ProteinStoichiometry(fragment: Fragment) -> String</code> 
''Get the protein stoichiometry of the parent structure. Possible values are: NotAssigned, Monomer, Homomer, Heteromer. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ProteinStoichiometry() == "Heteromer")</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== ProteinStoichiometryString ===
<code>ProteinStoichiometryString(fragment: Fragment) -> String</code> 
''Get the protein stoichiometry string of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== ReleaseDate ===
<code>ReleaseDate(fragment: Fragment) -> Value</code> 
''Get the release date of the parent structure. The value has to be compared to the DateTime(year, month, day) object. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ReleaseDate() >= DateTime(2008, 1, 1))</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== ReleaseYear ===
<code>ReleaseYear(fragment: Fragment) -> Integer</code> 
''Get the release year of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ReleaseYear() == 2006)</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== Resolution ===
<code>Resolution(fragment: Fragment) -> Real</code> 
''Get the resolution in angstroms of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.Resolution() <= 2.4)</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== Weight ===
<code>Weight(fragment: Fragment) -> Real</code> 
''Get the weight of the molecule in kDa. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.Weight() > 100000.0)</code>
:: ''Returns residues in structures that satisfy the property.''
 
== Miscellaneous Functions ==
''Various useful functions. These function often require a special setup (i.e. only useful in Scripting window or in specific applications).''
=== AminoSequenceString ===
<code>AminoSequenceString(fragment: Fragment) -> String</code> 
''Returns a string of single-letter amino acids contained in the fragment.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: fragment: Fragment - ''Fragment to convert.''
;Examples
: <code>Fragment("1tqn_12").AminoSequenceString()</code>
:: ''Returns a string representing amino acids in the fragment '1tqn_12'.''
: <code>RegularMotifs(Fragment("1tqn_12").AminoSequenceString())</code>
:: ''Returns all regular fragments that correspond to the AMK sequence in 1tqn_12.''
----
=== AtomProperty ===
<code>AtomProperty(atomFragment: Fragment, name: String) -> ?</code> 
''If the property exists and the fragment consists of a single atom, returns the property. Otherwise, returns Nothing.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: atomFragment: Fragment - ''Single atom fragment.''
: name: String - ''Property name.''
;Examples
: <code>a.AtomProperty("charge")</code>
:: ''Gets the 'charge' property of the atom a. Where a is a single atom Fragment. This example will not work directly.''
: <code>Atoms().Filter(lambda a: a.AtomProperty("charge") >= 2)</code>
:: ''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 ===
<code>AtomSimilarity(a: Fragment, b: Fragment) -> Real</code> 
''Computes Jaccard/Tanimoto coefficient on atoms (element symbols) of both structures.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: a: Fragment - ''First fragment.''
: b: Fragment - ''Second fragment.''
;Examples
: <code>AtomSimilarity(Current(),Fragment("1tqn_12"))</code>
:: ''Computes the atom similarity between the current fragment and 1tqn_12. This example can be used in SiteBinder to create a descriptor (assuming a structure with id '1tqn_12' is loaded).''
----
=== CommonAtoms ===
<code>CommonAtoms(modelId: String) -> FragmentSeq</code> 
''Returns a single fragment with atoms common with the model. Properties checked: atom id, element symbol, chain, residue number. This query is useful for example for atom selection in SiteBinder.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: modelId: String - ''Id of the model.''
;Examples
: <code>CommonAtoms("1tqn_12")</code>
:: ''Returns a fragment formed by atoms common with the '1tqn_12' structure.''
----
=== CSA ===
<code>CSA() -> FragmentSeq</code> 
''Entries from Catalytic Site Atlas represented as fragments. Works only if used from the command line version of MotiveQuery and property configured.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Examples
: <code>CSA()</code>
:: ''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 ===
<code>Current() -> Fragment</code> 
''A variable that is assigned by the application environment.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Examples
: <code>AtomSimilarity(Current(), Fragment("model"))</code>
:: ''Returns the atom similarity of the current fragment 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 ===
<code>Descriptor(fragment: Fragment, name: String) -> ?</code> 
''Returns the descriptor. If the descriptor does not exist, 'null' is returned.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: fragment: Fragment - ''Fragment that represents entire structure.''
: name: String - ''Descriptor name.''
;Examples
: <code>Current().Descriptor("similarity") >= 0.75</code>
:: ''Returns True if 'similarity' descriptor of the current fragment is at least 0.75. This example will work for example in SiteBinder's structure selection if the 'similarity' descriptor has been previously defined.''
----
=== DynamicInvoke ===
<code>DynamicInvoke(value: Value, name: String, isProperty: Bool, args: Value) -> Value</code> 
''Dynamically invoke a member. (internal)'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: value: Value - ''InnerQuery.''
: name: String - ''Member name.''
: isProperty: Bool - ''Is this a property.''
: args: Value - ''Array of arguments.''
----
=== Find ===
<code>Find(source: Fragment, fragments: FragmentSeq) -> FragmentSeq</code> 
''Converts the source fragment to a structure and finds fragments within it.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: source: Fragment - ''Where to look.''
: fragments: FragmentSeq - ''Fragments to find.''
;Examples
: <code>AtomSimilarity(Current().Find(NotAtoms("N")).ToFragment(), Fragment("model").Find(NotAtoms("N")).ToFragment())</code>
:: ''Computes the atom similarity of the 'current' and 'model' fragments, but ignores N atoms. This example can be used in SiteBinder to create a descriptor (assuming a structure with id 'model' is loaded).''
----
=== Fragment ===
<code>Fragment(structureName: String) -> Fragment</code> 
''Returns a structure represented as a fragment.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: structureName: String - ''Name of a structure.''
;Examples
: <code>Fragment("1tqn_12")</code>
:: ''Returns the structure '1tqn_12' represented as a fragment. Usable in defining descriptors or in Scripting window (using MQ.Execute).''
----
=== GroupedAtoms ===
<code>GroupedAtoms(symbols: String*) -> FragmentSeq</code> 
''Groups atoms using the element symbol and then returns each group as a single fragment.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: symbols: String* - ''Allowed element symbols.''
;Examples
: <code>GroupedAtoms()</code>
:: ''Returns groups of all atom types. For example if the input has atoms 5xC-1xO, fragments with 5xC and 1xO atoms are returned.''
: <code>GroupedAtoms('C', 'O')</code>
:: ''Returns groups of all atom types. For example if the input has atoms 5xC-1xO-6xH, fragments with 5xC and 1xO atoms are returned (but the H atoms are ignored).''
----
=== ResidueSimilarity ===
<code>ResidueSimilarity(a: Fragment, b: Fragment) -> Real</code> 
''Computes Jaccard/Tanimoto coefficient on residue names of both structures.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: a: Fragment - ''First fragment.''
: b: Fragment - ''Second fragment.''
;Examples
: <code>ResidueSimilarity(Current(), Fragment("1tqn_12"))</code>
:: ''Computes the residue similarity between the current fragment and '1tqn_12'. This example can be used in SiteBinder to create a descriptor (assuming a structure with id '1tqn_12' is loaded).''
----
=== ToFragment ===
<code>ToFragment(fragments: FragmentSeq) -> Fragment</code> 
''Converts a sequence of Fragments (FragmentSeq) to a single Fragment by merging all atoms into a single atom set. The Fragment type is required by some function such as AtomSimilarity.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: fragments: FragmentSeq - ''Fragments to convert.''
;Examples
: <code>Residues("HIS").ToFragment()</code>
:: ''Converts a sequence of HIS residue Fragments to a single Fragment.''
: <code>AtomSimilarity(Current().Find(NotAtoms("N")).ToFragment(), Fragment("model").Find(NotAtoms("N")).ToFragment())</code>
:: ''Computes the atom similarity of the 'current' and 'model' fragments, but ignores N atoms.''
 
== Value Functions ==
''Functions such as addition or comparison of numbers.''
=== Abs ===
<code>Abs(x: Number) -> Number</code> 
''Computes the 'Abs' function of the argument.'' 
;Arguments
: x: Number - ''Argument.''
;Examples
: <code>Abs(x)</code>
:: ''Evaluates the expression.''
----
=== Divide (/) ===
<code>Divide(x: Number, y: Number) -> Number</code> 
''Computes the 'Divide' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x / y</code>
:: ''Evaluates the expression.''
----
=== Equal (==) ===
<code>Equal(x: Value, y: Value) -> Bool</code> 
''Determines the 'Equal' relation between two values.'' 
;Arguments
: x: Value - ''Left argument.''
: y: Value - ''Right argument.''
;Examples
: <code>x == y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== Greater (>) ===
<code>Greater(x: Number, y: Number) -> Bool</code> 
''Determines the 'Greater' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x > y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== GreaterEqual (>=) ===
<code>GreaterEqual(x: Number, y: Number) -> Bool</code> 
''Determines the 'GreaterEqual' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x >= y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== Less (<) ===
<code>Less(x: Number, y: Number) -> Bool</code> 
''Determines the 'Less' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x < y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== LessEqual (<=) ===
<code>LessEqual(x: Number, y: Number) -> Bool</code> 
''Determines the 'LessEqual' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x <= y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== LogicalAnd (&) ===
<code>LogicalAnd(xs: Bool+) -> Bool</code> 
''Computes 'LogicalAnd' of the input values.'' 
;Arguments
: xs: Bool+ - ''Arguments.''
;Examples
: <code>x & y</code>
:: ''Evaluates to True or False based on the values of x and y.''
----
=== LogicalNot (Not) ===
<code>LogicalNot(x: Bool) -> Bool</code> 
''Computes 'LogicalNot' of the input value. This function can be called using the shorthand 'Not'.'' 
;Arguments
: x: Bool - ''Argument.''
;Examples
: <code>LogicalNot(x)</code>
:: ''Evaluates to True or False based on the value of x.''
: <code>x.Not()</code>
:: ''Evaluates to True or False based on the value of x.''
----
=== LogicalOr (|) ===
<code>LogicalOr(xs: Bool+) -> Bool</code> 
''Computes 'LogicalOr' of the input values.'' 
;Arguments
: xs: Bool+ - ''Arguments.''
;Examples
: <code>x | y</code>
:: ''Evaluates to True or False based on the values of x and y.''
----
=== LogicalXor (Xor) ===
<code>LogicalXor(xs: Bool+) -> Bool</code> 
''Computes 'LogicalXor' of the input values. This function can be called using the shorthand 'Xor'.'' 
;Arguments
: xs: Bool+ - ''Arguments.''
;Examples
: <code>LogicalXor(x, y)</code>
:: ''Evaluates to True or False based on the values of x and y.''
: <code>Xor(x, y)</code>
:: ''Evaluates to True or False based on the values of x and y.''
----
=== Minus (-) ===
<code>Minus(x: Number) -> Number</code> 
''Computes the arithmetic negation of the argument.'' 
;Arguments
: x: Number - ''Argument.''
;Examples
: <code>-x</code>
:: ''Arithmetic negation of x.''
----
=== NotEqual (!=) ===
<code>NotEqual(x: Value, y: Value) -> Bool</code> 
''Determines the 'NotEqual' relation between two values.'' 
;Arguments
: x: Value - ''Left argument.''
: y: Value - ''Right argument.''
;Examples
: <code>x != y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== Plus (+) ===
<code>Plus(x: Number, y: Number) -> Number</code> 
''Computes the 'Plus' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x + y</code>
:: ''Evaluates the expression.''
----
=== Power (^) ===
<code>Power(x: Number, y: Number) -> Number</code> 
''Computes the 'Power' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x ^ y</code>
:: ''Evaluates the expression.''
----
=== Subtract (-) ===
<code>Subtract(x: Number, y: Number) -> Number</code> 
''Computes the 'Subtract' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x - y</code>
:: ''Evaluates the expression.''
----
=== Times (*) ===
<code>Times(x: Number, y: Number) -> Number</code> 
''Computes the 'Times' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x * y</code>
:: ''Evaluates the expression.''

PatternQuery:Principles

2014-12-17T03:29:08Z

Dave: /* Example, Part One */

'''A new paradigm for describing structural fragments in molecules'''

This text describes the basic principles of the '''MotiveQuery''' language for describing structural fragments in molecules. First, the text puts two approaches for identifying molecular fragments in contrast: the imperative approach, and the declarative one, taken by the '''MotiveQuery''' language. Next, basic principles of the language are illustrated on several examples and later described in a more formal way. Finally, the original example is revisited and explained in the terms of the newly introduced concepts.

==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>[[MotiveQuery: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 fragment becomes simply:

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

==Basic Principles of the Language==

===Intuitive Description===

As we've seen in the example above, it is very easy to ''compose'' our ideas about the final shape of the fragment we are interested in. The way this works is that the input molecule is decomposed into a stream of fragments. These streams can then be modified and combined into new streams, which can be modified and combined again.

As an example, take the query <code>Atoms('Ca')</code>. What the '''MotiveQuery''' language does is to extract all calcium atoms from the input molecule and represent them as a stream of sets containing one atom each as illustrated on the image below:

[[Image:MotiveQuery-Principles Atoms(Ca).png|center|600px]]

Now, each element of this stream can be modified, for example to include all atoms 4A within the original calcium atom. Now we have a stream of sets of atoms, where each set contains the original Ca atom and the atoms within the given radius. This would be represented by the query <code>Atoms('Ca').AmbientAtoms(4)</code> and is illustrated on the image bellow:

[[Image:MotiveQuery-Principles Atoms(Ca) surr.png|center|600px]]

In the next step, we might wish to keep only these fragments that contain at least 6 atoms. This is achieved by looking at each fragment, counting the number of atoms and throwing away these fragments that do not meet the criteria. Written as a query, this could be represented as <code>Atoms('Ca').AmbientAtoms(4).Filter(lambda m: m.Count(Atoms()) >= 6)</code>. In the graphical form:

[[Image:MotiveQuery-Principles Atoms(Ca) surr filt.png|center|600px]]

The previous filter query also demonstrates another interesting concept of the language: ability to identify fragments within fragments, which is what the expression <code>m.Count(Atoms())</code> does - the <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> query is executed for each fragment from the original input sequence provided by the expression <code>Atoms('Ca').AmbientAtoms(4)</code>, and creates a new sequence of fragments that each contain a single atom. Then the Count function takes over and returns the number of fragments produced by its argument. In this way, the query <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> inside the Count function can be replaced by any function that also produces a sequence of fragments, for example <code>[[MotiveQuery:Language_Reference#Rings | Rings()]]</code>.

Finally, streams of fragments can be combined. For example, let’s say we want to find all pairs of calcium atoms that are no further than 4A within each other. This can be achieved using the query <code>Near(4, Atoms('Ca'), Atoms('Ca'))</code>. So this query takes as the input two identical streams of calcium atoms and for each pair of them determines if the atoms are closer than 4A to each other. For each pair that satisfies this condition, a new fragment from the 2 atoms is created. Therefore, the result of the above <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code> query is a stream of sets of atoms (fragments) that each contain two calcium atoms that are no further than 4A from each other:

[[Image:Near.png|center|600px]]

With these basic types queries outline in the previous paragraphs, the sky's the limit. Due to the composable nature of the language if a new type of motif emerges, only a single function needs to be added to the language for it to work with all its other parts. As an example, assume we didn’t know that proteins had secondary structure called “sheet” and we just discovered it and a fancy algorithm to identify these "sheets". Now we would be interested in how this new type of protein substructure interacts with other parts of the molecule. All that would be needed is to add a function called <code>[[MotiveQuery:Language_Reference#Sheets | Sheets()]]</code> to the language and immediately we would be able to analyze and filter it’s neighborhood using the functions <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code> and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.

===A More Formal Description===
There are two basic data structures that the language is built upon. These are:
* '''Fragment'''. A fragment is simple an arbitrary set of atoms.
* '''Fragment Sequence'''. A sequence of fragments. In mathematical terms, can be understood as a "set of fragments" which is another way of saying "set of sets of atoms".

And on these data structures, there are three basic types of queries:
* '''Generator queries'''. Generator queries, as the name suggests, generate sequences of fragments from the original input. They are the tool that transforms the input molecule into a stream of fragments that can be later modified or combined. Examples of these queries include <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code>, <code>[[MotiveQuery:Language_Reference#Residues | Residues()]]</code>, and <code>[[MotiveQuery:Language_Reference#RegularMotifs | RegularMotifs()]]</code>.
* '''Modifier queries'''. These queries operate on individual fragments and modify them or throw them away. Examples include <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code>, <code>[[MotiveQuery:Language_Reference#ConnectedResidues | ConnectedResidues()]]</code>, and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.
* '''Combinator queries'''. Combinatorial queries take as input two or more sequence of fragments and combine them into a single new sequence that satisfies given criteria. Examples include <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code>, <code>[[MotiveQuery:Language_Reference#Cluster | Cluster()]]</code>, and <code>[[MotiveQuery:Language_Reference#Star | Star()]]</code>.

==Example, Revised==
Now that we know the basic building blocks of the language, let’s go back to our original example and analyze it:

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

This corresponds to the following process.

# A generator query <code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code> is executed that produces a sequence of fragments that are composed of atoms corresponding to HET residues.
# Next, the original sequence is modified by adding atoms within 3 angstrom from any original atom to each fragment.
# Finally, each fragment in the modified sequence is examined: all “calcium atom fragments” are identified and counted. Only these fragments that contain at least 1 Ca atom are kept.

Graphically:

<code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code>
[[Image:MotiveQuery-Principles-HetResidues.png|none|500px]]

<code>[[MotiveQuery:Language_Reference#AmbientAtoms | .AmbientAtoms(3)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms.png|none|500px]]

<code>[[MotiveQuery:Language_Reference#Filter | .Filter(lambda l: l.Count(Atoms('Ca')) > 0)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms-filter.png|none|500px]]

PatternQuery:Principles

2014-12-17T03:28:13Z

Dave: /* Example, Part One */

'''A new paradigm for describing structural fragments in molecules'''

This text describes the basic principles of the '''MotiveQuery''' language for describing structural fragments in molecules. First, the text puts two approaches for identifying molecular fragments in contrast: the imperative approach, and the declarative one, taken by the '''MotiveQuery''' language. Next, basic principles of the language are illustrated on several examples and later described in a more formal way. Finally, the original example is revisited and explained in the terms of the newly introduced concepts.

==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>[[MotiveQuery: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 fragment becomes simply:

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

==Basic Principles of the Language==

===Intuitive Description===

As we've seen in the example above, it is very easy to ''compose'' our ideas about the final shape of the fragment we are interested in. The way this works is that the input molecule is decomposed into a stream of fragments. These streams can then be modified and combined into new streams, which can be modified and combined again.

As an example, take the query <code>Atoms('Ca')</code>. What the '''MotiveQuery''' language does is to extract all calcium atoms from the input molecule and represent them as a stream of sets containing one atom each as illustrated on the image below:

[[Image:MotiveQuery-Principles Atoms(Ca).png|center|600px]]

Now, each element of this stream can be modified, for example to include all atoms 4A within the original calcium atom. Now we have a stream of sets of atoms, where each set contains the original Ca atom and the atoms within the given radius. This would be represented by the query <code>Atoms('Ca').AmbientAtoms(4)</code> and is illustrated on the image bellow:

[[Image:MotiveQuery-Principles Atoms(Ca) surr.png|center|600px]]

In the next step, we might wish to keep only these fragments that contain at least 6 atoms. This is achieved by looking at each fragment, counting the number of atoms and throwing away these fragments that do not meet the criteria. Written as a query, this could be represented as <code>Atoms('Ca').AmbientAtoms(4).Filter(lambda m: m.Count(Atoms()) >= 6)</code>. In the graphical form:

[[Image:MotiveQuery-Principles Atoms(Ca) surr filt.png|center|600px]]

The previous filter query also demonstrates another interesting concept of the language: ability to identify fragments within fragments, which is what the expression <code>m.Count(Atoms())</code> does - the <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> query is executed for each fragment from the original input sequence provided by the expression <code>Atoms('Ca').AmbientAtoms(4)</code>, and creates a new sequence of fragments that each contain a single atom. Then the Count function takes over and returns the number of fragments produced by its argument. In this way, the query <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> inside the Count function can be replaced by any function that also produces a sequence of fragments, for example <code>[[MotiveQuery:Language_Reference#Rings | Rings()]]</code>.

Finally, streams of fragments can be combined. For example, let’s say we want to find all pairs of calcium atoms that are no further than 4A within each other. This can be achieved using the query <code>Near(4, Atoms('Ca'), Atoms('Ca'))</code>. So this query takes as the input two identical streams of calcium atoms and for each pair of them determines if the atoms are closer than 4A to each other. For each pair that satisfies this condition, a new fragment from the 2 atoms is created. Therefore, the result of the above <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code> query is a stream of sets of atoms (fragments) that each contain two calcium atoms that are no further than 4A from each other:

[[Image:Near.png|center|600px]]

With these basic types queries outline in the previous paragraphs, the sky's the limit. Due to the composable nature of the language if a new type of motif emerges, only a single function needs to be added to the language for it to work with all its other parts. As an example, assume we didn’t know that proteins had secondary structure called “sheet” and we just discovered it and a fancy algorithm to identify these "sheets". Now we would be interested in how this new type of protein substructure interacts with other parts of the molecule. All that would be needed is to add a function called <code>[[MotiveQuery:Language_Reference#Sheets | Sheets()]]</code> to the language and immediately we would be able to analyze and filter it’s neighborhood using the functions <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code> and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.

===A More Formal Description===
There are two basic data structures that the language is built upon. These are:
* '''Fragment'''. A fragment is simple an arbitrary set of atoms.
* '''Fragment Sequence'''. A sequence of fragments. In mathematical terms, can be understood as a "set of fragments" which is another way of saying "set of sets of atoms".

And on these data structures, there are three basic types of queries:
* '''Generator queries'''. Generator queries, as the name suggests, generate sequences of fragments from the original input. They are the tool that transforms the input molecule into a stream of fragments that can be later modified or combined. Examples of these queries include <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code>, <code>[[MotiveQuery:Language_Reference#Residues | Residues()]]</code>, and <code>[[MotiveQuery:Language_Reference#RegularMotifs | RegularMotifs()]]</code>.
* '''Modifier queries'''. These queries operate on individual fragments and modify them or throw them away. Examples include <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code>, <code>[[MotiveQuery:Language_Reference#ConnectedResidues | ConnectedResidues()]]</code>, and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.
* '''Combinator queries'''. Combinatorial queries take as input two or more sequence of fragments and combine them into a single new sequence that satisfies given criteria. Examples include <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code>, <code>[[MotiveQuery:Language_Reference#Cluster | Cluster()]]</code>, and <code>[[MotiveQuery:Language_Reference#Star | Star()]]</code>.

==Example, Revised==
Now that we know the basic building blocks of the language, let’s go back to our original example and analyze it:

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

This corresponds to the following process.

# A generator query <code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code> is executed that produces a sequence of fragments that are composed of atoms corresponding to HET residues.
# Next, the original sequence is modified by adding atoms within 3 angstrom from any original atom to each fragment.
# Finally, each fragment in the modified sequence is examined: all “calcium atom fragments” are identified and counted. Only these fragments that contain at least 1 Ca atom are kept.

Graphically:

<code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code>
[[Image:MotiveQuery-Principles-HetResidues.png|none|500px]]

<code>[[MotiveQuery:Language_Reference#AmbientAtoms | .AmbientAtoms(3)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms.png|none|500px]]

<code>[[MotiveQuery:Language_Reference#Filter | .Filter(lambda l: l.Count(Atoms('Ca')) > 0)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms-filter.png|none|500px]]

PatternQuery:Principles

2014-12-17T03:24:27Z

Dave: /* Example, Revised */

'''A new paradigm for describing structural fragments in molecules'''

This text describes the basic principles of the '''MotiveQuery''' language for describing structural fragments in molecules. First, the text puts two approaches for identifying molecular fragments in contrast: the imperative approach, and the declarative one, taken by the '''MotiveQuery''' language. Next, basic principles of the language are illustrated on several examples and later described in a more formal way. Finally, the original example is revisited and explained in the terms of the newly introduced concepts.

==Example, Part One==
'''Goal: Find all HET residues in a protein.'''

Let’s assume we have loaded a protein stored in a PDB or mmCIF file with correctly annotated HET groups.

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>[[MotiveQuery: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 fragment becomes simply:

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

==Basic Principles of the Language==

===Intuitive Description===

As we've seen in the example above, it is very easy to ''compose'' our ideas about the final shape of the fragment we are interested in. The way this works is that the input molecule is decomposed into a stream of fragments. These streams can then be modified and combined into new streams, which can be modified and combined again.

As an example, take the query <code>Atoms('Ca')</code>. What the '''MotiveQuery''' language does is to extract all calcium atoms from the input molecule and represent them as a stream of sets containing one atom each as illustrated on the image below:

[[Image:MotiveQuery-Principles Atoms(Ca).png|center|600px]]

Now, each element of this stream can be modified, for example to include all atoms 4A within the original calcium atom. Now we have a stream of sets of atoms, where each set contains the original Ca atom and the atoms within the given radius. This would be represented by the query <code>Atoms('Ca').AmbientAtoms(4)</code> and is illustrated on the image bellow:

[[Image:MotiveQuery-Principles Atoms(Ca) surr.png|center|600px]]

In the next step, we might wish to keep only these fragments that contain at least 6 atoms. This is achieved by looking at each fragment, counting the number of atoms and throwing away these fragments that do not meet the criteria. Written as a query, this could be represented as <code>Atoms('Ca').AmbientAtoms(4).Filter(lambda m: m.Count(Atoms()) >= 6)</code>. In the graphical form:

[[Image:MotiveQuery-Principles Atoms(Ca) surr filt.png|center|600px]]

The previous filter query also demonstrates another interesting concept of the language: ability to identify fragments within fragments, which is what the expression <code>m.Count(Atoms())</code> does - the <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> query is executed for each fragment from the original input sequence provided by the expression <code>Atoms('Ca').AmbientAtoms(4)</code>, and creates a new sequence of fragments that each contain a single atom. Then the Count function takes over and returns the number of fragments produced by its argument. In this way, the query <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> inside the Count function can be replaced by any function that also produces a sequence of fragments, for example <code>[[MotiveQuery:Language_Reference#Rings | Rings()]]</code>.

Finally, streams of fragments can be combined. For example, let’s say we want to find all pairs of calcium atoms that are no further than 4A within each other. This can be achieved using the query <code>Near(4, Atoms('Ca'), Atoms('Ca'))</code>. So this query takes as the input two identical streams of calcium atoms and for each pair of them determines if the atoms are closer than 4A to each other. For each pair that satisfies this condition, a new fragment from the 2 atoms is created. Therefore, the result of the above <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code> query is a stream of sets of atoms (fragments) that each contain two calcium atoms that are no further than 4A from each other:

[[Image:Near.png|center|600px]]

With these basic types queries outline in the previous paragraphs, the sky's the limit. Due to the composable nature of the language if a new type of motif emerges, only a single function needs to be added to the language for it to work with all its other parts. As an example, assume we didn’t know that proteins had secondary structure called “sheet” and we just discovered it and a fancy algorithm to identify these "sheets". Now we would be interested in how this new type of protein substructure interacts with other parts of the molecule. All that would be needed is to add a function called <code>[[MotiveQuery:Language_Reference#Sheets | Sheets()]]</code> to the language and immediately we would be able to analyze and filter it’s neighborhood using the functions <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code> and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.

===A More Formal Description===
There are two basic data structures that the language is built upon. These are:
* '''Fragment'''. A fragment is simple an arbitrary set of atoms.
* '''Fragment Sequence'''. A sequence of fragments. In mathematical terms, can be understood as a "set of fragments" which is another way of saying "set of sets of atoms".

And on these data structures, there are three basic types of queries:
* '''Generator queries'''. Generator queries, as the name suggests, generate sequences of fragments from the original input. They are the tool that transforms the input molecule into a stream of fragments that can be later modified or combined. Examples of these queries include <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code>, <code>[[MotiveQuery:Language_Reference#Residues | Residues()]]</code>, and <code>[[MotiveQuery:Language_Reference#RegularMotifs | RegularMotifs()]]</code>.
* '''Modifier queries'''. These queries operate on individual fragments and modify them or throw them away. Examples include <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code>, <code>[[MotiveQuery:Language_Reference#ConnectedResidues | ConnectedResidues()]]</code>, and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.
* '''Combinator queries'''. Combinatorial queries take as input two or more sequence of fragments and combine them into a single new sequence that satisfies given criteria. Examples include <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code>, <code>[[MotiveQuery:Language_Reference#Cluster | Cluster()]]</code>, and <code>[[MotiveQuery:Language_Reference#Star | Star()]]</code>.

==Example, Revised==
Now that we know the basic building blocks of the language, let’s go back to our original example and analyze it:

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

This corresponds to the following process.

# A generator query <code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code> is executed that produces a sequence of fragments that are composed of atoms corresponding to HET residues.
# Next, the original sequence is modified by adding atoms within 3 angstrom from any original atom to each fragment.
# Finally, each fragment in the modified sequence is examined: all “calcium atom fragments” are identified and counted. Only these fragments that contain at least 1 Ca atom are kept.

Graphically:

<code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code>
[[Image:MotiveQuery-Principles-HetResidues.png|none|500px]]

<code>[[MotiveQuery:Language_Reference#AmbientAtoms | .AmbientAtoms(3)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms.png|none|500px]]

<code>[[MotiveQuery:Language_Reference#Filter | .Filter(lambda l: l.Count(Atoms('Ca')) > 0)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms-filter.png|none|500px]]

PatternQuery:Principles

2014-12-17T03:16:42Z

Dave: /* Example, Part One */

'''A new paradigm for describing structural fragments in molecules'''

This text describes the basic principles of the '''MotiveQuery''' language for describing structural fragments in molecules. First, the text puts two approaches for identifying molecular fragments in contrast: the imperative approach, and the declarative one, taken by the '''MotiveQuery''' language. Next, basic principles of the language are illustrated on several examples and later described in a more formal way. Finally, the original example is revisited and explained in the terms of the newly introduced concepts.

==Example, Part One==
'''Goal: Find all HET residues in a protein.'''

Let’s assume we have loaded a protein stored in a PDB or mmCIF file with correctly annotated HET groups.

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>[[MotiveQuery: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 fragment becomes simply:

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

==Basic Principles of the Language==

===Intuitive Description===

As we've seen in the example above, it is very easy to ''compose'' our ideas about the final shape of the fragment we are interested in. The way this works is that the input molecule is decomposed into a stream of fragments. These streams can then be modified and combined into new streams, which can be modified and combined again.

As an example, take the query <code>Atoms('Ca')</code>. What the '''MotiveQuery''' language does is to extract all calcium atoms from the input molecule and represent them as a stream of sets containing one atom each as illustrated on the image below:

[[Image:MotiveQuery-Principles Atoms(Ca).png|center|600px]]

Now, each element of this stream can be modified, for example to include all atoms 4A within the original calcium atom. Now we have a stream of sets of atoms, where each set contains the original Ca atom and the atoms within the given radius. This would be represented by the query <code>Atoms('Ca').AmbientAtoms(4)</code> and is illustrated on the image bellow:

[[Image:MotiveQuery-Principles Atoms(Ca) surr.png|center|600px]]

In the next step, we might wish to keep only these fragments that contain at least 6 atoms. This is achieved by looking at each fragment, counting the number of atoms and throwing away these fragments that do not meet the criteria. Written as a query, this could be represented as <code>Atoms('Ca').AmbientAtoms(4).Filter(lambda m: m.Count(Atoms()) >= 6)</code>. In the graphical form:

[[Image:MotiveQuery-Principles Atoms(Ca) surr filt.png|center|600px]]

The previous filter query also demonstrates another interesting concept of the language: ability to identify fragments within fragments, which is what the expression <code>m.Count(Atoms())</code> does - the <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> query is executed for each fragment from the original input sequence provided by the expression <code>Atoms('Ca').AmbientAtoms(4)</code>, and creates a new sequence of fragments that each contain a single atom. Then the Count function takes over and returns the number of fragments produced by its argument. In this way, the query <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> inside the Count function can be replaced by any function that also produces a sequence of fragments, for example <code>[[MotiveQuery:Language_Reference#Rings | Rings()]]</code>.

Finally, streams of fragments can be combined. For example, let’s say we want to find all pairs of calcium atoms that are no further than 4A within each other. This can be achieved using the query <code>Near(4, Atoms('Ca'), Atoms('Ca'))</code>. So this query takes as the input two identical streams of calcium atoms and for each pair of them determines if the atoms are closer than 4A to each other. For each pair that satisfies this condition, a new fragment from the 2 atoms is created. Therefore, the result of the above <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code> query is a stream of sets of atoms (fragments) that each contain two calcium atoms that are no further than 4A from each other:

[[Image:Near.png|center|600px]]

With these basic types queries outline in the previous paragraphs, the sky's the limit. Due to the composable nature of the language if a new type of motif emerges, only a single function needs to be added to the language for it to work with all its other parts. As an example, assume we didn’t know that proteins had secondary structure called “sheet” and we just discovered it and a fancy algorithm to identify these "sheets". Now we would be interested in how this new type of protein substructure interacts with other parts of the molecule. All that would be needed is to add a function called <code>[[MotiveQuery:Language_Reference#Sheets | Sheets()]]</code> to the language and immediately we would be able to analyze and filter it’s neighborhood using the functions <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code> and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.

===A More Formal Description===
There are two basic data structures that the language is built upon. These are:
* '''Fragment'''. A fragment is simple an arbitrary set of atoms.
* '''Fragment Sequence'''. A sequence of fragments. In mathematical terms, can be understood as a "set of fragments" which is another way of saying "set of sets of atoms".

And on these data structures, there are three basic types of queries:
* '''Generator queries'''. Generator queries, as the name suggests, generate sequences of fragments from the original input. They are the tool that transforms the input molecule into a stream of fragments that can be later modified or combined. Examples of these queries include <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code>, <code>[[MotiveQuery:Language_Reference#Residues | Residues()]]</code>, and <code>[[MotiveQuery:Language_Reference#RegularMotifs | RegularMotifs()]]</code>.
* '''Modifier queries'''. These queries operate on individual fragments and modify them or throw them away. Examples include <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code>, <code>[[MotiveQuery:Language_Reference#ConnectedResidues | ConnectedResidues()]]</code>, and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.
* '''Combinator queries'''. Combinatorial queries take as input two or more sequence of fragments and combine them into a single new sequence that satisfies given criteria. Examples include <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code>, <code>[[MotiveQuery:Language_Reference#Cluster | Cluster()]]</code>, and <code>[[MotiveQuery:Language_Reference#Star | Star()]]</code>.

==Example, Revised==
Now that we know the basic building blocks of the language, let’s go back to our original example and analyze it:

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

This corresponds to the following process.

# A generator query <code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code> is executed that produces a sequence of fragments that are composed of atoms corresponding to HET residues.
# Next, the original sequence is modified by adding atoms within 3 angstrom from any original atom to each fragment.
# Finally, each fragment in the modified sequence is examined: all “calcium atom fragments” are identified and counted. Only these fragments that contain at least 1 Ca atom are kept.

Graphically:

<code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code>.
[[Image:MotiveQuery-Principles-HetResidues.png|center|500px]]

<code>[[MotiveQuery:Language_Reference#AmbientAtoms | .AmbientAtoms(3)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms.png|center|500px]]

<code>[[MotiveQuery:Language_Reference#Filter | .Filter(lambda l: l.Count(Atoms('Ca')) > 0)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms-filter.png|center|500px]]

PatternQuery:Principles

2014-12-17T02:51:56Z

Dave: /* Example, Revised */

'''A new paradigm for describing structural fragments in molecules'''

This text describes the basic principles of the '''MotiveQuery''' language for describing structural fragments in molecules. First, the text puts two approaches for identifying molecular fragments in contrast: the imperative approach, and the declarative one, taken by the '''MotiveQuery''' language. Next, basic principles of the language are illustrated on several examples and later described in a more formal way. Finally, the original example is revisited and explained in the terms of the newly introduced concepts.

==Example, Part One==
'''Goal: Find all HET residues in a protein.'''

Let’s assume we have loaded a protein stored in a PDB or mmCIF file with correctly annotated HET groups.

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 = new 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 = new List()

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

neighborhoodLookup = new NeighborhoodLookup(molecule.Atoms())
result = new 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>[[MotiveQuery: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 fragment becomes just:

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

==Basic Principles of the Language==

===Intuitive Description===

As we've seen in the example above, it is very easy to ''compose'' our ideas about the final shape of the fragment we are interested in. The way this works is that the input molecule is decomposed into a stream of fragments. These streams can then be modified and combined into new streams, which can be modified and combined again.

As an example, take the query <code>Atoms('Ca')</code>. What the '''MotiveQuery''' language does is to extract all calcium atoms from the input molecule and represent them as a stream of sets containing one atom each as illustrated on the image below:

[[Image:MotiveQuery-Principles Atoms(Ca).png|center|600px]]

Now, each element of this stream can be modified, for example to include all atoms 4A within the original calcium atom. Now we have a stream of sets of atoms, where each set contains the original Ca atom and the atoms within the given radius. This would be represented by the query <code>Atoms('Ca').AmbientAtoms(4)</code> and is illustrated on the image bellow:

[[Image:MotiveQuery-Principles Atoms(Ca) surr.png|center|600px]]

In the next step, we might wish to keep only these fragments that contain at least 6 atoms. This is achieved by looking at each fragment, counting the number of atoms and throwing away these fragments that do not meet the criteria. Written as a query, this could be represented as <code>Atoms('Ca').AmbientAtoms(4).Filter(lambda m: m.Count(Atoms()) >= 6)</code>. In the graphical form:

[[Image:MotiveQuery-Principles Atoms(Ca) surr filt.png|center|600px]]

The previous filter query also demonstrates another interesting concept of the language: ability to identify fragments within fragments, which is what the expression <code>m.Count(Atoms())</code> does - the <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> query is executed for each fragment from the original input sequence provided by the expression <code>Atoms('Ca').AmbientAtoms(4)</code>, and creates a new sequence of fragments that each contain a single atom. Then the Count function takes over and returns the number of fragments produced by its argument. In this way, the query <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> inside the Count function can be replaced by any function that also produces a sequence of fragments, for example <code>[[MotiveQuery:Language_Reference#Rings | Rings()]]</code>.

Finally, streams of fragments can be combined. For example, let’s say we want to find all pairs of calcium atoms that are no further than 4A within each other. This can be achieved using the query <code>Near(4, Atoms('Ca'), Atoms('Ca'))</code>. So this query takes as the input two identical streams of calcium atoms and for each pair of them determines if the atoms are closer than 4A to each other. For each pair that satisfies this condition, a new fragment from the 2 atoms is created. Therefore, the result of the above <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code> query is a stream of sets of atoms (fragments) that each contain two calcium atoms that are no further than 4A from each other:

[[Image:Near.png|center|600px]]

With these basic types queries outline in the previous paragraphs, the sky's the limit. Due to the composable nature of the language if a new type of motif emerges, only a single function needs to be added to the language for it to work with all its other parts. As an example, assume we didn’t know that proteins had secondary structure called “sheet” and we just discovered it and a fancy algorithm to identify these "sheets". Now we would be interested in how this new type of protein substructure interacts with other parts of the molecule. All that would be needed is to add a function called <code>[[MotiveQuery:Language_Reference#Sheets | Sheets()]]</code> to the language and immediately we would be able to analyze and filter it’s neighborhood using the functions <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code> and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.

===A More Formal Description===
There are two basic data structures that the language is built upon. These are:
* '''Fragment'''. A fragment is simple an arbitrary set of atoms.
* '''Fragment Sequence'''. A sequence of fragments. In mathematical terms, can be understood as a "set of fragments" which is another way of saying "set of sets of atoms".

And on these data structures, there are three basic types of queries:
* '''Generator queries'''. Generator queries, as the name suggests, generate sequences of fragments from the original input. They are the tool that transforms the input molecule into a stream of fragments that can be later modified or combined. Examples of these queries include <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code>, <code>[[MotiveQuery:Language_Reference#Residues | Residues()]]</code>, and <code>[[MotiveQuery:Language_Reference#RegularMotifs | RegularMotifs()]]</code>.
* '''Modifier queries'''. These queries operate on individual fragments and modify them or throw them away. Examples include <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code>, <code>[[MotiveQuery:Language_Reference#ConnectedResidues | ConnectedResidues()]]</code>, and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.
* '''Combinator queries'''. Combinatorial queries take as input two or more sequence of fragments and combine them into a single new sequence that satisfies given criteria. Examples include <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code>, <code>[[MotiveQuery:Language_Reference#Cluster | Cluster()]]</code>, and <code>[[MotiveQuery:Language_Reference#Star | Star()]]</code>.

==Example, Revised==
Now that we know the basic building blocks of the language, let’s go back to our original example and analyze it:

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

This corresponds to the following process.

# A generator query <code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code> is executed that produces a sequence of fragments that are composed of atoms corresponding to HET residues.
# Next, the original sequence is modified by adding atoms within 3 angstrom from any original atom to each fragment.
# Finally, each fragment in the modified sequence is examined: all “calcium atom fragments” are identified and counted. Only these fragments that contain at least 1 Ca atom are kept.

Graphically:

<code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code>.
[[Image:MotiveQuery-Principles-HetResidues.png|center|500px]]

<code>[[MotiveQuery:Language_Reference#AmbientAtoms | .AmbientAtoms(3)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms.png|center|500px]]

<code>[[MotiveQuery:Language_Reference#Filter | .Filter(lambda l: l.Count(Atoms('Ca')) > 0)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms-filter.png|center|500px]]

PatternQuery:Principles

2014-12-17T02:45:07Z

Dave:

'''A new paradigm for describing structural fragments in molecules'''

This text describes the basic principles of the '''MotiveQuery''' language for describing structural fragments in molecules. First, the text puts two approaches for identifying molecular fragments in contrast: the imperative approach, and the declarative one, taken by the '''MotiveQuery''' language. Next, basic principles of the language are illustrated on several examples and later described in a more formal way. Finally, the original example is revisited and explained in the terms of the newly introduced concepts.

==Example, Part One==
'''Goal: Find all HET residues in a protein.'''

Let’s assume we have loaded a protein stored in a PDB or mmCIF file with correctly annotated HET groups.

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 = new 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 = new List()

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

neighborhoodLookup = new NeighborhoodLookup(molecule.Atoms())
result = new 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>[[MotiveQuery: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 fragment becomes just:

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

==Basic Principles of the Language==

===Intuitive Description===

As we've seen in the example above, it is very easy to ''compose'' our ideas about the final shape of the fragment we are interested in. The way this works is that the input molecule is decomposed into a stream of fragments. These streams can then be modified and combined into new streams, which can be modified and combined again.

As an example, take the query <code>Atoms('Ca')</code>. What the '''MotiveQuery''' language does is to extract all calcium atoms from the input molecule and represent them as a stream of sets containing one atom each as illustrated on the image below:

[[Image:MotiveQuery-Principles Atoms(Ca).png|center|600px]]

Now, each element of this stream can be modified, for example to include all atoms 4A within the original calcium atom. Now we have a stream of sets of atoms, where each set contains the original Ca atom and the atoms within the given radius. This would be represented by the query <code>Atoms('Ca').AmbientAtoms(4)</code> and is illustrated on the image bellow:

[[Image:MotiveQuery-Principles Atoms(Ca) surr.png|center|600px]]

In the next step, we might wish to keep only these fragments that contain at least 6 atoms. This is achieved by looking at each fragment, counting the number of atoms and throwing away these fragments that do not meet the criteria. Written as a query, this could be represented as <code>Atoms('Ca').AmbientAtoms(4).Filter(lambda m: m.Count(Atoms()) >= 6)</code>. In the graphical form:

[[Image:MotiveQuery-Principles Atoms(Ca) surr filt.png|center|600px]]

The previous filter query also demonstrates another interesting concept of the language: ability to identify fragments within fragments, which is what the expression <code>m.Count(Atoms())</code> does - the <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> query is executed for each fragment from the original input sequence provided by the expression <code>Atoms('Ca').AmbientAtoms(4)</code>, and creates a new sequence of fragments that each contain a single atom. Then the Count function takes over and returns the number of fragments produced by its argument. In this way, the query <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> inside the Count function can be replaced by any function that also produces a sequence of fragments, for example <code>[[MotiveQuery:Language_Reference#Rings | Rings()]]</code>.

Finally, streams of fragments can be combined. For example, let’s say we want to find all pairs of calcium atoms that are no further than 4A within each other. This can be achieved using the query <code>Near(4, Atoms('Ca'), Atoms('Ca'))</code>. So this query takes as the input two identical streams of calcium atoms and for each pair of them determines if the atoms are closer than 4A to each other. For each pair that satisfies this condition, a new fragment from the 2 atoms is created. Therefore, the result of the above <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code> query is a stream of sets of atoms (fragments) that each contain two calcium atoms that are no further than 4A from each other:

[[Image:Near.png|center|600px]]

With these basic types queries outline in the previous paragraphs, the sky's the limit. Due to the composable nature of the language if a new type of motif emerges, only a single function needs to be added to the language for it to work with all its other parts. As an example, assume we didn’t know that proteins had secondary structure called “sheet” and we just discovered it and a fancy algorithm to identify these "sheets". Now we would be interested in how this new type of protein substructure interacts with other parts of the molecule. All that would be needed is to add a function called <code>[[MotiveQuery:Language_Reference#Sheets | Sheets()]]</code> to the language and immediately we would be able to analyze and filter it’s neighborhood using the functions <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code> and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.

===A More Formal Description===
There are two basic data structures that the language is built upon. These are:
* '''Fragment'''. A fragment is simple an arbitrary set of atoms.
* '''Fragment Sequence'''. A sequence of fragments. In mathematical terms, can be understood as a "set of fragments" which is another way of saying "set of sets of atoms".

And on these data structures, there are three basic types of queries:
* '''Generator queries'''. Generator queries, as the name suggests, generate sequences of fragments from the original input. They are the tool that transforms the input molecule into a stream of fragments that can be later modified or combined. Examples of these queries include <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code>, <code>[[MotiveQuery:Language_Reference#Residues | Residues()]]</code>, and <code>[[MotiveQuery:Language_Reference#RegularMotifs | RegularMotifs()]]</code>.
* '''Modifier queries'''. These queries operate on individual fragments and modify them or throw them away. Examples include <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code>, <code>[[MotiveQuery:Language_Reference#ConnectedResidues | ConnectedResidues()]]</code>, and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.
* '''Combinator queries'''. Combinatorial queries take as input two or more sequence of fragments and combine them into a single new sequence that satisfies given criteria. Examples include <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code>, <code>[[MotiveQuery:Language_Reference#Cluster | Cluster()]]</code>, and <code>[[MotiveQuery:Language_Reference#Star | Star()]]</code>.

==Example, Revised==
Now that we know the basic building blocks of the language, let’s go back to our original example and analyze it:

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

This corresponds to the following process.

# A generator query <code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code> is executed that produces a sequence of fragments that are composed of atoms corresponding to HET residues.
# Next, the original sequence is modified by adding atoms within 3 angstrom from any original atom to each fragment.
# Finally, each fragment in the modified sequence is examined: all “calcium atom fragments” are identified and counted. Only these fragments that contain at least 1 Ca atom are kept.

Graphically:

<code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code>.
[[Image:MotiveQuery-Principles-HetResidues.png|center|500px]]

<code>[[MotiveQuery:Language_Reference#AmbientAtoms | .AmbientAtoms(3)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms.png|center|500px]]

<code>[[MotiveQuery:Language_Reference#Filter | .Filter(lambda l: l.count(Atoms('Ca')) > 0)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms-filter.png|center|500px]]

PatternQuery:Principles

2014-12-17T02:42:56Z

Dave:

'''A new paradigm for describing structural fragments in molecules'''

This text describes the basic principles of the '''MotiveQuery''' language for describing structural fragments in molecules. First, the text puts two approaches for identifying molecular fragments in contrast: the imperative approach, and the declarative one, taken by the '''MotiveQuery''' language. Next, basic principles of the language are illustrated on several examples and later described in a more formal way. Finally, the original example is revisited and explained in the terms of the newly introduced concepts.

==Example, Part One==
'''Goal: Find all HET residues in a protein.'''

Let’s assume we have loaded a protein stored in a PDB or mmCIF file with correctly annotated HET groups.

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 = new 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 = new List()

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

neighborhoodLookup = new NeighborhoodLookup(molecule.Atoms())
result = new 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>[[MotiveQuery: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 fragment becomes just:

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

==Basic Principles of the Language==

As we've seen in the example above, it is very easy to ''compose'' our ideas about the final shape of the fragment we are interested in. The way this works is that the input molecule is decomposed into a stream of fragments. These streams can then be modified and combined into new streams, which can be modified and combined again.

As an example, take the query <code>Atoms('Ca')</code>. What the '''MotiveQuery''' language does is to extract all calcium atoms from the input molecule and represent them as a stream of sets containing one atom each as illustrated on the image below:

[[Image:MotiveQuery-Principles Atoms(Ca).png|center|600px]]

Now, each element of this stream can be modified, for example to include all atoms 4A within the original calcium atom. Now we have a stream of sets of atoms, where each set contains the original Ca atom and the atoms within the given radius. This would be represented by the query <code>Atoms('Ca').AmbientAtoms(4)</code> and is illustrated on the image bellow:

[[Image:MotiveQuery-Principles Atoms(Ca) surr.png|center|600px]]

In the next step, we might wish to keep only these fragments that contain at least 6 atoms. This is achieved by looking at each fragment, counting the number of atoms and throwing away these fragments that do not meet the criteria. Written as a query, this could be represented as <code>Atoms('Ca').AmbientAtoms(4).Filter(lambda m: m.Count(Atoms()) >= 6)</code>. In the graphical form:

[[Image:MotiveQuery-Principles Atoms(Ca) surr filt.png|center|600px]]

The previous filter query also demonstrates another interesting concept of the language: ability to identify fragments within fragments, which is what the expression <code>m.Count(Atoms())</code> does - the <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> query is executed for each fragment from the original input sequence provided by the expression <code>Atoms('Ca').AmbientAtoms(4)</code>, and creates a new sequence of fragments that each contain a single atom. Then the Count function takes over and returns the number of fragments produced by its argument. In this way, the query <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code> inside the Count function can be replaced by any function that also produces a sequence of fragments, for example <code>[[MotiveQuery:Language_Reference#Rings | Rings()]]</code>.

Finally, streams of fragments can be combined. For example, let’s say we want to find all pairs of calcium atoms that are no further than 4A within each other. This can be achieved using the query <code>Near(4, Atoms('Ca'), Atoms('Ca'))</code>. So this query takes as the input two identical streams of calcium atoms and for each pair of them determines if the atoms are closer than 4A to each other. For each pair that satisfies this condition, a new fragment from the 2 atoms is created. Therefore, the result of the above <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code> query is a stream of sets of atoms (fragments) that each contain two calcium atoms that are no further than 4A from each other:

[[Image:Near.png|center|600px]]

With these basic types queries outline in the previous paragraphs, the sky's the limit. Due to the composable nature of the language if a new type of motif emerges, only a single function needs to be added to the language for it to work with all its other parts. As an example, assume we didn’t know that proteins had secondary structure called “sheet” and we just discovered it and a fancy algorithm to identify these "sheets". Now we would be interested in how this new type of protein substructure interacts with other parts of the molecule. All that would be needed is to add a function called <code>[[MotiveQuery:Language_Reference#Sheets | Sheets()]]</code> to the language and immediately we would be able to analyze and filter it’s neighborhood using the functions <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code> and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.

==Basic Principles, More Formally this Time==
There are two basic data structures that the language is built upon. These are:
* '''Fragment'''. A fragment is simple an arbitrary set of atoms.
* '''Fragment Sequence'''. A sequence of fragments. In mathematical terms, can be understood as a "set of fragments" which is another way of saying "set of sets of atoms".

And on these data structures, there are three basic types of queries:
* '''Generator queries'''. Generator queries, as the name suggests, generate sequences of fragments from the original input. They are the tool that transforms the input molecule into a stream of fragments that can be later modified or combined. Examples of these queries include <code>[[MotiveQuery:Language_Reference#Atoms | Atoms()]]</code>, <code>[[MotiveQuery:Language_Reference#Residues | Residues()]]</code>, and <code>[[MotiveQuery:Language_Reference#RegularMotifs | RegularMotifs()]]</code>.
* '''Modifier queries'''. These queries operate on individual fragments and modify them or throw them away. Examples include <code>[[MotiveQuery:Language_Reference#AmbientAtoms | AmbientAtoms()]]</code>, <code>[[MotiveQuery:Language_Reference#ConnectedResidues | ConnectedResidues()]]</code>, and <code>[[MotiveQuery:Language_Reference#Filter | Filter()]]</code>.
* '''Combinator queries'''. Combinatorial queries take as input two or more sequence of fragments and combine them into a single new sequence that satisfies given criteria. Examples include <code>[[MotiveQuery:Language_Reference#Near | Near()]]</code>, <code>[[MotiveQuery:Language_Reference#Cluster | Cluster()]]</code>, and <code>[[MotiveQuery:Language_Reference#Star | Star()]]</code>.

==Example, Revised==
Now that we know the basic building blocks of the language, let’s go back to our original example and analyze it:

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

This corresponds to the following process.

# A generator query <code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code> is executed that produces a sequence of fragments that are composed of atoms corresponding to HET residues.
# Next, the original sequence is modified by adding atoms within 3 angstrom from any original atom to each fragment.
# Finally, each fragment in the modified sequence is examined: all “calcium atom fragments” are identified and counted. Only these fragments that contain at least 1 Ca atom are kept.

Graphically:

<code>[[MotiveQuery:Language_Reference#HetResidues | HetResidues()]]</code>.
[[Image:MotiveQuery-Principles-HetResidues.png|center|500px]]

<code>[[MotiveQuery:Language_Reference#AmbientAtoms | .AmbientAtoms(3)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms.png|center|500px]]

<code>[[MotiveQuery:Language_Reference#Filter | .Filter(lambda l: l.count(Atoms('Ca')) > 0)]]</code>
[[Image:MotiveQuery-Principles-AmbientAtoms-filter.png|center|500px]]

PatternQuery:Language Reference

2014-12-15T22:08:42Z

Dave:

== Introduction ==

MotiveQuery (MQ) is a user friendly chemical language primarily designed for defining structural fragments. MQ combines the clarity and brevity of programming languages with the versatility of natural language, aiming for an efficient inclusion of chemical and biochemical knowledge into the definition of structural fragments. MQ allows definitions based on chemical connectivity and three-dimensional structure at the same time. Additionally, in the case of molecules based on residue chains (such as proteins, nucleic acids, saccharides, etc.), MQ allows the user to include any amount of information regarding the residue level structure directly into the definition of the fragments.

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 '''<code>FragmentSeq</code>''' while other return '''<code>Fragment</code>'''.
* '''<code>Fragment</code>''' is a set of atoms.
* '''<code>FragmentSeq</code>''' is a sequence of '''<code>Fragment</code>''' (the sets of atoms).

When a molecule is queried, say using the expression <code>Rings(5 * ["C"] + ["O"])</code> a sequences of fragments each containing 6 atoms (5 C and 1 O) is returned. However, some functions such as <code>Filter</code> need to operate on a single fragment (the set of atoms) - not the whole sequences. The query <code>Filter(Residues(), lambda r: r.Count(Atoms()) > 10)</code> first finds all residue '''<code>Fragments</code>''' (sequence) and then passes every single '''<code>Fragment</code>''' (set of atoms) to a function that counts the atoms in the fragment 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 <code>MQ.Execute</code> 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.

<pre>q = Atoms("Zn").ConnectedAtoms(2)
MQ.Execute(q)</pre>
: ''This command finds all fragments specified by the query q in all loaded structures.''

<pre>MQ.Execute(Residues("HEM"), [ Session.StructureMap["1tqn"], Session.StructureMap["2wer"] ])</pre>
: ''This command finds all HEM residues in structures 1tqn and 2wer (provided structures with these names are loaded).''

<pre>q = AtomSimilarity(Fragment("model"), Fragment("1gtz_0"))
MQ.Execute(q)</pre>
: ''This command computes the atom similarity (Jaccard coefficient) for structures model and 1gtz_0.''

<pre>q = ResidueSimilarity(Fragment("model"), Current())
MQ.Execute(q, Session.Structures)</pre>
: ''This command computes the residue similarity (Jaccard coefficient) for the structure with id 'model' (which is loaded using the Fragment 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 ===
<code>AminoAcids() -> Residues</code> 
''Sequence of all residues with the 20 basic amino acid names.'' 
;Options
: ChargeType: String = "" - ''Specify type of the charge. Allowed values: Positive, Negative, Aromatic, Polar, NonPolar.''
;Examples
: <code>AminoAcids()</code>
:: ''All amino acids.''
: <code>AminoAcids(ChargeType = "Polar")</code>
:: ''Amino acids with polar charge.''
----
=== AtomIdRange ===
<code>AtomIdRange(minId: Integer, maxId: ?Integer) -> Atoms</code> 
''Sequence of atoms with minId <= atomId <= maxId.'' 
;Arguments
: minId: Integer - ''Minimum id.''
: maxId: ?Integer - ''Maximum id. If not specified, maxId = minId.''
;Examples
: <code>AtomIdRange(152, 161)</code>
:: ''Returns all atoms with id between 152 and 161 inclusive.''
----
=== AtomIds ===
<code>AtomIds(ids: Integer+) -> Atoms</code> 
''Sequence of atoms with specified identifiers.'' 
;Arguments
: ids: Integer+ - ''Identifiers.''
;Examples
: <code>AtomIds(1, 2, 3)</code>
:: ''Returns atoms with ids 1, 2, 3.''
----
=== AtomNames ===
<code>AtomNames(names: String+) -> Atoms</code> 
''Sequence of atoms with specified names.'' 
;Arguments
: names: String+ - ''Allowed names.''
;Examples
: <code>AtomNames("O1","NH1")</code>
:: ''Returns all atoms with names O1 or NH1.''
----
=== Atoms ===
<code>Atoms(symbols: String*) -> Atoms</code> 
''Sequence of atoms with specified element symbols. If no symbols are specified, yields all atoms one by one.'' 
;Arguments
: symbols: String* - ''Allowed element symbols.''
;Examples
: <code>Atoms("Zn","Ca")</code>
:: ''Returns all atoms with element symbol Zn or Ca''
----
=== Helices ===
<code>Helices() -> FragmentSeq</code> 
''Returns all helices. This assumes the information about helices was present in the input structure.'' 
;Examples
: <code>Helices()</code>
:: ''Returns all helices.''
----
=== HetResidues ===
<code>HetResidues() -> Residues</code> 
''Sequence of all residues that contain HET atoms.'' 
;Options
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
;Examples
: <code>HetResidues()</code>
:: ''Returns all residues that contain HET atoms (ignores water).''
: <code>HetResidues(NoWaters=False)</code>
:: ''Returns all residues that contain HET atoms (includes water).''
----
=== Chains ===
<code>Chains(identifiers: Value*) -> FragmentSeq</code> 
''Splits the structures into chains. If no identifiers are specified, all chains are returned.'' 
;Arguments
: identifiers: Value* - ''Chain identifiers.''
;Examples
: <code>Chains()</code>
:: ''Returns all chains.''
: <code>Chains("")</code>
:: ''Returns chains without specific identifier.''
: <code>Chains("A", "B")</code>
:: ''Returns chains A and B.''
----
=== Named ===
<code>Named(fragments: FragmentSeq) -> FragmentSeq</code> 
'''Names' the fragment by its lowest atom id.'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to name.''
;Examples
: <code>Atoms("Zn").Named().AmbientAtoms(7)</code>
:: ''When exported, the result files will have names in the format '[parent id]_[pseudorandom number]_[zn atomid]'. If the Named function was not used, the name would be just '[parent id]_[pseudorandom number]'.''
----
=== NotAminoAcids ===
<code>NotAminoAcids() -> Residues</code> 
''Sequence of all residues that are not any of the 20 basic amino acids.'' 
;Options
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
;Examples
: <code>NotAminoAcids()</code>
:: ''Returns all residues that are not amino acids.''
----
=== NotAtomIds ===
<code>NotAtomIds(ids: Integer+) -> Atoms</code> 
''Sequence of atoms that do not have specified identifiers.'' 
;Arguments
: ids: Integer+ - ''Identifiers.''
;Examples
: <code>NotAtomIds(1, 2, 3)</code>
:: ''Returns atoms that do not have id 1, 2, nor 3.''
----
=== NotAtomNames ===
<code>NotAtomNames(names: String+) -> Atoms</code> 
''Sequence of atoms that do not have a specified name.'' 
;Arguments
: names: String+ - ''Forbidden names.''
;Examples
: <code>NotAtomNames("O4")</code>
:: ''Returns all atoms that are not called O4.''
----
=== NotAtoms ===
<code>NotAtoms(symbols: String+) -> Atoms</code> 
''Sequence of atoms that are not particular elements.'' 
;Arguments
: symbols: String+ - ''Forbidden element symbols.''
;Examples
: <code>NotAtoms("O")</code>
:: ''Returns all atoms that are not O.''
----
=== NotResidues ===
<code>NotResidues(names: Value+) -> Residues</code> 
''Sequence of residues that are not called by the specified names.'' 
;Arguments
: names: Value+ - ''Forbidden residue names.''
;Examples
: <code>NotResidues("THR","CYS")</code>
:: ''Returns all residues that are not THR or CYS.''
----
=== RegularMotifs ===
<code>RegularMotifs(regex: Value) -> FragmentSeq</code> 
''Identifies regular motifs. The protein is split into individual chains and the residues are sorted by their Sequence Number before the motifs are identified. The query does not check if adjacent residues have consecutive Sequence Numbers. The query works in two modes: Amino and Nucleotide, on amino acids and nucleotides respectively. The default mode is 'Amino''' 
;Arguments
: regex: Value - ''Regular expression on one letter abbreviations of amino acids.''
;Options
: Type: String = "Amino" - ''Determines the type of the query. Allowed values: Amino, Nucleotide.''
;Examples
: <code>RegularMotifs("RGD")</code>
:: ''Finds all RGD motifs.''
: <code>RegularMotifs("ACGTU", Type = 'Nucleotide')</code>
:: ''Finds all consecutive occurrences of the ACGTU nucleotides.''
: <code>RegularMotifs(".HC.").Filter(lambda m: m.IsConnected())</code>
:: ''Finds all 4 residue motifs with ?-HIS-CYS-? that are connected.''
----
=== ResidueIdRange ===
<code>ResidueIdRange(chain: String, min: Integer, max: ?Integer) -> Residues</code> 
''Sequence of residues with specific chain and min <= sequence number <= max.'' 
;Arguments
: chain: String - ''Chain identifier. Case sensitive (a != A).''
: min: Integer - ''Minimum sequence number.''
: max: ?Integer - ''Maximum sequence number. If not specified, max = min.''
;Examples
: <code>ResidueIdRange("A", 161, 165)</code>
:: ''Returns all residues on chain A with seq. number between 161 and 165 inclusive.''
----
=== ResidueIds ===
<code>ResidueIds(ids: String+) -> Residues</code> 
''Sequence of residues with specific identifiers. If the structure does not contain a residue with the given identifier, it is skipped.'' 
;Arguments
: ids: String+ - ''One or more identifiers in the format 'NUMBER [CHAIN] [i:INSERTIONCODE]' (parameters in [] are optional, for example '175 i:12' or '143 B'). Case sensitive (a != A).''
;Examples
: <code>ResidueIds("132 A", "178 A")</code>
:: ''Returns residues A 123 and A 178 (provided the input structure contains them).''
----
=== Residues ===
<code>Residues(names: String*) -> Residues</code> 
''Sequence of residues with specified names. If no names are specified, yields all residues one by one.'' 
;Arguments
: names: String* - ''Allowed residue names.''
;Examples
: <code>Residues("HIS", "CYS")</code>
:: ''Returns all HIS or CYS residues.''
----
=== RingAtoms ===
<code>RingAtoms(atom: Atoms, ring: ?Rings) -> Atoms</code> 
''Returns all rings atoms.'' 
;Arguments
: atom: Atoms - ''Atom types.''
: ring: ?Rings - ''Specific ring.''
;Examples
: <code>RingAtoms(Atoms("C"), Rings(4 * ["C"] + ["O"]))</code>
:: ''Returns all C atoms on a ring with 4C and O.''
----
=== Rings ===
<code>Rings(atoms: Value*) -> Rings</code> 
''Sequence of rings with particular atoms. If no atoms are specified, yields all rings (cycles) one by one. The order of atoms matters.'' 
;Arguments
: atoms: Value* - ''Ring atoms.''
;Examples
: <code>Rings()</code>
:: ''Returns all rings.''
: <code>Rings(5 * ["C"] + ["O"])</code>
:: ''Returns all rings with 5C and 1O atoms.''
: <code>Rings(["C", "C", "N", "C", "N"])</code>
:: ''Returns all rings with C-C-N-C-N atoms.''
: <code>Or(Rings(["C", "C", "N", "C", "N"]), Rings(["C", "C", "C", "N", "N"]))</code>
:: ''Returns all rings with C-C-N-C-N or C-C-C-N-N atoms.''
----
=== Sheets ===
<code>Sheets() -> FragmentSeq</code> 
''Returns all sheets. This assumes the information about sheets was present in the input structure.'' 
;Examples
: <code>Sheets()</code>
:: ''Returns all sheets.''
 
== Advanced Query Functions ==
''Advanced building blocks of the language.''
=== Flatten ===
<code>Flatten(fragments: FragmentSeq, selector: Fragment->FragmentSeq) -> FragmentSeq</code> 
''Converts a sequence of sequence of fragments into a single 'flat' sequence.'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to project.''
: selector: Fragment->FragmentSeq - ''The selector.''
;Examples
: <code>Residues("HIS").Flatten(lambda m: m.Find(Atoms("C")))</code>
:: ''Returns all C atoms on HIS residues.''
----
=== Inside ===
<code>Inside(fragments: FragmentSeq, where: FragmentSeq) -> FragmentSeq</code> 
''Finds fragments within another fragment. Equivalent to where.Flatten(lambda m: m.Find(fragments))'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to find.''
: where: FragmentSeq - ''Where to find them.''
;Examples
: <code>Atoms("C").Inside(Residues("HIS"))</code>
:: ''Returns all C atoms on HIS residues.''
----
=== Or ===
<code>Or(fragments: FragmentSeq+) -> FragmentSeq</code> 
''Merges several fragment sequences into one.'' 
;Arguments
: fragments: FragmentSeq+ - ''Fragments to merge.''
;Examples
: <code>Or(Atoms("Zn").ConnectedResidues(1), Rings())</code>
:: ''Finds all zincs and their connected residues or rings.''
----
=== ToAtoms ===
<code>ToAtoms(fragments: FragmentSeq) -> FragmentSeq</code> 
''Collects all 'inner' fragments and yields all unique atoms one by one.'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to split.''
;Examples
: <code>Residues("HIS").ToAtoms()</code>
:: ''Returns all atoms on HIS residues one by one.''
----
=== ToResidues ===
<code>ToResidues(fragments: FragmentSeq) -> FragmentSeq</code> 
''Collects all 'inner' fragments and yields all unique residues one by one. The residues contain only the atoms that have been yielded by the inner query.'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to split.''
;Examples
: <code>Atoms("C").ToResidues()</code>
:: ''Returns all C atoms grouped by residues.''
----
=== Union ===
<code>Union(fragments: FragmentSeq) -> FragmentSeq</code> 
''Collects all 'inner' fragments and yields one created from their unique atoms.'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to merge.''
;Examples
: <code>Rings().Union()</code>
:: ''Creates a single fragment that contains all rings.''
 
== Filter Functions ==
''Functions useful for filtering fragments.''
=== Contains ===
<code>Contains(where: Fragment, what: FragmentSeq) -> Bool</code> 
''Checks if a fragment is contained within another one. Equivalent to where.Count(what) > 0.'' 
;Arguments
: where: Fragment - ''Where to look.''
: what: FragmentSeq - ''What to find.''
;Examples
: <code>HetResidues().Filter(lambda m: m.Contains(Rings(5*['C']+['O'])).Not())</code>
:: ''Returns all HET residues that do not contain a 5CO ring.''
----
=== Count ===
<code>Count(where: Fragment, what: FragmentSeq) -> Integer</code> 
''Counts all occurrences of fragment 'what' in fragment 'where'.'' 
;Arguments
: where: Fragment - ''Where to count it.''
: what: FragmentSeq - ''What fragment to count.''
;Examples
: <code>m.Count(Residues("HIS"))</code>
:: ''Returns the count of HIS residues in the fragment m. Where m is a Fragment (for example when using the Filter function or returned by the ToFragment() function). This example will not work directly and is here to illustrate a concept.''
: <code>Atoms("Zn").ConnectedResidues(1).Filter(lambda m: m.Count(Residues("HIS")) == 2)</code>
:: ''Fragments with Zn atoms and its connected residues with exactly 2 HIS residues.''
----
=== ExecuteIf ===
<code>ExecuteIf(query: FragmentSeq, condition: Fragment->Bool) -> FragmentSeq</code> 
''Executes a query only if the condition is met. Otherwise, return an empty sequence of fragments.'' 
;Arguments
: query: FragmentSeq - ''Query to execute.''
: condition: Fragment->Bool - ''Condition that must be satisfied for the parent structure/fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.Resolution() <= 2.4)</code>
:: ''Returns residues in structures that have resolution lower than 2.4ang.''
: <code>AminoAcids().ExecuteIf(lambda p: p.Count(Atoms('Fe')) > 3)</code>
:: ''Returns all amino acids in structures that have at least 3 Fe atoms.''
----
=== Filter ===
<code>Filter(fragments: FragmentSeq, filter: Fragment->Bool) -> FragmentSeq</code> 
''Filters a sequence of fragments with a given predicate.'' 
;Arguments
: fragments: FragmentSeq - ''Fragments to filter.''
: filter: Fragment->Bool - ''Filter predicate.''
;Examples
: <code>Residues().Filter(lambda m: m.Count(Atoms("C")) >= 3)</code>
:: ''Returns all residues that contain at least 3 C atoms.''
----
=== IsConnected ===
<code>IsConnected(fragment: Fragment) -> Bool</code> 
''Checks if a particular fragment is a connected graph.'' 
;Arguments
: fragment: Fragment - ''A fragment to test.''
;Examples
: <code>Atoms("Zn").AmbientResidues(3).Filter(lambda m: m.IsConnected())</code>
:: ''Finds all fragments with a Zn and residues within 3 ang, where all the ambient residues are connected to the central atom.''
----
=== IsConnectedTo ===
<code>IsConnectedTo(where: Fragment, fragments: FragmentSeq) -> Bool</code> 
''Checks if a particular fragment is connected to any other specified fragment. The fragments must have empty intersection for this function to return true.'' 
;Arguments
: where: Fragment - ''A fragment to test.''
: fragments: FragmentSeq - ''Fragment sequence to test against.''
;Examples
: <code>Atoms().Filter(lambda a: a.IsConnectedTo(Rings()))</code>
:: ''Finds all atoms that are connected to a ring they do not belong to.''
----
=== IsNotConnectedTo ===
<code>IsNotConnectedTo(what: Fragment, fragments: FragmentSeq) -> Bool</code> 
''Checks if a particular fragment is not connected to any other specified fragment. The fragments must have empty intersection for this function to return true.'' 
;Arguments
: what: Fragment - ''A fragment to test.''
: fragments: FragmentSeq - ''Fragment sequence to test against.''
;Examples
: <code>Residues().Filter(lambda r: r.IsNotConnectedTo(Atoms("Ca")))</code>
:: ''Finds all residues that are not connected to Ca atoms. The residue itself can still contain Ca atoms.''
----
=== NearestDistanceTo ===
<code>NearestDistanceTo(where: Fragment, fragments: FragmentSeq) -> Real</code> 
''Finds the distance to a particular fragment.'' 
;Arguments
: where: Fragment - ''A fragment to test.''
: fragments: FragmentSeq - ''Fragment sequence to test against.''
;Examples
: <code>Atoms().Filter(lambda m: m.NearestDistanceTo(Residues("ASP")) >= 5)</code>
:: ''Finds all atoms that are at least 5 (angstroms) away from any ASP residue.''
 
== Topology Functions ==
''Functions that rely on the topology of fragments.''
=== ConnectedAtoms ===
<code>ConnectedAtoms(fragment: FragmentSeq, n: Integer) -> FragmentSeq</code> 
''Surrounds the inner fragment by n layers of atoms.'' 
;Arguments
: fragment: FragmentSeq - ''Basic fragment.''
: n: Integer - ''Number of atom layers to connect.''
;Options
: YieldNamedDuplicates: Bool = False - ''Yield duplicate fragments if they have a different name.''
;Examples
: <code>Residues("MAN").ConnectedAtoms(2)</code>
:: ''Finds all MAN residues and then adds two connected levels of atoms to them.''
----
=== ConnectedResidues ===
<code>ConnectedResidues(fragment: FragmentSeq, n: Integer) -> FragmentSeq</code> 
''Surrounds the inner fragment by n layers of residues.'' 
;Arguments
: fragment: FragmentSeq - ''Basic fragment.''
: n: Integer - ''Number of residue layers to connect.''
;Options
: YieldNamedDuplicates: Bool = False - ''Yield duplicate fragments if they have a different name.''
;Examples
: <code>Atoms("Zn").ConnectedResidues(1)</code>
:: ''Finds all Zn atoms and adds all residues that are connected to them.''
----
=== Path ===
<code>Path(fragments: FragmentSeq+) -> FragmentSeq</code> 
''Creates a new fragment from 'connected' parts.'' 
;Arguments
: fragments: FragmentSeq+ - ''Fragments to path.''
;Examples
: <code>Path(Atoms("O"), Atoms("C"), Atoms("O"))</code>
:: ''Finds fragments with two O and one C atoms where the C atoms is connected to the O ones.''
----
=== Star ===
<code>Star(center: FragmentSeq, fragments: FragmentSeq+) -> FragmentSeq</code> 
''Creates a new fragment from a central one and connected parts.'' 
;Arguments
: center: FragmentSeq - ''Center fragment.''
: fragments: FragmentSeq+ - ''Fragments to chain.''
;Examples
: <code>Star(Atoms("C"), Atoms("O"), Atoms("O"))</code>
:: ''Finds fragments with two O atoms and one C atom in the center.''
: <code>Atoms("C").Star(Atoms("O"), Atoms("O"))</code>
:: ''Finds fragments with two O atoms and one C atom in the center.''
 
== Geometry Functions ==
''Functions that rely on the geometry of fragments.''
=== AmbientAtoms ===
<code>AmbientAtoms(fragment: FragmentSeq, r: Number) -> FragmentSeq</code> 
''Surrounds the inner fragment by atoms that within the given radius from the inner fragment.'' 
;Arguments
: fragment: FragmentSeq - ''Basic fragment.''
: r: Number - ''Radius.''
;Options
: ExcludeBase: Bool = False - ''Exclude the central original fragment.''
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
: YieldNamedDuplicates: Bool = False - ''Yield duplicate fragments if they have a different name.''
;Examples
: <code>Atoms("Fe").AmbientAtoms(4)</code>
:: ''Finds Fe atoms and all atoms within 4 (angstroms) from each of them.''
----
=== AmbientResidues ===
<code>AmbientResidues(fragment: FragmentSeq, r: Number) -> FragmentSeq</code> 
''Surrounds the inner fragment by residues that have at least one atom within the given radius from the inner fragment.'' 
;Arguments
: fragment: FragmentSeq - ''Basic fragment.''
: r: Number - ''Radius.''
;Options
: ExcludeBase: Bool = False - ''Exclude the central original fragment.''
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
: YieldNamedDuplicates: Bool = False - ''Yield duplicate fragments if they have a different name.''
;Examples
: <code>Rings(6 * ["C"]).AmbientResidues(4)</code>
:: ''Finds rings with 6C atoms and all residues within 4 (angstroms) from each of them.''
----
=== Cluster ===
<code>Cluster(r: Number, fragments: FragmentSeq+) -> FragmentSeq</code> 
''Clusters all fragments that are pairwise closer than r (angstroms).'' 
;Arguments
: r: Number - ''Maximum distance between two fragments in the cluster.''
: fragments: FragmentSeq+ - ''Fragments to cluster.''
;Examples
: <code>Cluster(4, Atoms("Ca"), Rings(5 * ["C"] + ["O"]))</code>
:: ''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 ===
<code>Filled(fragment: FragmentSeq) -> FragmentSeq</code> 
''Adds all atoms that fall within the circumsphere (with radius multiplied by the factor) of the basic fragment.'' 
;Arguments
: fragment: FragmentSeq - ''Basic fragment.''
;Options
: NoWaters: Bool = True - ''Ignore water residues such as HOH.''
: RadiusFactor: Number = 0.75 - ''Circumsphere radius factor.''
;Examples
: <code>Cluster(4, Residues("HIS")).Filled(RadiusFactor = 0.75)</code>
:: ''Finds clusters of HIS residues and all atoms within the circumsphere.''
----
=== Near ===
<code>Near(r: Number, fragments: FragmentSeq+) -> FragmentSeq</code> 
''Clusters all fragments that are pairwise closer than r (angstroms) and checks if the "counts" match.'' 
;Arguments
: r: Number - ''Maximum distance between two sub-fragments in the fragment.''
: fragments: FragmentSeq+ - ''Fragments to 'cluster'.''
;Examples
: <code>Near(4, Atoms("Ca"), Atoms("Ca"), Rings(5 * ["C"] + ["O"]))</code>
:: ''Finds all instance of a single ring with 5C and O atoms and two Ca atoms that are closer than 4 (angstroms).''
 
== Meta-data Functions ==
''Functions dealing with meta-data about structures such as release date or authors.''
=== Authors ===
<code>Authors(fragment: Fragment) -> String</code> 
''Returns authors of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== ECNumbers ===
<code>ECNumbers(fragment: Fragment) -> String</code> 
''Returns Enzymatic Commission numbers assigned to enzymes in the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== EntitySources ===
<code>EntitySources(fragment: Fragment) -> String</code> 
''Returns entity sources of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== ExperimentMethod ===
<code>ExperimentMethod(fragment: Fragment) -> String</code> 
''Get the experiment method. The value is always an upper-case string. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ExperimentMethod() == "INFRARED SPECTROSCOPY")</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== HasAllAuthors ===
<code>HasAllAuthors(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given authors. The comparison is case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllAuthors("Holmes", "Watson"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllECNumbers ===
<code>HasAllECNumbers(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given Enzymatic Commission numbers. It is possible to enter just a number prefix without the '.'. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllECNumbers("3.2.1.18", "3.3"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllEntitySources ===
<code>HasAllEntitySources(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given entity sources. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllEntitySources("GMO", "Natural", "Synthetic"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllHostOrganismGenus ===
<code>HasAllHostOrganismGenus(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given host organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllHostOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllHostOrganismIds ===
<code>HasAllHostOrganismIds(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given host organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllHostOrganismIds("7108", "11244"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllHostOrganisms ===
<code>HasAllHostOrganisms(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given host organism names. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllHostOrganisms("Spodoptera frugiperda", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllKeywords ===
<code>HasAllKeywords(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given keywords. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllKeywords("membrane", "glycoprotein"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllOriginOrganismGenus ===
<code>HasAllOriginOrganismGenus(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given origin organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllOriginOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllOriginOrganismIds ===
<code>HasAllOriginOrganismIds(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given origin organism identifiers. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllOriginOrganismIds("121791", "10090"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAllOriginOrganisms ===
<code>HasAllOriginOrganisms(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains all given origin organism names. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAllOriginOrganisms("Nipah virus", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyAuthor ===
<code>HasAnyAuthor(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given authors. The comparison is case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyAuthor("Holmes", "Watson"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyECNumber ===
<code>HasAnyECNumber(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given Enzymatic Commission number. It is possible to enter just a number prefix without the '.'s. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyECNumber("3.2.1.19", "3.3"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyEntitySources ===
<code>HasAnyEntitySources(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given entity sources. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyEntitySources("GMO", "Natural", "Synthetic"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyHostOrganism ===
<code>HasAnyHostOrganism(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given host organism names. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyHostOrganism("Spodoptera frugiperda", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyHostOrganismGenus ===
<code>HasAnyHostOrganismGenus(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given host organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyHostOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyHostOrganismId ===
<code>HasAnyHostOrganismId(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given host organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyHostOrganismId("7108", "11244"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyKeyword ===
<code>HasAnyKeyword(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given keywords. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyKeyword("membrane", "glycoprotein"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyOriginOrganism ===
<code>HasAnyOriginOrganism(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given origin organism names. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyOriginOrganism("Nipah virus", "Mus musculus"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyOriginOrganismGenus ===
<code>HasAnyOriginOrganismGenus(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given origin organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyOriginOrganismGenus("X", "Y"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HasAnyOriginOrganismId ===
<code>HasAnyOriginOrganismId(fragment: Fragment, properties: String+) -> Bool</code> 
''Determines if the parent structure contains any of the given origin organism identifierss. The comparison is not case sensitive.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
: properties: String+ - ''Properties.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.HasAnyOriginOrganismId("121791", "10090"))</code>
:: ''Returns residues in structures that contain all given properties.''
----
=== HostOrganismGenus ===
<code>HostOrganismGenus(fragment: Fragment) -> String</code> 
''Returns host organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== HostOrganismIds ===
<code>HostOrganismIds(fragment: Fragment) -> String</code> 
''Returns host organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== HostOrganisms ===
<code>HostOrganisms(fragment: Fragment) -> String</code> 
''Returns host organism names of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== Keywords ===
<code>Keywords(fragment: Fragment) -> String</code> 
''Returns keywords of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== LatestRevisionDate ===
<code>LatestRevisionDate(fragment: Fragment) -> Value</code> 
''Get the latest revision date of the parent structure. The value has to be compared to the DateTime(year, month, day) object. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.LatestRevisionDate() >= DateTime(2008, 1, 1))</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== LatestRevisionYear ===
<code>LatestRevisionYear(fragment: Fragment) -> Integer</code> 
''Get the latest revision year of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.LatestRevisionYear() == 2006)</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== OriginOrganismGenus ===
<code>OriginOrganismGenus(fragment: Fragment) -> String</code> 
''Returns origin organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== OriginOrganismIds ===
<code>OriginOrganismIds(fragment: Fragment) -> String</code> 
''Returns origin organism identifiers of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== OriginOrganisms ===
<code>OriginOrganisms(fragment: Fragment) -> String</code> 
''Returns origin organism names of the parent structure separated by a semicolon. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== PolymerType ===
<code>PolymerType(fragment: Fragment) -> String</code> 
''Get the polymer type of the structure. Possible values are: NotAssigned, Protein, DNA, RNA, ProteinDNA, ProteinRNA, NucleicAcids, Mixture, Sugar, Other. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.PolymerType() == "ProteinDNA")</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== ProteinStoichiometry ===
<code>ProteinStoichiometry(fragment: Fragment) -> String</code> 
''Get the protein stoichiometry of the parent structure. Possible values are: NotAssigned, Monomer, Homomer, Heteromer. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ProteinStoichiometry() == "Heteromer")</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== ProteinStoichiometryString ===
<code>ProteinStoichiometryString(fragment: Fragment) -> String</code> 
''Get the protein stoichiometry string of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
----
=== ReleaseDate ===
<code>ReleaseDate(fragment: Fragment) -> Value</code> 
''Get the release date of the parent structure. The value has to be compared to the DateTime(year, month, day) object. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ReleaseDate() >= DateTime(2008, 1, 1))</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== ReleaseYear ===
<code>ReleaseYear(fragment: Fragment) -> Integer</code> 
''Get the release year of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.ReleaseYear() == 2006)</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== Resolution ===
<code>Resolution(fragment: Fragment) -> Real</code> 
''Get the resolution in angstroms of the parent structure. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.Resolution() <= 2.4)</code>
:: ''Returns residues in structures that satisfy the property.''
----
=== Weight ===
<code>Weight(fragment: Fragment) -> Real</code> 
''Get the weight of the molecule in kDa. If the value is not available, null is returned.'' 
;Arguments
: fragment: Fragment - ''Fragment.''
;Examples
: <code>Residues().ExecuteIf(lambda p: p.Weight() > 100000.0)</code>
:: ''Returns residues in structures that satisfy the property.''
 
== Miscellaneous Functions ==
''Various useful functions. These function often require a special setup (i.e. only useful in Scripting window or in specific applications).''
=== AminoSequenceString ===
<code>AminoSequenceString(fragment: Fragment) -> String</code> 
''Returns a string of single-letter amino acids contained in the fragment.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: fragment: Fragment - ''Fragment to convert.''
;Examples
: <code>Fragment("1tqn_12").AminoSequenceString()</code>
:: ''Returns a string representing amino acids in the fragment '1tqn_12'.''
: <code>RegularMotifs(Fragment("1tqn_12").AminoSequenceString())</code>
:: ''Returns all regular fragments that correspond to the AMK sequence in 1tqn_12.''
----
=== AtomProperty ===
<code>AtomProperty(atomFragment: Fragment, name: String) -> ?</code> 
''If the property exists and the fragment consists of a single atom, returns the property. Otherwise, returns Nothing.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: atomFragment: Fragment - ''Single atom fragment.''
: name: String - ''Property name.''
;Examples
: <code>a.AtomProperty("charge")</code>
:: ''Gets the 'charge' property of the atom a. Where a is a single atom Fragment. This example will not work directly.''
: <code>Atoms().Filter(lambda a: a.AtomProperty("charge") >= 2)</code>
:: ''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 ===
<code>AtomSimilarity(a: Fragment, b: Fragment) -> Real</code> 
''Computes Jaccard/Tanimoto coefficient on atoms (element symbols) of both structures.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: a: Fragment - ''First fragment.''
: b: Fragment - ''Second fragment.''
;Examples
: <code>AtomSimilarity(Current(),Fragment("1tqn_12"))</code>
:: ''Computes the atom similarity between the current fragment and 1tqn_12. This example can be used in SiteBinder to create a descriptor (assuming a structure with id '1tqn_12' is loaded).''
----
=== CommonAtoms ===
<code>CommonAtoms(modelId: String) -> FragmentSeq</code> 
''Returns a single fragment with atoms common with the model. Properties checked: atom id, element symbol, chain, residue number. This query is useful for example for atom selection in SiteBinder.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: modelId: String - ''Id of the model.''
;Examples
: <code>CommonAtoms("1tqn_12")</code>
:: ''Returns a fragment formed by atoms common with the '1tqn_12' structure.''
----
=== CSA ===
<code>CSA() -> FragmentSeq</code> 
''Entries from Catalytic Site Atlas represented as fragments. Works only if used from the command line version of MotiveQuery and property configured.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Examples
: <code>CSA()</code>
:: ''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 ===
<code>Current() -> Fragment</code> 
''A variable that is assigned by the application environment.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Examples
: <code>AtomSimilarity(Current(), Fragment("model"))</code>
:: ''Returns the atom similarity of the current fragment 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 ===
<code>Descriptor(fragment: Fragment, name: String) -> ?</code> 
''Returns the descriptor. If the descriptor does not exist, 'null' is returned.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: fragment: Fragment - ''Fragment that represents entire structure.''
: name: String - ''Descriptor name.''
;Examples
: <code>Current().Descriptor("similarity") >= 0.75</code>
:: ''Returns True if 'similarity' descriptor of the current fragment is at least 0.75. This example will work for example in SiteBinder's structure selection if the 'similarity' descriptor has been previously defined.''
----
=== DynamicInvoke ===
<code>DynamicInvoke(value: Value, name: String, isProperty: Bool, args: Value) -> Value</code> 
''Dynamically invoke a member. (internal)'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: value: Value - ''InnerQuery.''
: name: String - ''Member name.''
: isProperty: Bool - ''Is this a property.''
: args: Value - ''Array of arguments.''
----
=== Find ===
<code>Find(source: Fragment, fragments: FragmentSeq) -> FragmentSeq</code> 
''Converts the source fragment to a structure and finds fragments within it.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: source: Fragment - ''Where to look.''
: fragments: FragmentSeq - ''Fragments to find.''
;Examples
: <code>AtomSimilarity(Current().Find(NotAtoms("N")).ToFragment(), Fragment("model").Find(NotAtoms("N")).ToFragment())</code>
:: ''Computes the atom similarity of the 'current' and 'model' fragments, but ignores N atoms. This example can be used in SiteBinder to create a descriptor (assuming a structure with id 'model' is loaded).''
----
=== Fragment ===
<code>Fragment(structureName: String) -> Fragment</code> 
''Returns a structure represented as a fragment.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: structureName: String - ''Name of a structure.''
;Examples
: <code>Fragment("1tqn_12")</code>
:: ''Returns the structure '1tqn_12' represented as a fragment. Usable in defining descriptors or in Scripting window (using MQ.Execute).''
----
=== GroupedAtoms ===
<code>GroupedAtoms(symbols: String*) -> FragmentSeq</code> 
''Groups atoms using the element symbol and then returns each group as a single fragment.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: symbols: String* - ''Allowed element symbols.''
;Examples
: <code>GroupedAtoms()</code>
:: ''Returns groups of all atom types. For example if the input has atoms 5xC-1xO, fragments with 5xC and 1xO atoms are returned.''
: <code>GroupedAtoms('C', 'O')</code>
:: ''Returns groups of all atom types. For example if the input has atoms 5xC-1xO-6xH, fragments with 5xC and 1xO atoms are returned (but the H atoms are ignored).''
----
=== ResidueSimilarity ===
<code>ResidueSimilarity(a: Fragment, b: Fragment) -> Real</code> 
''Computes Jaccard/Tanimoto coefficient on residue names of both structures.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: a: Fragment - ''First fragment.''
: b: Fragment - ''Second fragment.''
;Examples
: <code>ResidueSimilarity(Current(), Fragment("1tqn_12"))</code>
:: ''Computes the residue similarity between the current fragment and '1tqn_12'. This example can be used in SiteBinder to create a descriptor (assuming a structure with id '1tqn_12' is loaded).''
----
=== ToFragment ===
<code>ToFragment(fragments: FragmentSeq) -> Fragment</code> 
''Converts a sequence of Fragments (FragmentSeq) to a single Fragment by merging all atoms into a single atom set. The Fragment type is required by some function such as AtomSimilarity.'' 
''Note:'' This function cannot be used directly to query fragments from MotiveExplorer or MotiveQuery service. 
;Arguments
: fragments: FragmentSeq - ''Fragments to convert.''
;Examples
: <code>Residues("HIS").ToFragment()</code>
:: ''Converts a sequence of HIS residue Fragments to a single Fragment.''
: <code>AtomSimilarity(Current().Find(NotAtoms("N")).ToFragment(), Fragment("model").Find(NotAtoms("N")).ToFragment())</code>
:: ''Computes the atom similarity of the 'current' and 'model' fragments, but ignores N atoms.''
 
== Value Functions ==
''Functions such as addition or comparison of numbers.''
=== Abs ===
<code>Abs(x: Number) -> Number</code> 
''Computes the 'Abs' function of the argument.'' 
;Arguments
: x: Number - ''Argument.''
;Examples
: <code>Abs(x)</code>
:: ''Evaluates the expression.''
----
=== Divide (/) ===
<code>Divide(x: Number, y: Number) -> Number</code> 
''Computes the 'Divide' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x / y</code>
:: ''Evaluates the expression.''
----
=== Equal (==) ===
<code>Equal(x: Value, y: Value) -> Bool</code> 
''Determines the 'Equal' relation between two values.'' 
;Arguments
: x: Value - ''Left argument.''
: y: Value - ''Right argument.''
;Examples
: <code>x == y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== Greater (>) ===
<code>Greater(x: Number, y: Number) -> Bool</code> 
''Determines the 'Greater' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x > y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== GreaterEqual (>=) ===
<code>GreaterEqual(x: Number, y: Number) -> Bool</code> 
''Determines the 'GreaterEqual' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x >= y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== Less (<) ===
<code>Less(x: Number, y: Number) -> Bool</code> 
''Determines the 'Less' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x < y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== LessEqual (<=) ===
<code>LessEqual(x: Number, y: Number) -> Bool</code> 
''Determines the 'LessEqual' relation between two values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x <= y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== LogicalAnd (&) ===
<code>LogicalAnd(xs: Bool+) -> Bool</code> 
''Computes 'LogicalAnd' of the input values.'' 
;Arguments
: xs: Bool+ - ''Arguments.''
;Examples
: <code>x & y</code>
:: ''Evaluates to True or False based on the values of x and y.''
----
=== LogicalNot (Not) ===
<code>LogicalNot(x: Bool) -> Bool</code> 
''Computes 'LogicalNot' of the input value. This function can be called using the shorthand 'Not'.'' 
;Arguments
: x: Bool - ''Argument.''
;Examples
: <code>LogicalNot(x)</code>
:: ''Evaluates to True or False based on the value of x.''
: <code>x.Not()</code>
:: ''Evaluates to True or False based on the value of x.''
----
=== LogicalOr (|) ===
<code>LogicalOr(xs: Bool+) -> Bool</code> 
''Computes 'LogicalOr' of the input values.'' 
;Arguments
: xs: Bool+ - ''Arguments.''
;Examples
: <code>x | y</code>
:: ''Evaluates to True or False based on the values of x and y.''
----
=== LogicalXor (Xor) ===
<code>LogicalXor(xs: Bool+) -> Bool</code> 
''Computes 'LogicalXor' of the input values. This function can be called using the shorthand 'Xor'.'' 
;Arguments
: xs: Bool+ - ''Arguments.''
;Examples
: <code>LogicalXor(x, y)</code>
:: ''Evaluates to True or False based on the values of x and y.''
: <code>Xor(x, y)</code>
:: ''Evaluates to True or False based on the values of x and y.''
----
=== Minus (-) ===
<code>Minus(x: Number) -> Number</code> 
''Computes the arithmetic negation of the argument.'' 
;Arguments
: x: Number - ''Argument.''
;Examples
: <code>-x</code>
:: ''Arithmetic negation of x.''
----
=== NotEqual (!=) ===
<code>NotEqual(x: Value, y: Value) -> Bool</code> 
''Determines the 'NotEqual' relation between two values.'' 
;Arguments
: x: Value - ''Left argument.''
: y: Value - ''Right argument.''
;Examples
: <code>x != y</code>
:: ''Evaluates to True or False based on the value of x and y.''
----
=== Plus (+) ===
<code>Plus(x: Number, y: Number) -> Number</code> 
''Computes the 'Plus' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x + y</code>
:: ''Evaluates the expression.''
----
=== Power (^) ===
<code>Power(x: Number, y: Number) -> Number</code> 
''Computes the 'Power' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x ^ y</code>
:: ''Evaluates the expression.''
----
=== Subtract (-) ===
<code>Subtract(x: Number, y: Number) -> Number</code> 
''Computes the 'Subtract' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x - y</code>
:: ''Evaluates the expression.''
----
=== Times (*) ===
<code>Times(x: Number, y: Number) -> Number</code> 
''Computes the 'Times' function of the values.'' 
;Arguments
: x: Number - ''Left argument.''
: y: Number - ''Right argument.''
;Examples
: <code>x * y</code>
:: ''Evaluates the expression.''

ChargeCalculator:CMD Version

2014-12-08T15:49:18Z

Dave:

This is help for version 1.0.14.11.28 or newer. The help text for other versions can be viewed using the --help command when running the application.
== Running the Service ==
The service can be executed using the command (latest .NET Framework required):
<pre>WebChemistry.Charges.Service.exe workingFolder configuration.json</pre>
In Linux (where available) and MacOS, the latest version the Mono Framework (http://mono-project.com/) must be used to run the application:
<pre>mono WebChemistry.Charges.Service.exe workingFolder configuration.json</pre>
Alternatively, on Linux and MacOS, an official version of .NET Framework should become available during 2015.
In Linux and MacOS, specific version of the Intel MKL library must be provided in order for the computation to run fast. See http://numerics.mathdotnet.com/ for more info.

== Configuration ==
The configuration is specified using the JSON format.

=== Configuration Example ===
This is the general shape of the JSON input configuration.
<pre>{
"InputFolder": "c:\\Data\\Structures",
"SetsXmlFilename": "c:\\Data\\DefaultSets.xml",
"ExportUncompressed": false,
"Sets": [
{
"Name": "RS2-EX",
"Method": "EemCutoffCover",
"Precision": "Double",
"CutoffRadius": 13.0,
"CorrectCutoffTotalCharge": true,
"IgnoreWaters": false
},
{
"Name": "RS2-E",
"Method": "Eem",
"Precision": "Double",
"CutoffRadius": 0.0,
"CorrectCutoffTotalCharge": true,
"IgnoreWaters": false
}
],
"Jobs": [
{
"Id": "1tqn",
"TotalCharges": [
-6.0
]
},
{
"Id": "1e12",
"TotalCharges": [
60.0
]
}
],
"MaxFullEemAtomCount": 30000,
"MaxDegreeOfParallelism": 8
}</pre>

There has to be exactly one configuration file for each validation run. Every value, as well as settings' names, is surrounded in quotation marks (" " or ' '). Backslashes (\) have to be escaped (\\). File system paths can be absolute as well as relative (/ works as well in paths).

=== Attributes ===
* '''InputFolder''' [ String ]
: ''Path to a folder containing the input data.''

* '''SetsXmlFilename''' [ String ]
: ''Path to a file containing the parameter sets.''

* '''ExportUncompressed''' [ Boolean ]
: ''If true, the output will not be compressed in ZIP.''

* '''Sets''' [ [[#SetConfig_details|SetConfig]] ]
: ''A list of sets that will be computed.''

* '''Jobs''' [ [[#Job_details|Job]] ]
: ''A list of job that need to be computed.''

* '''MaxFullEemAtomCount''' [ Int32 ], Default value = 30000
: ''A maximum number of atoms a molecule can have to be eligible for the 'Eem' method. 30000 atoms molecule consumes about 8GB of memory using the Double precision.''

* '''MaxDegreeOfParallelism''' [ Int32 ], Default value = 8
: ''Maximum number of parallel tasks that can be executed simultaneously. Recommended to be set to the number of cores your system has.''

=== Descriptions ===
===== SetConfig =====
* '''Name''' [ String ]
: ''The name of the set.''

* '''Method''' [ ChargeComputationMethod ]
: ''Computation method.''
: ''Available values are: Eem, EemCutoff, EemCutoffCoalesceH, EemCutoffCover, Reference.''

* '''Precision''' [ ChargeComputationPrecision ]
: ''Precision (Double is 64bit, Single is 32bit).''
: ''Available values are: Double, Single.''

* '''CutoffRadius''' [ Double ]
: ''Cutoff radius parameter for methods that require it.''

* '''CorrectCutoffTotalCharge''' [ Boolean ], Default value = true
: ''Determines whether to adjust the total charge during the cutoff computations.''

* '''IgnoreWaters''' [ Boolean ]
: ''Determines whether to ignore water atoms or not.''

===== Job =====
* '''Id''' [ String ]
: ''Id of the job is the filename of the molecule without extension.''

* '''TotalCharges''' [ Double[] ]
: ''A list of total charges that need to be computed.''

== Output Description ==

=== General Structure ===
* '''[WorkingDirectory]''' - ''Working directory of the application.''
:* '''result''' - ''Contains the result of the computation.''
:: '''log.txt''' - ''Contains the console output of the application.''
:: '''status.json''' - ''Contains general information of the computation (running time, version, etc.).''

=== Charges Specific Structure ===
* '''result''' - ''Folder with computation result.''
:* '''charges''' - ''Folder with computed charges''
::* '''<source>''' - ''A folder for each charge source''
:::* '''mol2''' - ''Folder with structures in MOL2 format''
:::* '''pqr''' - ''Folder with structures in PQR format''
:::* '''wprop''' - ''Folder with results in WPROP format - a list of pairs of atom serial numbers and values of atomic charges <Atom Id> <Charge>''
:::* '''computation_setup.json''' - ''File describing the setup of the calculation''
::: '''<molecule>_allcharges.csv''' - ''CSV file for each molecule with all computed charges''
:* '''statistics''' - ''Folder with statistics about the computed charges''
::* '''Atoms''' - ''Statistics data for each molecule, calculated at atomic level resolution''
:::* '''mol2''' - ''Folder with structures in MOL2 format''
:::* '''csv''' - ''Folder - for each molecule, a CSV file with all computed atomic charges''
:::* '''correlations''' - ''Folder - for each molecule, a CSV file with correlation statistics between all computed atomic charges''
:::* '''properties''' - ''Folder with statistics based on several specific properties of atoms''
::* '''Residues''' - ''Statistics data for each molecule, calculated at the residue level resolution - only present if the input file contained relevant residue information''
:::* '''mol2''' - ''Folder with mock structures in MOL2 format, where each atom represents a single residue''
:::* '''csv''' - ''Folder - for each molecule, a CSV file with all computed residue charges''
:::* '''correlations''' - ''Folder - for each molecule, a CSV file with correlation statistics between all computed residue charges''
:::* '''properties''' - ''Folder with statistics based on several specific properties of residues''
:* '''json''' - ''All data for each molecule in JSON format''
::: '''<molecule>.json''' - ''Entry for each molecule''
:* '''logs''' - ''Folder with computation logs''
::: '''<molecule>_log.csv ''' - ''A log entry for each molecule that includes execution time, warnings, etc.''
:: '''Sets.xml''' - ''Parameter sets used for the computation''
:: '''Summary_<date:year-month-day>_<time:hour-minute>.json''' - ''Summary information about the entire computation, date/time is in universal time''

=== Specific File Descriptions ===
This section contains detailed descriptions of selected specific files.
==== json folder ====
JSON files from this folder can be deserialized to the type `WebChemistry.Charges.Service.DataModel.ChargesServiceStructureData` available in the .NET library WebChemistry.Charges.Service.DataModel.dll included with the program.

ChargeCalculator:CMD Version

2014-12-05T14:18:23Z

Dave:

This is help for version 1.0.14.11.28 or newer. The help text for other versions be viewed using the --help command when running the application.
== Running the Service ==
The service can be executed using the command (latest .NET Framework required):
<pre>WebChemistry.Charges.Service.exe workingFolder configuration.json</pre>
In Linux (where available) and MacOS, the latest version the Mono Framework (http://mono-project.com/) must be used to run the application:
<pre>mono WebChemistry.Charges.Service.exe workingFolder configuration.json</pre>
Alternatively, on Linux and MacOS, an official version of .NET Framework should become available during 2015.
In Linux and MacOS, specific version of the Intel MKL library must be provider in order for the computation to run fast. See http://numerics.mathdotnet.com/ for more info.

== Configuration ==
The configuration is specified using the JSON format.

=== Configuration Example ===
This is the general shape of the JSON input configuration.
<pre>{
"InputFolder": "c:\\Data\\Structures",
"SetsXmlFilename": "c:\\Data\\DefaultSets.xml",
"ExportUncompressed": false,
"Sets": [
{
"Name": "RS2-EX",
"Method": "EemCutoffCover",
"Precision": "Double",
"CutoffRadius": 13.0,
"CorrectCutoffTotalCharge": true,
"IgnoreWaters": false
},
{
"Name": "RS2-E",
"Method": "Eem",
"Precision": "Double",
"CutoffRadius": 0.0,
"CorrectCutoffTotalCharge": true,
"IgnoreWaters": false
}
],
"Jobs": [
{
"Id": "1tqn",
"TotalCharges": [
-6.0
]
},
{
"Id": "1e12",
"TotalCharges": [
60.0
]
}
],
"MaxFullEemAtomCount": 30000,
"MaxDegreeOfParallelism": 8
}</pre>

There has to be exactly one configuration file for each validation run. Every value, as well as settings' names, is surrounded in quotation marks (" " or ' '). Backslashes (\) have to be escaped (\\). File system paths can be absolute as well as relative (/ works as well in paths).

=== Attributes ===
* '''InputFolder''' [ String ]
: ''Path to a folder containing the input data.''

* '''SetsXmlFilename''' [ String ]
: ''Path to a file containing the parameter sets.''

* '''ExportUncompressed''' [ Boolean ]
: ''If true, the output will not be compressed in ZIP.''

* '''Sets''' [ [[#SetConfig_details|SetConfig]] ]
: ''A list of sets that will be computed.''

* '''Jobs''' [ [[#Job_details|Job]] ]
: ''A list of job that need to be computed.''

* '''MaxFullEemAtomCount''' [ Int32 ], Default value = 30000
: ''A maximum number of atoms a molecule can have to be eligible for the 'Eem' method. 30000 atoms molecule consumes about 8GB of memory using the Double precision.''

* '''MaxDegreeOfParallelism''' [ Int32 ], Default value = 8
: ''Maximum number of a parallel tasks that can be executed simultaneously. Recommended to be set to the number of cores your system has.''

=== Descriptions ===
===== SetConfig =====
* '''Name''' [ String ]
: ''The name of the set.''

* '''Method''' [ ChargeComputationMethod ]
: ''Computation method.''
: ''Available values are: Eem, EemCutoff, EemCutoffCoalesceH, EemCutoffCover, Reference.''

* '''Precision''' [ ChargeComputationPrecision ]
: ''Precision (Double is 64bit, Single is 32bit).''
: ''Available values are: Double, Single.''

* '''CutoffRadius''' [ Double ]
: ''Cutoff radius parameter for methods that require it.''

* '''CorrectCutoffTotalCharge''' [ Boolean ], Default value = true
: ''Determines whether to adjust the total charge during the cutoff computations.''

* '''IgnoreWaters''' [ Boolean ]
: ''Determines whether to ignore water atoms or not.''

===== Job =====
* '''Id''' [ String ]
: ''Id of the job is the filename of the molecule without extension.''

* '''TotalCharges''' [ Double[] ]
: ''A list of total charges that need to be computed.''

== Output Description ==

=== General Structure ===
* '''[WorkingDirectory]''' - ''Working directory of the application.''
:* '''result''' - ''Contains the result of the computation.''
:: log.txt - ''Contains the console output of the application.''
:: status.json - ''Contains general information of the computation (running time, version, etc.).''

=== Charges Specific Structure ===
* '''result''' - ''Folder with computation result.''
:* '''charges''' - ''Folder with computed charges''
::* '''<source>''' - ''A folder for each charge source''
:::* '''mol2''' - ''Folder with structures in MOL2 format''
:::* '''pqr''' - ''Folder with structures in PQR format''
:::* '''wprop''' - ''Folder with results in WPROP format - a list of pairs of atom serial numbers and values of atomic charges <Atom Id> <Charge>''
:::* '''computation_setup.json''' - ''File describing the setup of the calculation''
::: <molecule>_allcharges.csv - ''CSV file for each molecule with all computed charges''
:* '''statistics''' - ''Folder with statistics about the computed charges''
::* '''Atoms''' - ''Statistics data for each molecule, calculated at atomic level resolution]''
:::* '''mol2''' - ''Folder with structures in MOL2 format''
:::* '''csv''' - ''Folder - for each molecule, a CSV file with all computed atomic charges''
:::* '''correlations''' - ''Folder - for each molecule, a CSV file with correlation statistics between all computed atomic charges''
:::* '''properties''' - ''Folder with statistics based on several specific properties of atoms''
::* '''Residues''' - ''Statistics data for each molecule, calculated at the residue level resolution - only present if the input file contained relevant residue information''
:::* '''mol2''' - ''Folder with mock structures in MOL2 format, where each atom represents a single residue''
:::* '''csv''' - ''Folder - for each molecule, a CSV file with all computed residue charges''
:::* '''correlations''' - ''Folder - for each molecule, a CSV file with correlation statistics between all computed residue charges''
:::* '''properties''' - ''Folder with statistics based on several specific properties of residues''
:* '''json''' - ''All data for each molecule in JSON format''
::: <molecule>.json - ''Entry for each molecule''
:* '''logs/''' - ''Folder with computation logs''
::: <molecule>_log.csv - ''A log entry for each molecule that includes execution time, warnings, etc.''
:: Sets.xml - ''Parameter sets used for the computation''
:: Summary_<date:year-month-day>_<time:hour-minute>.json - ''Summary information about the entire computation, date/time is in universal time''

=== Specific File Descriptions ===
This section contains detailed descriptions of selected specific files.
==== json folder ====
JSON files from this folder can be deserialized to the type `WebChemistry.Charges.Service.DataModel.ChargesServiceStructureData` available in the .NET library WebChemistry.Charges.Service.DataModel.dll included with the program.

ChargeCalculator:CMD Version

2014-12-05T14:16:42Z

Dave: Created page with "This is help for version 1.0.14.11.28 or newer. The help text for other versions be viewed using the --help command when running the application. == Running the Service == The..."

This is help for version 1.0.14.11.28 or newer. The help text for other versions be viewed using the --help command when running the application.
== Running the Service ==
The service can be executed using the command (latest .NET Framework required):
<pre>WebChemistry.Charges.Service.exe workingFolder configuration.json</pre>
In Linux (where available) and MacOS, the latest version the Mono Framework (http://mono-project.com/) must be used to run the application:
<pre>mono WebChemistry.Charges.Service.exe workingFolder configuration.json</pre>
Alternatively, on Linux and MacOS, an official version of .NET Framework should become available during 2015.
In Linux and MacOS, specific version of the Intel MKL library must be provider in order for the computation to run fast. See http://http://numerics.mathdotnet.com/ for more info.

== Configuration ==
The configuration is specified using the JSON format.

=== Configuration Example ===
This is the general shape of the JSON input configuration.
<pre>{
"InputFolder": "c:\\Data\\Structures",
"SetsXmlFilename": "c:\\Data\\DefaultSets.xml",
"ExportUncompressed": false,
"Sets": [
{
"Name": "RS2-EX",
"Method": "EemCutoffCover",
"Precision": "Double",
"CutoffRadius": 13.0,
"CorrectCutoffTotalCharge": true,
"IgnoreWaters": false
},
{
"Name": "RS2-E",
"Method": "Eem",
"Precision": "Double",
"CutoffRadius": 0.0,
"CorrectCutoffTotalCharge": true,
"IgnoreWaters": false
}
],
"Jobs": [
{
"Id": "1tqn",
"TotalCharges": [
-6.0
]
},
{
"Id": "1e12",
"TotalCharges": [
60.0
]
}
],
"MaxFullEemAtomCount": 30000,
"MaxDegreeOfParallelism": 8
}</pre>

There has to be exactly one configuration file for each validation run. Every value, as well as settings' names, is surrounded in quotation marks (" " or ' '). Backslashes (\) have to be escaped (\\). File system paths can be absolute as well as relative (/ works as well in paths).

=== Attributes ===
* '''InputFolder''' [ String ]
: ''Path to a folder containing the input data.''

* '''SetsXmlFilename''' [ String ]
: ''Path to a file containing the parameter sets.''

* '''ExportUncompressed''' [ Boolean ]
: ''If true, the output will not be compressed in ZIP.''

* '''Sets''' [ [[#SetConfig_details|SetConfig]] ]
: ''A list of sets that will be computed.''

* '''Jobs''' [ [[#Job_details|Job]] ]
: ''A list of job that need to be computed.''

* '''MaxFullEemAtomCount''' [ Int32 ], Default value = 30000
: ''A maximum number of atoms a molecule can have to be eligible for the 'Eem' method. 30000 atoms molecule consumes about 8GB of memory using the Double precision.''

* '''MaxDegreeOfParallelism''' [ Int32 ], Default value = 8
: ''Maximum number of a parallel tasks that can be executed simultaneously. Recommended to be set to the number of cores your system has.''

=== Descriptions ===
===== SetConfig =====
* '''Name''' [ String ]
: ''The name of the set.''

* '''Method''' [ ChargeComputationMethod ]
: ''Computation method.''
: ''Available values are: Eem, EemCutoff, EemCutoffCoalesceH, EemCutoffCover, Reference.''

* '''Precision''' [ ChargeComputationPrecision ]
: ''Precision (Double is 64bit, Single is 32bit).''
: ''Available values are: Double, Single.''

* '''CutoffRadius''' [ Double ]
: ''Cutoff radius parameter for methods that require it.''

* '''CorrectCutoffTotalCharge''' [ Boolean ], Default value = true
: ''Determines whether to adjust the total charge during the cutoff computations.''

* '''IgnoreWaters''' [ Boolean ]
: ''Determines whether to ignore water atoms or not.''

===== Job =====
* '''Id''' [ String ]
: ''Id of the job is the filename of the molecule without extension.''

* '''TotalCharges''' [ Double[] ]
: ''A list of total charges that need to be computed.''

== Output Description ==

=== General Structure ===
* '''[WorkingDirectory]''' - ''Working directory of the application.''
:* '''result''' - ''Contains the result of the computation.''
:: log.txt - ''Contains the console output of the application.''
:: status.json - ''Contains general information of the computation (running time, version, etc.).''

=== Charges Specific Structure ===
* '''result''' - ''Folder with computation result.''
:* '''charges''' - ''Folder with computed charges''
::* '''<source>''' - ''A folder for each charge source''
:::* '''mol2''' - ''Folder with structures in MOL2 format''
:::* '''pqr''' - ''Folder with structures in PQR format''
:::* '''wprop''' - ''Folder with results in WPROP format - a list of pairs of atom serial numbers and values of atomic charges <Atom Id> <Charge>''
:::* '''computation_setup.json''' - ''File describing the setup of the calculation''
::: <molecule>_allcharges.csv - ''CSV file for each molecule with all computed charges''
:* '''statistics''' - ''Folder with statistics about the computed charges''
::* '''Atoms''' - ''Statistics data for each molecule, calculated at atomic level resolution]''
:::* '''mol2''' - ''Folder with structures in MOL2 format''
:::* '''csv''' - ''Folder - for each molecule, a CSV file with all computed atomic charges''
:::* '''correlations''' - ''Folder - for each molecule, a CSV file with correlation statistics between all computed atomic charges''
:::* '''properties''' - ''Folder with statistics based on several specific properties of atoms''
::* '''Residues''' - ''Statistics data for each molecule, calculated at the residue level resolution - only present if the input file contained relevant residue information''
:::* '''mol2''' - ''Folder with mock structures in MOL2 format, where each atom represents a single residue''
:::* '''csv''' - ''Folder - for each molecule, a CSV file with all computed residue charges''
:::* '''correlations''' - ''Folder - for each molecule, a CSV file with correlation statistics between all computed residue charges''
:::* '''properties''' - ''Folder with statistics based on several specific properties of residues''
:* '''json''' - ''All data for each molecule in JSON format''
::: <molecule>.json - ''Entry for each molecule''
:* '''logs/''' - ''Folder with computation logs''
::: <molecule>_log.csv - ''A log entry for each molecule that includes execution time, warnings, etc.''
:: Sets.xml - ''Parameter sets used for the computation''
:: Summary_<date:year-month-day>_<time:hour-minute>.json - ''Summary information about the entire computation, date/time is in universal time''

=== Specific File Descriptions ===
This section contains detailed descriptions of selected specific files.
==== json folder ====
JSON files from this folder can be deserialized to the type `WebChemistry.Charges.Service.DataModel.ChargesServiceStructureData` available in the .NET library WebChemistry.Charges.Service.DataModel.dll included with the program.

MotiveValidator:Analysis of Results

2014-08-17T01:31:31Z

Dave: /* Complete structures */

For each validated motif, a validation report contains several types of results. Since the evaluation of the validated motif relies on comparing all atoms and bonds in the validated motif to those in the model residue, the first results that can be encountered are errors. In the first level '''Complete''' and '''Incomplete''' structures are distinguished. '''If you are unsure about the Terminology used in this section, please see [[MotiveValidator:Terminology | this webpage]]'''.

==Incomplete structures==

Incomplete structures are validated residues, which were lacking atoms in their structure in comparison to the model residue, or the inter-atomic distances were way too big or too low. Namely:
* '''Missing atoms''': An atom in the model residue has no corresponding atom in the validated motif.
* '''Missing rings''': At least one missing atom originates from cycles (rings).
* '''Degenerate''': Those motifs could not be properly analyzed due their degenerate structure, i.e. suspicious discrepancies between the atoms and inter-atomic bonds in the validated motif and in the model residue prevented proper validation.

Please note, ''chirality'' is only evaluated for those motifs which are complete. This is because the absence of some atoms can prevent the proper evaluation of chirality on the chiral centers present in the validated motif. Therefore, note that all motifs which are counted in the Wrong chirality category are in fact complete. At the same time, the motifs with no missing atoms and no chirality error are actually counted in a category called '''Correct chirality'''.

==Complete structures==
Complete validated structures include all the atoms which are present in the model residue. However, there are still possible issues and warnings can be raised:

* '''Wrong chirality''': an atom from the validated motif has different chirality than the corresponding atom from the model residue.
** '''Planar atom''': the chirality error was found on a planar chiral center. Because of their spacial distribution, planar chiral centers are very sensitive even to small perturbations in the position of the substituents. Therefore, some of the errors reported here might not be significant.
** '''Metal atom''': the chirality error was found on a metal chiral center. @Crina: Add more info here?

* '''Uncertain chirality''': the presence of unusual bonds may cause an improper evaluation of chirality.
* '''Substitution''': An atom from the validated motif is of a different chemical element than the corresponding atom in the model residue (e.g. O mapped to N). This happens often at linkage sites.
* '''Different naming''': An atom from the validated motif has a different PDB atom name than the corresponding atom from the model residue (e.g. the C1 atom mapped to the C7 atom). This happens often when the original PDB files were produced by different software.
* '''Foreign atom''': An atom from the model residue was mapped to an atom from outside the validated residue (i.e. from its surroundings).
* '''Alternate conformations''': In the original PDB file, the validated residue contains atoms which were given in alternate conformations (i.e., most probably different rotamers). Only the first rotamer was considered during validation.
* '''Zero model RMSD''': The superimposition between the model residue and the validated motif has a root mean square deviation of zero, i.e., the validated motif is identical to the model residue used as reference.

The last cathegory '''Correct chirality''' includes all the validated residues, where all the atoms from the validated motif have a matching partner in the model structure and the chirality of the chiral atoms is correct.

Additionally, for each validation run, there is '''Processing warnings''' tab available, where one can find warnings about the processed structures. Typically, there is an information about skipped ''alternate conformation residues'', ''wrong CONNECT records'' from the parent PDB file, ''processed models'' (in case the parent PDB is composed of multiple models) etc. Finally, as a general rule, in the validation interface, errors are marked in red (missing atoms) or dark yellow (wrong chirality), correct structures in green, and warnings in cyan.

[[File:MV_manual_figures7.png|thumb|center|1000px| '''MotiveValidator''' reports correct structures, as well as all potential issues found during validation, namely structures that are wrong either because they are incomplete (missing atoms or rings), or because the chirality of some atoms is incorrect. Additionally, '''MotiveValidator''' reports substitutions of native atoms due to chemical modifications of the residue, or atoms of neighboring residues found to replace native atoms at linkage sites, as well as unexpected PDB atom identifiers (not shown here).]]

ValidatorDB:Specifics page

2014-08-17T01:30:54Z

Dave: /* Processing Warnings */

The '''[[ValidatorDB]] specifics page''' is accessible from the [[ValidatorDB#Synopsis_page | synopsis page]], either via the '''LookUp bar''' on the '''Overview''' tab, or via the residue names and PDB IDs in the interactive tables on the tabs '''Details by Residue''' and '''Details by PDB Entry''', respectively. Depending on how it was accessed, the '''specifics page''' might retrieve validation results for one or more residues, a fact mentioned at the very top of the page.

The '''[[ValidatorDB]]''' specifics page provides a straightforward report of the validation results, including a summary and detailed information in both tabular and graphical form, along with a 3D structure visualizer for closer inspection of the problematic structures. These reports are accessible via several tabs on the specifics page, namely '''Overview''', '''Summary''', '''Details''' and '''Processing Warnings'''. These are described in detail in the section below. Inspecting the tabular and graphical validation reports accessible on the specifics page is the most comfortable and effective way to evaluate the results. Additionally, you may use the JSON Data download button at the top right corner of the specifics page in order to download the complete validation reports and perform any additional analyses on your own.

==Overview==
[[File:VDB_Model.png|thumb|right|500px|'''Overview''' tab]]

To keep consistency with the synopsis page, the specifics page also allows visualization of general validation statistics for a selected number of residues via the Overview tab. This representation is entirely compatible with that of the '''Overview''' tab on the synopsis page, and in fact makes up a subset of that data set. All color coding conventions are kept, and tool tips provide descriptions of each graphical element.

Note that this statistics can be downloaded in a *.csv format after clicking 'CSV' in the bottom right corner of the infographics.

 

==Summary==
[[File:VDB_Residue_summary.PNG|thumb|right|500px|'''Summary''' tab]]

On the '''[[ValidatorDB]]''' specifics page, the first view of the results is available in the '''Summary''' tab. For each validated residue, the Summary tab provides an overview of potential issues encountered.

If more than one residue were validated in one run, a list of these residues will be at the top of the page. In order to examine the validation summary for each residue, you will need to either click on that specific residue in the list, or just scroll down the page till you reach it. Each validated residue is identified by its 3-letter code, as well as its chemical formula and common name. Validation statistics are given as absolute numbers and percentages over all the motifs that were processed for each residue.

The table with the validation report is organized into two main sections, referring to '''incomplete''' (''Missing Atoms'' or ''Rings'') and '''complete structures''' (''With All Atoms'' and ''Rings'') respectively. The formal distinction between ring atoms and non-ring atoms (simply denoted as atoms) is meant to allow a quick localization of potential issues in residues containing rings, especially where atom identifiers are not useful. '''Chirality''' is evaluated only for the complete structures, since the absence of some atoms makes it difficult to check the chirality of some of the remaining atoms. Further, the problematic atoms are highlighted, in order to better localize the problems in the structures.

Last, a 2D representation of the model residue, and a pie chart with the validation results are provided for visual representation purposes. You can download them via the small icon at the top right corner of the chart, and later use them in your presentations.
 

==Details==
[[File:VDB_Residue_details.PNG|thumb|right|500px|'''Details''' tab]]

Whereas the Summary tab provides statistics of the issues over all validated motifs for each validated residue, the '''Details''' tab of the '''[[ValidatorDB]]''' specifics page allows you to inspect the issues in select groups of motifs, and further in each individual motif. Note that you may also access the details of any particular group of motifs also by clicking on a specific issue in any '''Summary''' tab table.

The '''Details''' tab is organized into a table where each row contains information regarding a single validated motif. The content of the table (i.e., which motifs are included, and what information is displayed) is dictated by the values of three selection fields at the top of the table. Click on the first field, and select the validated residue by its name (3-letter code) from the drop down menu. Only the motifs that were matched to that residue name will be displayed in the table. Click on the second field and select the type of issue (e.g., wrong chirality) from the drop down menu. Only the motifs which exhibit that type of issue will be displayed in the table. The number of motifs that fit each selection is given in brackets. If you want to make your selection even more specific, use the selection filed Id filter.

Which table columns are filled depend mostly on the type of issue selected in the filter. The most important columns are ''Id'', ''Issues/Warnings'', ''Missing atoms/rings'', ''Atoms'', ''Processing warnings''. The other columns give additional information, usually helpful in identifying the source of the error in the structure. Note that complete structures '''do not''' contain columns with the information about missing atoms. The column Id refers to a unique identifier assigned to each motif in order to keep a transparent trace of the motif's origin, as it contains the PDB ID, as well as the serial index of the first atom in the motif, as it appears in the original PDB entry. The column ''Issues/Warnings'' reports the number of issues or warnings found for each particular motif. The column ''Missing atoms/rings'' explains which atoms are missing in each validated motif, whereas ''Atoms'' shows the position of incorrect chirality. ''Missing atoms'' are listed by their atom identifier in the model, whereas atoms with wrong chirality are listed by their identifier in the validated motif. Clicking on a column header allows to sort the motifs according to the property specified in the header.

 

==3D visualization==
[[File:VDB_Details_entry.PNG|thumb|right|500px|'''Details''' tab]]

The 3D viewer implemented in the [[ValidatorDB]] interface offers one step further in the analysis of each individual validated motif, and is accessible via the '''Details'' tab on the specifics page. In the table, simply click on the Id of a motif of interest in order to open the 3D viewer, where you can inspect the structural inaccuracies more closely. Here you will be able to view and manipulate with the 3D representations of the validated motif and model residue, to help you better assess the position and relevance of the structural issues found during validation. Additionally, a 2D representation of the model is provided for clarity, which is especially helpful for larger motifs. Basic information about the validated motif is also given, along with a complete report of the validation results, where all the potential issues are listed.

 

==Processing Warnings==
[[File:VDB_Warnings.PNG|thumb|right|500px|'''Processing warnings''' tab]]

The validation reports in ValidatorDB also mention various unusual aspects encountered during validation. Sometimes the processed PDB entries contain information that is ambiguous, conflicting or which deviates strongly from the expected reference. [[ValidatorDB]] reports such events as processing warnings. Such information can be found in the '''Processing Warnings''' tab on the specifics page. The selection field at the top of the page helps filter the warnings for different residues, in case more of them are in validation report. Simply click on the drop down menu and select the category of warnings that you would like to explore. Processing warnings are issues that may cause incorrect Validation, such as bad two residues being too close together (misused concept of alternate conformations) or unusual bond lengths given by the CONECT records. Make sure that negative validation results (e.g., missing atoms) are not in fact caused by ignoring some atoms in an ill-formed structure.

Overally a processing warning may simply lead to ignoring a faulty atom, but the motif is validated.

ValidatorDB:Analysis of Results

2014-08-17T01:30:16Z

Dave: /* Complete structures */

For each validated motif, a validation report contains several types of results. Since the evaluation of the validated motif relies on comparing all atoms and bonds in the validated motif to those in the model residue, the first results that can be encountered are errors. In the first level '''Complete''' and '''Incomplete''' structures are distinguished. '''If you are unsure about the Terminology used in this section, please see [[MotiveValidator:Terminology | this webpage]]'''.

==Incomplete structures==

Incomplete structures are validated residues, which were lacking atoms in their structure in comparison to the model residue, or the inter-atomic distances were way too big or too low. Namely:
* '''Missing atoms''': An atom in the model residue has no corresponding atom in the validated motif.
* '''Missing rings''': At least one missing atom originates from cycles (rings).
* '''Degenerate''': Those motifs could not be properly analyzed due their degenerate structure, i.e. suspicious discrepancies between the atoms and inter-atomic bonds in the validated motif and in the model residue prevented proper validation.

Please note, ''chirality'' is only evaluated for those motifs which are complete. This is because the absence of some atoms can prevent the proper evaluation of chirality on the chiral centers present in the validated motif. Therefore, note that all motifs which are counted in the Wrong chirality category are in fact complete. At the same time, the motifs with no missing atoms and no chirality error are actually counted in a category called '''Correct chirality'''.

[[File:VDB incomplete.png|thumb|center|1200px| '''ValidatorDB''' reports correct structures, as well as all potential issues found during validation, namely structures that are wrong either because they are incomplete (missing atoms or rings), or because the chirality of some atoms is incorrect. Here all the are potential issues of the incomplete structure are illustrated.]]

==Complete structures==
[[File:VDB chirality.png|thumb|right|500px| Complete structures can contain chirality issues on a variety of different atom types, here all possible cases occuring in '''ValidatorDB''' are illustrated.]]

Complete validated structures include all the atoms which are present in the model residue. However, there are still possible issues and warnings can be raised:

* '''Wrong chirality''': an atom from the validated motif has different chirality than the corresponding atom from the model residue. This category can be further specified by identifying a source of the chirality issue.
** '''C atom''': the chirality error was found on a single bonded carbon atom.
** '''Planar atom''': the chirality error was found on a planar chiral center. Because of their spacial distribution, planar chiral centers are very sensitive even to small perturbations in the position of the substituents. Therefore, some of the errors reported here might not be significant.
** '''Metal atom''': the chirality error was found on a metal chiral center.
** '''High order atom''': the chirality error was detected on an atom, which is bonded with a bond of higher order than one. A typical example is phosphorus.
** '''Other''': Additional chirality issue which could not be asserted to any of the above categories, for example chirality issues on Nitrogen.

Note that in case a validated residues belongs to more than one category, it can be found in all of them (i.e. Planar and Metal, which is often case of ''HEM'' residues)

* '''Uncertain chirality''': the presence of unusual bonds may cause an improper evaluation of chirality.
* '''Substitution''': An atom from the validated motif is of a different chemical element than the corresponding atom in the model residue (e.g. O mapped to N). This happens often at linkage sites.
* '''Different naming''': An atom from the validated motif has a different PDB atom name than the corresponding atom from the model residue (e.g. the C1 atom mapped to the C7 atom). This happens often when the original PDB files were produced by different software.
* '''Foreign atom''': An atom from the model residue was mapped to an atom from outside the validated residue (i.e. from its surroundings).
* '''Alternate conformations''': In the original PDB file, the validated residue contains atoms which were given in conformations (i.e., most probably different rotamers). Only the first rotamer was considered during validation.
* '''Zero model RMSD''': The superimposition between the model residue and the validated motif has a root mean square deviation of zero, i.e., the validated motif is identical to the model residue used as reference.

The last category '''Correct chirality''' includes all the validated residues, where all the atoms from the validated motif have a matching partner in the model structure and the chirality of the chiral atoms is correct. Last but not least, additional category '''Correct (Tolerant) chirality''' further includes motifs with identified chirality issues as '''Planar''' and '''High order''' since these might not be significant.

Furthermore, for each validation run, there is '''Processing warnings''' tab available, where one can find warnings about the processed structures. Typically, there is an information about skipped ''alternate conformation residues'', ''wrong CONNECT records'' from the parent PDB file, ''processed models'' (in case the parent PDB is composed of multiple models) etc. Finally, as a general rule, in the validation interface, errors are marked in red (missing atoms) or dark yellow (wrong chirality), correct structures in green, and warnings in cyan.

[[File:VDB warnings.png|thumb|left|1000px| '''ValidatorDB''' also reports warnings in the complete structures such as ''substitutions'', ''different naming'' or ''foreign atoms''.]]

ValidatorDB

2014-06-26T00:20:05Z

Dave: /* Validation results */

The advancement of research in structural biology has provided a large body of structural data deposited in various databases. One great example is the Protein Data Bank (PDB), which has been growing exponentially, and which currently consists of more than 100,000 structures of biomolecules and their complexes. Such large bodies of data, especially accumulated over a short period of time using high throughput techniques, will inherently be plagued by various problems.

Validation arose as a major issue in the structural biology community when it became apparent that some published structures contained serious errors, and only sometimes it is properly explained(e.g., due to insufficient electron density in a certain area). Structural databases generally require that the new submissions be checked prior to acceptance. The tools employed for presubmission validations work fairly well for residues like amino acids or nucleotides. However, an essential step in the validation process is checking the ligand structure, because ligands play a key role in protein function, and also because they are the main source of errors in structures. Ligand validation, as well as the validation of uncommon residues, are very challenging tasks, because of the high diversity and nontriviality of their structure, and the general lack of information about correct structures. Therefore, software tools focused on ligand validation were developed relatively recently,<ref>Lütteke T, von der Lieth C-W. {BMC Bioinformatics} (2004) 5, 69.</ref><ref>Kleywegt GJ, Harris MR. Acta Crystallographica D. Biological Crystallography (2007) 63: 935–8.</ref>, and the topic is still under active development<ref>ftp://ftp.ebi.ac.uk/pub/databases/pdb/validation_reports/</ref>. These tools are able to validate one or more structures (even thousands of structures), but they are not able to provide the broad scientific community with a more complex image of the quality of structures in dedicated and well established structural databases. For example, a general overview and corresponding statistical evaluation of validation results for residues and ligands in the entire PDB is not yet available, despite the exponential growth of the PDB and the development of structural validation tools in recent years.

We had recently developed MotiveValidator<ref>Svobodová Vařeková R, Jaiswal D, Sehnal D, Ionescu CM, Geidl S, Pravda L, Horský V, Wimmerová M, Koca J, Nucleic Acids Research (2014) doi:10.1093/nar/gku426</ref>, an interactive platform for the speedy validation of ligands, residues and fragments using a novel, straightforward approach based on the validation of residue annotation. MotiveValidator employs advanced algorithms for the detection and comparison of structural motifs<ref>Sehnal D, Svobodová Vařeková R, Huber HJ, Geidl S, Ionescu CM, Wimmerová M, Koca J, Journal of Chemical Information and Modeling 52(2), (2012): 343-359</ref>, along with tools for chirality verification<ref>O'Boyle NM, Banck M, James CA, Morley C, Vandermeersch T, Hutchison GR, Journal of Chemoinformatics 3, (2011): 33</ref> and interactive visualization of 3D structures <ref>http://www.chemdoodle.com</ref>. Using MotiveValidator, we further created ValidatorDB, a comprehensive resource of validation results for residues and ligands in the Protein Data Bank. Along with validation results for individual residues and ligands, ValidatorDB also provides a summary and statistical evaluation of the validation results at various levels of detail within the PDB. Thus, ValidatorDB offers a comprehensive overview of the quality of the ligand structures in the entire PDB. ValidatorDB contains precomputed validation results for ligands and residues in the Protein Data Bank. The database is updated on a weekly basis.

The residues deemed relevant for validation are all ligands and residues with reasonable size (more than six heavy atoms), with the exception of standard amino acids and nucleotides. The validation is performed using MotiveValidator, and the residue models from wwPDB Chemical Component Dictionary (wwPDB CCD) are used as reference structures for validation.

==Availability and technical details==

===Where to find ValidatorDB===
ValidatorDB is freely available online since May 2014 at http://ncbr.muni.cz/MotiveValidatorDB. There is no login requirement for accessing ValidatorDB.

===What you need in order to access ValidatorDB===
ValidatorDB is basically a database, or rather a collection of validation results for ligands and residues in Protein Data Bank. The database is maintained at the National Centre for Biomolecular Research within Masaryk University, Czech Republic, and updated weekly. All you need in order to access ValidatorDB is an internet browser and has JavaScript enabled. The only functionality that relies on your system is the display of 3D models, for which your browser will need to support WebGL. If you experience trouble displaying the 3D models, please check http://get.webgl.org in order to find out how to enable WebGL on your system.

===How to get around the web page===

As soon as you type in the address http://ncbr.muni.cz/ValidatorDB, you will reach the ValidatorDB synopsis page, which contains a brief, general description of ValidatorDB, along with 3 tabs. The different tabs on the ValidatorDB synopsis page provide access to overviews and statistical evaluation of validation results for the entire PDB, for each residue across all PDB IDs containing that residue, and for all analyzed residues in each PDB ID, in graphical or tabular form. Click on each tab to discover what type of overview can be accessed. Further, the ValidatorDB specifics page, which is accessible by looking up specific residues or PDB IDs in the synopsis page, allows to view the results for selected residues in more detail. The specifics page is also organized into tabs that allow different levels of analysis of the results. Last but not least, remember to check the tool tips by hovering the mouse cursor over any graphical or textual element in the ValidatorDB interface.

Before moving on to more extensive descriptions of features, it is important to clearly establish the meaning of a few key terms and principles within the ValidatorDB environment. See [[MotiveValidator:Terminology|Terminology]].

==Basic Principles==

===Residues and ligands relevant for validation===

As mentioned in section 1, well studied residues like amino acids and nucleotides are routinely validated upon submission of new structures to the PDB. Furthermore, reports of the quality of their structure are already accessible. The challenge addressed by
ValidatorDB lies in providing access to validation results for residues other than the well studied amino acids and nucleotides. This generally includes ligands and uncommon residues (e.g. substituted amino acids), which exhibit high diversity and nontriviality in their structure, and for which there is generally much less information regarding correct structures. Thus, within the ValidatorDB environment, we further refine the meaning of the terms residue and ligand to refer to residues and ligands relevant for validation. Specifically, these are all ligands and residues with reasonable size (more than six heavy atoms), with the exception of amino acids and nucleotides. All other features of the terms residue and ligand described in sections 2.1 and 2.2 are maintained. Henceforth, all references to residues and ligands in the ValidatorDB web pages (including Wiki and tutorial) have the meaning of residues and ligands relevant for validation. The PDB currently holds over 170,00 residues and ligands relevant for validation.

===Validation===
[[File:VDB_manual_figures2.png|thumb|right|Validation process: figure 1]]
As stated in section, the validation results stored in ValidatorDB are updated every week. Within the ValidatorDB environment, the term validation refers to the process of determining whether a residue or ligand is structurally complete and correctly annotated. This means checking if the topology and chirality of each motif of a validated residue (section 2.4) correspond to those of the model residue (section 2.5) with the same name as the validated residue.
The validation of residues and ligands in the entire PDB takes place in a few distinct steps. First, for each PDB entry, the residues which are relevant for validation are detected based on their name (3-letter code) and number of atoms (more than 6 heavy atoms). Amino acid residues and nucleotides are excluded based on their residue name. Then, for each validated residue, the corresponding model (same 3-letter code as the validated residue) is retrieved from wwPDB CCD, and each motif of this residue is validated against the model.

ValidatorDB is then built as the collection of validation results for all motifs of all residues in all PDB entries(Figure 1A).
The validation of each motif against the model residue can be illustrated on a galactose (GAL)motif from the PDB entry 1bzw
(Figure 1B). The validated residue GAL is extracted form PDB entry 1bzw in the form of an input motif , which contains all the atoms of the validated residue, together with all atoms found within one or two bonds of any atom from the validated residue
(surroundings). Then, by superimposing the input motif and model residue, the validated motif is obtained as the subset of atoms in the input motif which have a correspondent atom in the model residue. Comparing each atom and bond in the validated motif to those in the model residue produces the validation results.

==Validation results==
For each validated motif, ValidatorDB contains several types of results. Since the evaluation of the validated motif relies on comparing all atoms and bonds in the validated motif to those in the model residue, the first results that can be encountered are errors. Namely:

*Missing atoms: an atom in the model residue has no corresponding atom in the validated motif.

*Missing rings: at least one missing atom originates from cycles (rings).

*Wrong chirality: an atom from the validated motif has different chirality than the corresponding atom from the model residue.

*Wrong chirality (planar): the chirality error was found on a planar chiral center. Because of their spacial distribution, planar chiral centers are very sensitive even to small perturbations in the position of the substituents. Therefore, some of the errors reported here might not be significant.

*Uncertain chirality: the presence of unusual bonds may cause an improper evaluation of chirality.

Chirality is only evaluated for those motifs which are complete. This is because the absence of some atoms can prevent the proper evaluation of chirality on the chiral centers present in the validated motif. Therefore, note that all motifs which are counted in the Wrong chirality category are in fact complete. At the same time, the motifs with no missing atoms and no chirality error are actually counted in a category called Correct chirality.

===Warnings===
Suspicious discrepancies between the atoms and inter-atomic bonds in the validated motif and in the model residue are reported as warnings. Namely:

*Substitution: an atom from the validated motif is of a different chemical element than the corresponding atom in the model residue (e.g. O mapped to N). This happens often at linkage sites.

*Different naming: an atom from the validated motif has a different PDB atom name than the corresponding atom from the model residue (e.g. the C1 atom mapped to the C7 atom). This happens often when the original PDB files were produced by different software.

*Foreign atom: an atom from the model residue was mapped to an atom from outside the validated residue (i.e. from its surroundings).

*Alternate locations: in the original PDB file, the validated residue contains atoms which were given in alternate locations (i.e., most probably different rotamers). Only the first rotamer was considered during validation.

*Zero model RMSD: the superimposition between the model residue and the validated motif has a root mean square deviation of zero, i.e., the validated motif is identical to the model residue used as reference.

Disabling discrepancies between the atoms and inter-atomic bonds in the validated motif and in the model residue are reported as
processing errors, and such motifs are not validated.

Typical validation results that can be found in ValidatorDB are illustrated on the galactose motif mentioned in section 2.6(Fig 1C). As a general rule, in the ValidatorDB interface, errors are marked in red (missing atoms) or dark yellow (wrong chirality), correct structures in green, and warnings in cyan.

==Database contents==
ValidatorDB contains precomputed validation results for ligands and residues in the Protein Data Bank. The database is updated on a weekly basis. The validation is performed using Validator, and the residue models from wwPDB CCD are used as reference templates for validation. All residues of significant size (a minimum of 6 heavy atoms) have been included in ValidatorDB, with the exception of amino acids and nucleotides, which are checked thoroughly upon submission of the structure to the PDB, and thus do not require additional validation.

The validation results available in ValidatorDB inform whether each motif (occurrence, instance) of a ligand or residue in the PDB exhibits the appropriate topology and stereochemistry expected from its annotation (3-letter code), or how it differs from this annotation. Additionally, all issues related to incorrect or suspicious topology and stereochemistry are explicitly described in a comprehensive and intuitive manner (e.g., location of missing atoms or chirality inversions).

ValidatorDB is organized on two main levels, namely PDB-wide results (synopsis page), and results restricted to specific residues of interest (specifics page). The two levels present the same type of validation results (as described in section 2.7), although the available features differ to some extent (e.g., the specifics page allows 3D visualization of motifs). We shall describe each level of the database in detail below.

==Synopsis page==

The ValidatorDB synopsis page(Figures1A, 3) contains a brief description of ValidatorDB, along with information about the last database update (date and number of structures that have been processed during the validation). Specifically, in May 2014, over 100,000 PDB entries had been processed, containing over 230,000 motifs of 17,000 residues relevant for validation.
Additionally, the synopsis page allows to access the validation results for specific residues of interest via the LookUp bar
(Figure 1A). Simply type a comma separated list of residue names (3-letter codes) into the LookUp bar, and you will be redirected to the specifics page containing validation results for the residues you requested. If you specify a list of PDB IDs (4-letter codes)instead, then the corresponding specifics page will contain validation results for all relevant residues and ligands in the PDB entries you specified. See section 3.2 for a description of the contents of the specifics page, and how to interpret these contents. The ValidatorDB synopsis page further provides access to various data sets of PDB-wide validations via 3 different tabs, namely Overview, Details by Residue, and Details by PDB entry. A full description of each of these tab is given below (sections 2.1.1-2.1.3).

====Overview====
The Overview tab of the synopsis page provides a very general statistical evaluation of results across the entire PDB in graphical form (Figures 1A,3A). The elements of the graph represent percentages of the total number of motifs (over 200,000) of residues relevant for validation. A graphic element will be displayed in the Overview graph only if it represents at least 0.5% of the total number of motifs. Each element of the graph is described in a tool tip, but note that here the term residue actually refers to occurrence of residue(motif).

The elements of the graph can be assigned to roughly 6 categories, depending on which kind of information they contain (e.g., incomplete residue, chirality issues, warnings, etc.). The categories are marked by different colors (Figure 3A). Most of the graph elements have been explained in section 3.7 of this manual. The additional elements are Analyzed, which refers to the total number of motifs that could be processed, Missing Atoms or Rings, which is the sum of Missing (Only) Atoms and Missing Rings, and Has All Atoms and Rings, which is the total number of complete residues.

====Details tabs====

Details of the validation are provided in a tabular form separately for Residues and Structures.

* Each Details tab (Figures 3B and 3C) contains an interactive table summarizing the results for each residue validated across the entire PDB.
* Each row corresponds to a single residue (identified by its residue 3-letter code) or a PDB entry (using its 4-letter code). The information in the table is organized according to the validation results as presented in section about [[#Validation results|results]]. The color coding for the table header and the font inside the table is the same as in the categories defined in the Overview tab. Each element of the table header is described in a tool tip, but note that here the term residue actually refers to occurrence of residue (motif).
* The table is interactive. Clicking on any element in the table header allows to sort the table entries according to that element. Click on any residue name in order to access the ValidatorDB specifics page with detailed validation results for that residue (see section 3.2).
* The filter at the top right corner allows to retrieve the table row with a specific residue. Simply type the residue name into the filter. All results can be downloaded in .csv format using the download button at the top left corner.

==Specifics page==

The ValidatorDB specifics page is accessible from the synopsis page, either via the LookUp bar on the Overview tab (Figure 1A), or via the residue names and PDB IDs in the interactive tables on the tabs Details by Residue(Figure 3B) and Details by PDB Entry (Figure 3C), respectively. Depending on how it was accessed, the specifics page might retrieve validation results for one or more residues, a fact mentioned at the very top of the page(Figure 1B).

The ValidatorDB specifics page (Figures 1B,4,5)provides a straightforward report of the validation results, including a summary and detailed information in both tabular and graphical form, along with a 3D structure visualizer for closer inspection of the problematic structures. These reports are accessible via several tabs on the specifics page, namely Summary, Details, Processing Errors/Warnings, and Overview. These tabs will be described in detail in sections 3.2.1 - 3.2.4.Inspecting the tabular and graphical validation reports accessible on the specifics page is the most comfortable and effective way to evaluate the results. Additionally, you may use the JSON Data download button at the top right corner of the specifics page in order to download the complete validation reports and perform any additional analyses on your own.

====Summary====

On the ValidatorDB specifics page, the first view of the results is available in the Summary tab (Figures 1 B,4A). For each validated residue, the Summary tab provides an overview of potential issues encountered, as described in section 2.7.

If more than one residue were validated in one run, a list of these residues will be at the top of the page. In order to examine the validation summary for each residue, you will need to either click on that specific residue in the list, or just scroll down the page till you reach it. Each validated residue is identified by its 3-letter code, as well as its chemical formula and common name. Validation statistics are given as absolute numbers and percentages over all the motifs that were processed for each residue.

The table with the validation report is organized into two main sections, referring to incomplete(Missing Atoms or Rings) and complete structures (With All Atoms and Rings) respectively. The formal distinction between ring atoms and non-ring atoms (simply denoted as atoms ) is meant to allow a quick localization of potential issues in residues containing rings, especially where atom identifiers are not useful. Chirality is evaluated only for the complete structures, since the absence of some atoms makes it difficult to check the chirality of some of the remaining atoms. Further, the problematic atoms are highlighted, in order to better localize the problems in the structures.

Last, a 2D representation of the model residue, and a pie chart with the validation results are provided for visual representation purposes. You can download them via the small icon at the top right corner of the chart, and later use them in your presentations.

====Details====

Whereas the Summary tab provides statistics of the issues over all validated motifs for each validated residue, the Details tab of the ValidatorDB specifics page allows you to inspect the issues in select groups of motifs, and further in each individual motif(Figure 5A). Note that you may also access the details of any particular group of motifs also by clicking on a specific issue in any Summary tab table.

The Details tab is organized into a table where each row contains information regarding a single validated motif. The content of the table (i.e., which motifs are included, and what information is displayed) is dictated by the values of three selection fields at the top of the table. Click on the first field, and select the validated residue by its name (3-letter code) from the drop down menu. Only the motifs that were matched to that residue name will be displayed in the table. Click on the second field and select the type of issue (e.g., wrong chirality) from the drop down menu. Only the motifs which exhibit that type of issue will be displayed in the table. The number of motifs that fit each selection is given in brackets. If you want to make your selection even more specific, use the selection filed Id filter.

Which table columns are filled depend mostly on the type of issue selected in the filter. The most important columns are Id, Issues/Warnings, Missing atoms/rings, Atoms, Processing warnings. The other columns give additional information, usually helpful in identifying the source of the error in the structure. The column Id refers to a unique identifier assigned to each motif in order to keep a transparent trace of the motif's origin, as it contains the PDB ID, as well as the serial index of the first atom in the motif, as it appears in the original PDB entry. The column Issues/Warnings reports the number of issues or warnings found for each particular motif. The column Missing atoms/rings explains which atoms are missing in each validated motif, whereas Atoms shows the position of incorrect chirality. Missing atoms are listed by their atom identifier in the model, whereas atoms with wrong chirality are listed by their identifier in the validated motif. Clicking on a column header allows to sort the motifs according to the property specified in the header.

====3D visualization====
The 3D viewer implemented in the ValidatorDB interface offers one step further in the analysis of each individual validated motif, and is accessible via the Details tab on the specifics page(Figure 5B). In the table, simply click on the Id of a motif of interest in order to open the 3D viewer, where you can inspect the structural inaccuracies more closely. Here you will be able to view and manipulate with the 3D representations of the validated motif and model residue, to help you better assess the position and relevance of the structural issues found during validation. Additionally, a 2D representation of the model is provided for clarity, which is especially helpful for larger motifs. Basic information about the validated motif is also given, along with a complete report of the validation results, where all the potential issues are listed.

====Processing warnings and processing errors====

The validation reports in ValidatorDB also mention various unusual aspects encountered during validation. Sometimes the processed PDB entries contain information that is ambiguous, conflicting or which deviates strongly from the expected reference. ValidatorDB reports such events as processing warnings or processing errors, depending on the severity of the deviations. Such information can be found in the Processing Errors/Warnings tab on the specifics page. The selection field at the top of the page helps filter the warnings and errors. Simply click on the drop down menu and select the category of warnings or errors that you would like to explore. Processing warnings are issues that may cause incorrect Validation, such as atoms that are too close in the 3D space, or unusual bond lengths given by the CONECT records. ValidatorDB typically reports several kinds of warnings: substitutions, foreign atoms, different naming, alternate locations and zero model RMSD, planar chiral center, unusual bond lengths, etc. It is always good to check and make sure that negative validation results (e.g., missing atoms) are not in fact caused by ignoring some atoms in an ill-formed structure.

Processing errors are major issues preventing the finalization of the validation, such as parts of the residue which are completely disconnected from the rest of the structure, probably due to missing atoms at multiple locations throughout the structure. Any major errors in the input file, such as atoms that are completely disconnected from the rest of the structure, are reported as processing errors, and these structures are not processed at all.

It is important to note the difference between processing warnings and processing errors. A warning may simply lead to ignoring a faulty atom, but the motif is validated. On the other hand, a processing error prevents entire motifs from being validated, so you will not find these motifs in the statistics available on either the synopsis or specifics page. The number of motifs with processing errors can be easily calculated as the difference between total motifs of relevant residues in the PDB, and the number of analyzed motifs (currently around 2000 motifs, about 0.5% of relevant motifs in the PDB). Further, because ValidatorDB
automatically extracts all motifs of a relevant residue and assigns them a unique and informative motif Id, you will be able to easily find the motif in its original PDB entry, and explore it.

====Overview====

To keep consistency with the synopsis page, the specifics page also allows visualization of general validation statistics for a selected number of residues via the Overview tab. This representation is entirely compatible with that of the Overview tab on the synopsis page(Figure 5A), and in fact makes up a subset of that data set. All color coding conventions are kept, and tool tips provide descriptions of each graphical element.

==References==
<references/>

ValidatorDB

2014-06-26T00:17:52Z

Dave: /* Synopsis page */

The advancement of research in structural biology has provided a large body of structural data deposited in various databases. One great example is the Protein Data Bank (PDB), which has been growing exponentially, and which currently consists of more than 100,000 structures of biomolecules and their complexes. Such large bodies of data, especially accumulated over a short period of time using high throughput techniques, will inherently be plagued by various problems.

Validation arose as a major issue in the structural biology community when it became apparent that some published structures contained serious errors, and only sometimes it is properly explained(e.g., due to insufficient electron density in a certain area). Structural databases generally require that the new submissions be checked prior to acceptance. The tools employed for presubmission validations work fairly well for residues like amino acids or nucleotides. However, an essential step in the validation process is checking the ligand structure, because ligands play a key role in protein function, and also because they are the main source of errors in structures. Ligand validation, as well as the validation of uncommon residues, are very challenging tasks, because of the high diversity and nontriviality of their structure, and the general lack of information about correct structures. Therefore, software tools focused on ligand validation were developed relatively recently,<ref>Lütteke T, von der Lieth C-W. {BMC Bioinformatics} (2004) 5, 69.</ref><ref>Kleywegt GJ, Harris MR. Acta Crystallographica D. Biological Crystallography (2007) 63: 935–8.</ref>, and the topic is still under active development<ref>ftp://ftp.ebi.ac.uk/pub/databases/pdb/validation_reports/</ref>. These tools are able to validate one or more structures (even thousands of structures), but they are not able to provide the broad scientific community with a more complex image of the quality of structures in dedicated and well established structural databases. For example, a general overview and corresponding statistical evaluation of validation results for residues and ligands in the entire PDB is not yet available, despite the exponential growth of the PDB and the development of structural validation tools in recent years.

We had recently developed MotiveValidator<ref>Svobodová Vařeková R, Jaiswal D, Sehnal D, Ionescu CM, Geidl S, Pravda L, Horský V, Wimmerová M, Koca J, Nucleic Acids Research (2014) doi:10.1093/nar/gku426</ref>, an interactive platform for the speedy validation of ligands, residues and fragments using a novel, straightforward approach based on the validation of residue annotation. MotiveValidator employs advanced algorithms for the detection and comparison of structural motifs<ref>Sehnal D, Svobodová Vařeková R, Huber HJ, Geidl S, Ionescu CM, Wimmerová M, Koca J, Journal of Chemical Information and Modeling 52(2), (2012): 343-359</ref>, along with tools for chirality verification<ref>O'Boyle NM, Banck M, James CA, Morley C, Vandermeersch T, Hutchison GR, Journal of Chemoinformatics 3, (2011): 33</ref> and interactive visualization of 3D structures <ref>http://www.chemdoodle.com</ref>. Using MotiveValidator, we further created ValidatorDB, a comprehensive resource of validation results for residues and ligands in the Protein Data Bank. Along with validation results for individual residues and ligands, ValidatorDB also provides a summary and statistical evaluation of the validation results at various levels of detail within the PDB. Thus, ValidatorDB offers a comprehensive overview of the quality of the ligand structures in the entire PDB. ValidatorDB contains precomputed validation results for ligands and residues in the Protein Data Bank. The database is updated on a weekly basis.

The residues deemed relevant for validation are all ligands and residues with reasonable size (more than six heavy atoms), with the exception of standard amino acids and nucleotides. The validation is performed using MotiveValidator, and the residue models from wwPDB Chemical Component Dictionary (wwPDB CCD) are used as reference structures for validation.

==Availability and technical details==

===Where to find ValidatorDB===
ValidatorDB is freely available online since May 2014 at http://ncbr.muni.cz/MotiveValidatorDB. There is no login requirement for accessing ValidatorDB.

===What you need in order to access ValidatorDB===
ValidatorDB is basically a database, or rather a collection of validation results for ligands and residues in Protein Data Bank. The database is maintained at the National Centre for Biomolecular Research within Masaryk University, Czech Republic, and updated weekly. All you need in order to access ValidatorDB is an internet browser and has JavaScript enabled. The only functionality that relies on your system is the display of 3D models, for which your browser will need to support WebGL. If you experience trouble displaying the 3D models, please check http://get.webgl.org in order to find out how to enable WebGL on your system.

===How to get around the web page===

As soon as you type in the address http://ncbr.muni.cz/ValidatorDB, you will reach the ValidatorDB synopsis page, which contains a brief, general description of ValidatorDB, along with 3 tabs. The different tabs on the ValidatorDB synopsis page provide access to overviews and statistical evaluation of validation results for the entire PDB, for each residue across all PDB IDs containing that residue, and for all analyzed residues in each PDB ID, in graphical or tabular form. Click on each tab to discover what type of overview can be accessed. Further, the ValidatorDB specifics page, which is accessible by looking up specific residues or PDB IDs in the synopsis page, allows to view the results for selected residues in more detail. The specifics page is also organized into tabs that allow different levels of analysis of the results. Last but not least, remember to check the tool tips by hovering the mouse cursor over any graphical or textual element in the ValidatorDB interface.

Before moving on to more extensive descriptions of features, it is important to clearly establish the meaning of a few key terms and principles within the ValidatorDB environment. See [[MotiveValidator:Terminology|Terminology]].

==Basic Principles==

===Residues and ligands relevant for validation===

As mentioned in section 1, well studied residues like amino acids and nucleotides are routinely validated upon submission of new structures to the PDB. Furthermore, reports of the quality of their structure are already accessible. The challenge addressed by
ValidatorDB lies in providing access to validation results for residues other than the well studied amino acids and nucleotides. This generally includes ligands and uncommon residues (e.g. substituted amino acids), which exhibit high diversity and nontriviality in their structure, and for which there is generally much less information regarding correct structures. Thus, within the ValidatorDB environment, we further refine the meaning of the terms residue and ligand to refer to residues and ligands relevant for validation. Specifically, these are all ligands and residues with reasonable size (more than six heavy atoms), with the exception of amino acids and nucleotides. All other features of the terms residue and ligand described in sections 2.1 and 2.2 are maintained. Henceforth, all references to residues and ligands in the ValidatorDB web pages (including Wiki and tutorial) have the meaning of residues and ligands relevant for validation. The PDB currently holds over 170,00 residues and ligands relevant for validation.

===Validation===
[[File:VDB_manual_figures2.png|thumb|right|Validation process: figure 1]]
As stated in section, the validation results stored in ValidatorDB are updated every week. Within the ValidatorDB environment, the term validation refers to the process of determining whether a residue or ligand is structurally complete and correctly annotated. This means checking if the topology and chirality of each motif of a validated residue (section 2.4) correspond to those of the model residue (section 2.5) with the same name as the validated residue.
The validation of residues and ligands in the entire PDB takes place in a few distinct steps. First, for each PDB entry, the residues which are relevant for validation are detected based on their name (3-letter code) and number of atoms (more than 6 heavy atoms). Amino acid residues and nucleotides are excluded based on their residue name. Then, for each validated residue, the corresponding model (same 3-letter code as the validated residue) is retrieved from wwPDB CCD, and each motif of this residue is validated against the model.

ValidatorDB is then built as the collection of validation results for all motifs of all residues in all PDB entries(Figure 1A).
The validation of each motif against the model residue can be illustrated on a galactose (GAL)motif from the PDB entry 1bzw
(Figure 1B). The validated residue GAL is extracted form PDB entry 1bzw in the form of an input motif , which contains all the atoms of the validated residue, together with all atoms found within one or two bonds of any atom from the validated residue
(surroundings). Then, by superimposing the input motif and model residue, the validated motif is obtained as the subset of atoms in the input motif which have a correspondent atom in the model residue. Comparing each atom and bond in the validated motif to those in the model residue produces the validation results.

==Validation results==
For each validated motif, ValidatorDB contains several types of results. Since the evaluation of the validated motif relies on comparing all atoms and bonds in the validated motif to those in the model residue, the first results that can be encountered are errors. Namely:

*Missing atoms: an atom in the model residue has no corresponding atom in the validated motif.

*Missing rings: at least one missing atom originates from cycles (rings).

*Wrong chirality: an atom from the validated motif has different chirality than the corresponding atom from the model residue.

*Wrong chirality (planar): the chirality error was found on a planar chiral center. Because of their spacial distribution, planar chiral centers are very sensitive even to small perturbations in the position of the substituents. Therefore, some of the errors reported here might not be significant.

*Uncertain chirality: the presence of unusual bonds may cause an improper evaluation of chirality.

Chirality is only evaluated for those motifs which are complete. This is because the absence of some atoms can prevent the proper evaluation of chirality on the chiral centers present in the validated motif. Therefore, note that all motifs which are counted in the Wrong chirality category are in fact complete. At the same time, the motifs with no missing atoms and no chirality error are actually counted in a category called Correct chirality.

--------------------------
Suspicious discrepancies between the atoms and inter-atomic bonds in the validated motif and in the model residue are reported as warnings. Namely:

*Substitution: an atom from the validated motif is of a different chemical element than the corresponding atom in the model residue (e.g. O mapped to N). This happens often at linkage sites.

*Different naming: an atom from the validated motif has a different PDB atom name than the corresponding atom from the model residue (e.g. the C1 atom mapped to the C7 atom). This happens often when the original PDB files were produced by different software.

*Foreign atom: an atom from the model residue was mapped to an atom from outside the validated residue (i.e. from its surroundings).

*Alternate locations: in the original PDB file, the validated residue contains atoms which were given in alternate locations (i.e., most probably different rotamers). Only the first rotamer was considered during validation.

*Zero model RMSD: the superimposition between the model residue and the validated motif has a root mean square deviation of zero, i.e., the validated motif is identical to the model residue used as reference.

Disabling discrepancies between the atoms and inter-atomic bonds in the validated motif and in the model residue are reported as
processing errors, and such motifs are not validated.

Typical validation results that can be found in ValidatorDB are illustrated on the galactose motif mentioned in section 2.6(Fig 1C). As a general rule, in the ValidatorDB interface, errors are marked in red (missing atoms) or dark yellow (wrong chirality), correct structures in green, and warnings in cyan.

==Database contents==
ValidatorDB contains precomputed validation results for ligands and residues in the Protein Data Bank. The database is updated on a weekly basis. The validation is performed using Validator, and the residue models from wwPDB CCD are used as reference templates for validation. All residues of significant size (a minimum of 6 heavy atoms) have been included in ValidatorDB, with the exception of amino acids and nucleotides, which are checked thoroughly upon submission of the structure to the PDB, and thus do not require additional validation.

The validation results available in ValidatorDB inform whether each motif (occurrence, instance) of a ligand or residue in the PDB exhibits the appropriate topology and stereochemistry expected from its annotation (3-letter code), or how it differs from this annotation. Additionally, all issues related to incorrect or suspicious topology and stereochemistry are explicitly described in a comprehensive and intuitive manner (e.g., location of missing atoms or chirality inversions).

ValidatorDB is organized on two main levels, namely PDB-wide results (synopsis page), and results restricted to specific residues of interest (specifics page). The two levels present the same type of validation results (as described in section 2.7), although the available features differ to some extent (e.g., the specifics page allows 3D visualization of motifs). We shall describe each level of the database in detail below.

==Synopsis page==

The ValidatorDB synopsis page(Figures1A, 3) contains a brief description of ValidatorDB, along with information about the last database update (date and number of structures that have been processed during the validation). Specifically, in May 2014, over 100,000 PDB entries had been processed, containing over 230,000 motifs of 17,000 residues relevant for validation.
Additionally, the synopsis page allows to access the validation results for specific residues of interest via the LookUp bar
(Figure 1A). Simply type a comma separated list of residue names (3-letter codes) into the LookUp bar, and you will be redirected to the specifics page containing validation results for the residues you requested. If you specify a list of PDB IDs (4-letter codes)instead, then the corresponding specifics page will contain validation results for all relevant residues and ligands in the PDB entries you specified. See section 3.2 for a description of the contents of the specifics page, and how to interpret these contents. The ValidatorDB synopsis page further provides access to various data sets of PDB-wide validations via 3 different tabs, namely Overview, Details by Residue, and Details by PDB entry. A full description of each of these tab is given below (sections 2.1.1-2.1.3).

====Overview====
The Overview tab of the synopsis page provides a very general statistical evaluation of results across the entire PDB in graphical form (Figures 1A,3A). The elements of the graph represent percentages of the total number of motifs (over 200,000) of residues relevant for validation. A graphic element will be displayed in the Overview graph only if it represents at least 0.5% of the total number of motifs. Each element of the graph is described in a tool tip, but note that here the term residue actually refers to occurrence of residue(motif).

The elements of the graph can be assigned to roughly 6 categories, depending on which kind of information they contain (e.g., incomplete residue, chirality issues, warnings, etc.). The categories are marked by different colors (Figure 3A). Most of the graph elements have been explained in section 3.7 of this manual. The additional elements are Analyzed, which refers to the total number of motifs that could be processed, Missing Atoms or Rings, which is the sum of Missing (Only) Atoms and Missing Rings, and Has All Atoms and Rings, which is the total number of complete residues.

====Details tabs====

Details of the validation are provided in a tabular form separately for Residues and Structures.

* Each Details tab (Figures 3B and 3C) contains an interactive table summarizing the results for each residue validated across the entire PDB.
* Each row corresponds to a single residue (identified by its residue 3-letter code) or a PDB entry (using its 4-letter code). The information in the table is organized according to the validation results as presented in section about [[#Validation results|results]]. The color coding for the table header and the font inside the table is the same as in the categories defined in the Overview tab. Each element of the table header is described in a tool tip, but note that here the term residue actually refers to occurrence of residue (motif).
* The table is interactive. Clicking on any element in the table header allows to sort the table entries according to that element. Click on any residue name in order to access the ValidatorDB specifics page with detailed validation results for that residue (see section 3.2).
* The filter at the top right corner allows to retrieve the table row with a specific residue. Simply type the residue name into the filter. All results can be downloaded in .csv format using the download button at the top left corner.

==Specifics page==

The ValidatorDB specifics page is accessible from the synopsis page, either via the LookUp bar on the Overview tab (Figure 1A), or via the residue names and PDB IDs in the interactive tables on the tabs Details by Residue(Figure 3B) and Details by PDB Entry (Figure 3C), respectively. Depending on how it was accessed, the specifics page might retrieve validation results for one or more residues, a fact mentioned at the very top of the page(Figure 1B).

The ValidatorDB specifics page (Figures 1B,4,5)provides a straightforward report of the validation results, including a summary and detailed information in both tabular and graphical form, along with a 3D structure visualizer for closer inspection of the problematic structures. These reports are accessible via several tabs on the specifics page, namely Summary, Details, Processing Errors/Warnings, and Overview. These tabs will be described in detail in sections 3.2.1 - 3.2.4.Inspecting the tabular and graphical validation reports accessible on the specifics page is the most comfortable and effective way to evaluate the results. Additionally, you may use the JSON Data download button at the top right corner of the specifics page in order to download the complete validation reports and perform any additional analyses on your own.

====Summary====

On the ValidatorDB specifics page, the first view of the results is available in the Summary tab (Figures 1 B,4A). For each validated residue, the Summary tab provides an overview of potential issues encountered, as described in section 2.7.

If more than one residue were validated in one run, a list of these residues will be at the top of the page. In order to examine the validation summary for each residue, you will need to either click on that specific residue in the list, or just scroll down the page till you reach it. Each validated residue is identified by its 3-letter code, as well as its chemical formula and common name. Validation statistics are given as absolute numbers and percentages over all the motifs that were processed for each residue.

The table with the validation report is organized into two main sections, referring to incomplete(Missing Atoms or Rings) and complete structures (With All Atoms and Rings) respectively. The formal distinction between ring atoms and non-ring atoms (simply denoted as atoms ) is meant to allow a quick localization of potential issues in residues containing rings, especially where atom identifiers are not useful. Chirality is evaluated only for the complete structures, since the absence of some atoms makes it difficult to check the chirality of some of the remaining atoms. Further, the problematic atoms are highlighted, in order to better localize the problems in the structures.

Last, a 2D representation of the model residue, and a pie chart with the validation results are provided for visual representation purposes. You can download them via the small icon at the top right corner of the chart, and later use them in your presentations.

====Details====

Whereas the Summary tab provides statistics of the issues over all validated motifs for each validated residue, the Details tab of the ValidatorDB specifics page allows you to inspect the issues in select groups of motifs, and further in each individual motif(Figure 5A). Note that you may also access the details of any particular group of motifs also by clicking on a specific issue in any Summary tab table.

The Details tab is organized into a table where each row contains information regarding a single validated motif. The content of the table (i.e., which motifs are included, and what information is displayed) is dictated by the values of three selection fields at the top of the table. Click on the first field, and select the validated residue by its name (3-letter code) from the drop down menu. Only the motifs that were matched to that residue name will be displayed in the table. Click on the second field and select the type of issue (e.g., wrong chirality) from the drop down menu. Only the motifs which exhibit that type of issue will be displayed in the table. The number of motifs that fit each selection is given in brackets. If you want to make your selection even more specific, use the selection filed Id filter.

Which table columns are filled depend mostly on the type of issue selected in the filter. The most important columns are Id, Issues/Warnings, Missing atoms/rings, Atoms, Processing warnings. The other columns give additional information, usually helpful in identifying the source of the error in the structure. The column Id refers to a unique identifier assigned to each motif in order to keep a transparent trace of the motif's origin, as it contains the PDB ID, as well as the serial index of the first atom in the motif, as it appears in the original PDB entry. The column Issues/Warnings reports the number of issues or warnings found for each particular motif. The column Missing atoms/rings explains which atoms are missing in each validated motif, whereas Atoms shows the position of incorrect chirality. Missing atoms are listed by their atom identifier in the model, whereas atoms with wrong chirality are listed by their identifier in the validated motif. Clicking on a column header allows to sort the motifs according to the property specified in the header.

====3D visualization====
The 3D viewer implemented in the ValidatorDB interface offers one step further in the analysis of each individual validated motif, and is accessible via the Details tab on the specifics page(Figure 5B). In the table, simply click on the Id of a motif of interest in order to open the 3D viewer, where you can inspect the structural inaccuracies more closely. Here you will be able to view and manipulate with the 3D representations of the validated motif and model residue, to help you better assess the position and relevance of the structural issues found during validation. Additionally, a 2D representation of the model is provided for clarity, which is especially helpful for larger motifs. Basic information about the validated motif is also given, along with a complete report of the validation results, where all the potential issues are listed.

====Processing warnings and processing errors====

The validation reports in ValidatorDB also mention various unusual aspects encountered during validation. Sometimes the processed PDB entries contain information that is ambiguous, conflicting or which deviates strongly from the expected reference. ValidatorDB reports such events as processing warnings or processing errors, depending on the severity of the deviations. Such information can be found in the Processing Errors/Warnings tab on the specifics page. The selection field at the top of the page helps filter the warnings and errors. Simply click on the drop down menu and select the category of warnings or errors that you would like to explore. Processing warnings are issues that may cause incorrect Validation, such as atoms that are too close in the 3D space, or unusual bond lengths given by the CONECT records. ValidatorDB typically reports several kinds of warnings: substitutions, foreign atoms, different naming, alternate locations and zero model RMSD, planar chiral center, unusual bond lengths, etc. It is always good to check and make sure that negative validation results (e.g., missing atoms) are not in fact caused by ignoring some atoms in an ill-formed structure.

Processing errors are major issues preventing the finalization of the validation, such as parts of the residue which are completely disconnected from the rest of the structure, probably due to missing atoms at multiple locations throughout the structure. Any major errors in the input file, such as atoms that are completely disconnected from the rest of the structure, are reported as processing errors, and these structures are not processed at all.

It is important to note the difference between processing warnings and processing errors. A warning may simply lead to ignoring a faulty atom, but the motif is validated. On the other hand, a processing error prevents entire motifs from being validated, so you will not find these motifs in the statistics available on either the synopsis or specifics page. The number of motifs with processing errors can be easily calculated as the difference between total motifs of relevant residues in the PDB, and the number of analyzed motifs (currently around 2000 motifs, about 0.5% of relevant motifs in the PDB). Further, because ValidatorDB
automatically extracts all motifs of a relevant residue and assigns them a unique and informative motif Id, you will be able to easily find the motif in its original PDB entry, and explore it.

====Overview====

To keep consistency with the synopsis page, the specifics page also allows visualization of general validation statistics for a selected number of residues via the Overview tab. This representation is entirely compatible with that of the Overview tab on the synopsis page(Figure 5A), and in fact makes up a subset of that data set. All color coding conventions are kept, and tool tips provide descriptions of each graphical element.

==References==
<references/>

ValidatorDB

2014-06-26T00:16:35Z

Dave: /* Details by Residue */

The advancement of research in structural biology has provided a large body of structural data deposited in various databases. One great example is the Protein Data Bank (PDB), which has been growing exponentially, and which currently consists of more than 100,000 structures of biomolecules and their complexes. Such large bodies of data, especially accumulated over a short period of time using high throughput techniques, will inherently be plagued by various problems.

Validation arose as a major issue in the structural biology community when it became apparent that some published structures contained serious errors, and only sometimes it is properly explained(e.g., due to insufficient electron density in a certain area). Structural databases generally require that the new submissions be checked prior to acceptance. The tools employed for presubmission validations work fairly well for residues like amino acids or nucleotides. However, an essential step in the validation process is checking the ligand structure, because ligands play a key role in protein function, and also because they are the main source of errors in structures. Ligand validation, as well as the validation of uncommon residues, are very challenging tasks, because of the high diversity and nontriviality of their structure, and the general lack of information about correct structures. Therefore, software tools focused on ligand validation were developed relatively recently,<ref>Lütteke T, von der Lieth C-W. {BMC Bioinformatics} (2004) 5, 69.</ref><ref>Kleywegt GJ, Harris MR. Acta Crystallographica D. Biological Crystallography (2007) 63: 935–8.</ref>, and the topic is still under active development<ref>ftp://ftp.ebi.ac.uk/pub/databases/pdb/validation_reports/</ref>. These tools are able to validate one or more structures (even thousands of structures), but they are not able to provide the broad scientific community with a more complex image of the quality of structures in dedicated and well established structural databases. For example, a general overview and corresponding statistical evaluation of validation results for residues and ligands in the entire PDB is not yet available, despite the exponential growth of the PDB and the development of structural validation tools in recent years.

We had recently developed MotiveValidator<ref>Svobodová Vařeková R, Jaiswal D, Sehnal D, Ionescu CM, Geidl S, Pravda L, Horský V, Wimmerová M, Koca J, Nucleic Acids Research (2014) doi:10.1093/nar/gku426</ref>, an interactive platform for the speedy validation of ligands, residues and fragments using a novel, straightforward approach based on the validation of residue annotation. MotiveValidator employs advanced algorithms for the detection and comparison of structural motifs<ref>Sehnal D, Svobodová Vařeková R, Huber HJ, Geidl S, Ionescu CM, Wimmerová M, Koca J, Journal of Chemical Information and Modeling 52(2), (2012): 343-359</ref>, along with tools for chirality verification<ref>O'Boyle NM, Banck M, James CA, Morley C, Vandermeersch T, Hutchison GR, Journal of Chemoinformatics 3, (2011): 33</ref> and interactive visualization of 3D structures <ref>http://www.chemdoodle.com</ref>. Using MotiveValidator, we further created ValidatorDB, a comprehensive resource of validation results for residues and ligands in the Protein Data Bank. Along with validation results for individual residues and ligands, ValidatorDB also provides a summary and statistical evaluation of the validation results at various levels of detail within the PDB. Thus, ValidatorDB offers a comprehensive overview of the quality of the ligand structures in the entire PDB. ValidatorDB contains precomputed validation results for ligands and residues in the Protein Data Bank. The database is updated on a weekly basis.

The residues deemed relevant for validation are all ligands and residues with reasonable size (more than six heavy atoms), with the exception of standard amino acids and nucleotides. The validation is performed using MotiveValidator, and the residue models from wwPDB Chemical Component Dictionary (wwPDB CCD) are used as reference structures for validation.

==Availability and technical details==

===Where to find ValidatorDB===
ValidatorDB is freely available online since May 2014 at http://ncbr.muni.cz/MotiveValidatorDB. There is no login requirement for accessing ValidatorDB.

===What you need in order to access ValidatorDB===
ValidatorDB is basically a database, or rather a collection of validation results for ligands and residues in Protein Data Bank. The database is maintained at the National Centre for Biomolecular Research within Masaryk University, Czech Republic, and updated weekly. All you need in order to access ValidatorDB is an internet browser and has JavaScript enabled. The only functionality that relies on your system is the display of 3D models, for which your browser will need to support WebGL. If you experience trouble displaying the 3D models, please check http://get.webgl.org in order to find out how to enable WebGL on your system.

===How to get around the web page===

As soon as you type in the address http://ncbr.muni.cz/ValidatorDB, you will reach the ValidatorDB synopsis page, which contains a brief, general description of ValidatorDB, along with 3 tabs. The different tabs on the ValidatorDB synopsis page provide access to overviews and statistical evaluation of validation results for the entire PDB, for each residue across all PDB IDs containing that residue, and for all analyzed residues in each PDB ID, in graphical or tabular form. Click on each tab to discover what type of overview can be accessed. Further, the ValidatorDB specifics page, which is accessible by looking up specific residues or PDB IDs in the synopsis page, allows to view the results for selected residues in more detail. The specifics page is also organized into tabs that allow different levels of analysis of the results. Last but not least, remember to check the tool tips by hovering the mouse cursor over any graphical or textual element in the ValidatorDB interface.

Before moving on to more extensive descriptions of features, it is important to clearly establish the meaning of a few key terms and principles within the ValidatorDB environment. See [[MotiveValidator:Terminology|Terminology]].

==Basic Principles==

===Residues and ligands relevant for validation===

As mentioned in section 1, well studied residues like amino acids and nucleotides are routinely validated upon submission of new structures to the PDB. Furthermore, reports of the quality of their structure are already accessible. The challenge addressed by
ValidatorDB lies in providing access to validation results for residues other than the well studied amino acids and nucleotides. This generally includes ligands and uncommon residues (e.g. substituted amino acids), which exhibit high diversity and nontriviality in their structure, and for which there is generally much less information regarding correct structures. Thus, within the ValidatorDB environment, we further refine the meaning of the terms residue and ligand to refer to residues and ligands relevant for validation. Specifically, these are all ligands and residues with reasonable size (more than six heavy atoms), with the exception of amino acids and nucleotides. All other features of the terms residue and ligand described in sections 2.1 and 2.2 are maintained. Henceforth, all references to residues and ligands in the ValidatorDB web pages (including Wiki and tutorial) have the meaning of residues and ligands relevant for validation. The PDB currently holds over 170,00 residues and ligands relevant for validation.

===Validation===
[[File:VDB_manual_figures2.png|thumb|right|Validation process: figure 1]]
As stated in section, the validation results stored in ValidatorDB are updated every week. Within the ValidatorDB environment, the term validation refers to the process of determining whether a residue or ligand is structurally complete and correctly annotated. This means checking if the topology and chirality of each motif of a validated residue (section 2.4) correspond to those of the model residue (section 2.5) with the same name as the validated residue.
The validation of residues and ligands in the entire PDB takes place in a few distinct steps. First, for each PDB entry, the residues which are relevant for validation are detected based on their name (3-letter code) and number of atoms (more than 6 heavy atoms). Amino acid residues and nucleotides are excluded based on their residue name. Then, for each validated residue, the corresponding model (same 3-letter code as the validated residue) is retrieved from wwPDB CCD, and each motif of this residue is validated against the model.

ValidatorDB is then built as the collection of validation results for all motifs of all residues in all PDB entries(Figure 1A).
The validation of each motif against the model residue can be illustrated on a galactose (GAL)motif from the PDB entry 1bzw
(Figure 1B). The validated residue GAL is extracted form PDB entry 1bzw in the form of an input motif , which contains all the atoms of the validated residue, together with all atoms found within one or two bonds of any atom from the validated residue
(surroundings). Then, by superimposing the input motif and model residue, the validated motif is obtained as the subset of atoms in the input motif which have a correspondent atom in the model residue. Comparing each atom and bond in the validated motif to those in the model residue produces the validation results.

==Validation results==
For each validated motif, ValidatorDB contains several types of results. Since the evaluation of the validated motif relies on comparing all atoms and bonds in the validated motif to those in the model residue, the first results that can be encountered are errors. Namely:

*Missing atoms: an atom in the model residue has no corresponding atom in the validated motif.

*Missing rings: at least one missing atom originates from cycles (rings).

*Wrong chirality: an atom from the validated motif has different chirality than the corresponding atom from the model residue.

*Wrong chirality (planar): the chirality error was found on a planar chiral center. Because of their spacial distribution, planar chiral centers are very sensitive even to small perturbations in the position of the substituents. Therefore, some of the errors reported here might not be significant.

*Uncertain chirality: the presence of unusual bonds may cause an improper evaluation of chirality.

Chirality is only evaluated for those motifs which are complete. This is because the absence of some atoms can prevent the proper evaluation of chirality on the chiral centers present in the validated motif. Therefore, note that all motifs which are counted in the Wrong chirality category are in fact complete. At the same time, the motifs with no missing atoms and no chirality error are actually counted in a category called Correct chirality.

--------------------------
Suspicious discrepancies between the atoms and inter-atomic bonds in the validated motif and in the model residue are reported as warnings. Namely:

*Substitution: an atom from the validated motif is of a different chemical element than the corresponding atom in the model residue (e.g. O mapped to N). This happens often at linkage sites.

*Different naming: an atom from the validated motif has a different PDB atom name than the corresponding atom from the model residue (e.g. the C1 atom mapped to the C7 atom). This happens often when the original PDB files were produced by different software.

*Foreign atom: an atom from the model residue was mapped to an atom from outside the validated residue (i.e. from its surroundings).

*Alternate locations: in the original PDB file, the validated residue contains atoms which were given in alternate locations (i.e., most probably different rotamers). Only the first rotamer was considered during validation.

*Zero model RMSD: the superimposition between the model residue and the validated motif has a root mean square deviation of zero, i.e., the validated motif is identical to the model residue used as reference.

Disabling discrepancies between the atoms and inter-atomic bonds in the validated motif and in the model residue are reported as
processing errors, and such motifs are not validated.

Typical validation results that can be found in ValidatorDB are illustrated on the galactose motif mentioned in section 2.6(Fig 1C). As a general rule, in the ValidatorDB interface, errors are marked in red (missing atoms) or dark yellow (wrong chirality), correct structures in green, and warnings in cyan.

==Database contents==
ValidatorDB contains precomputed validation results for ligands and residues in the Protein Data Bank. The database is updated on a weekly basis. The validation is performed using Validator, and the residue models from wwPDB CCD are used as reference templates for validation. All residues of significant size (a minimum of 6 heavy atoms) have been included in ValidatorDB, with the exception of amino acids and nucleotides, which are checked thoroughly upon submission of the structure to the PDB, and thus do not require additional validation.

The validation results available in ValidatorDB inform whether each motif (occurrence, instance) of a ligand or residue in the PDB exhibits the appropriate topology and stereochemistry expected from its annotation (3-letter code), or how it differs from this annotation. Additionally, all issues related to incorrect or suspicious topology and stereochemistry are explicitly described in a comprehensive and intuitive manner (e.g., location of missing atoms or chirality inversions).

ValidatorDB is organized on two main levels, namely PDB-wide results (synopsis page), and results restricted to specific residues of interest (specifics page). The two levels present the same type of validation results (as described in section 2.7), although the available features differ to some extent (e.g., the specifics page allows 3D visualization of motifs). We shall describe each level of the database in detail below.

==Synopsis page==

The ValidatorDB synopsis page(Figures1A, 3) contains a brief description of ValidatorDB, along with information about the last database update (date and number of structures that have been processed during the validation). Specifically, in May 2014, over 100,000 PDB entries had been processed, containing over 230,000 motifs of 17,000 residues relevant for validation.
Additionally, the synopsis page allows to access the validation results for specific residues of interest via the LookUp bar
(Figure 1A). Simply type a comma separated list of residue names (3-letter codes) into the LookUp bar, and you will be redirected to the specifics page containing validation results for the residues you requested. If you specify a list of PDB IDs (4-letter codes)instead, then the corresponding specifics page will contain validation results for all relevant residues and ligands in the PDB entries you specified. See section 3.2 for a description of the contents of the specifics page, and how to interpret these contents. The ValidatorDB synopsis page further provides access to various data sets of PDB-wide validations via 3 different tabs, namely Overview, Details by Residue, and Details by PDB entry. A full description of each of these tab is given below (sections 2.1.1-2.1.3).

====Overview====
The Overview tab of the synopsis page provides a very general statistical evaluation of results across the entire PDB in graphical form (Figures 1A,3A). The elements of the graph represent percentages of the total number of motifs (over 200,000) of residues relevant for validation. A graphic element will be displayed in the Overview graph only if it represents at least 0.5% of the total number of motifs. Each element of the graph is described in a tool tip, but note that here the term residue actually refers to occurrence of residue(motif).

The elements of the graph can be assigned to roughly 6 categories, depending on which kind of information they contain (e.g., incomplete residue, chirality issues, warnings, etc.). The categories are marked by different colors (Figure 3A). Most of the graph elements have been explained in section 3.7 of this manual. The additional elements are Analyzed, which refers to the total number of motifs that could be processed, Missing Atoms or Rings, which is the sum of Missing (Only) Atoms and Missing Rings, and Has All Atoms and Rings, which is the total number of complete residues.

====Details tabs====

Details of the validation are provided in a tabular form separately for Residues and Structures.

* Each Details tab (Figures 3B and 3C) contains an interactive table summarizing the results for each residue validated across the entire PDB.
* Each row corresponds to a single residue (identified by its residue 3-letter code) or a PDB entry (using its 4-letter code). The information in the table is organized according to the validation results as presented in section about [[#Validation results|results]]. The color coding for the table header and the font inside the table is the same as in the categories defined in the Overview tab. Each element of the table header is described in a tool tip, but note that here the term residue actually refers to occurrence of residue (motif).
* The table is interactive. Clicking on any element in the table header allows to sort the table entries according to that element. Click on any residue name in order to access the ValidatorDB specifics page with detailed validation results for that residue (see section 3.2).
* The filter at the top right corner allows to retrieve the table row with a specific residue. Simply type the residue name into the filter. All results can be downloaded in .csv format using the download button at the top left corner.

====Details by PDB entry====

The Details by PDB Entry tab (Figure 3C) contains an interactive table summarizing the results for all residues validated in each PDB entry. Each row corresponds to one PDB entry, identified by its PDB ID (4-letter code). The information in the table is organized according to the validation results as presented in section 2.7 of this manual. The color coding for the table header and the font inside the table is the same as in the categories defined in the Overview tab. Each element of the table header is described in a tool tip, but note that here the term residue actually refers to occurrence of residue (motif).

The table is interactive. Clicking on any element in the table header allows to sort the table entries according to that element. Click on any PDB in order to access the ValidatorDB specifics page with detailed validation results for all residues in that PDB entry (see section 3.2).

The filter at the top right corner allows to retrieve the table rows with a specific residue, or the table rows with selected PDB IDs. Simply type the residue name or PDB ID into the filter. All results can be downloaded in .csv format using the download button at the top left corner.

==Specifics page==

The ValidatorDB specifics page is accessible from the synopsis page, either via the LookUp bar on the Overview tab (Figure 1A), or via the residue names and PDB IDs in the interactive tables on the tabs Details by Residue(Figure 3B) and Details by PDB Entry (Figure 3C), respectively. Depending on how it was accessed, the specifics page might retrieve validation results for one or more residues, a fact mentioned at the very top of the page(Figure 1B).

The ValidatorDB specifics page (Figures 1B,4,5)provides a straightforward report of the validation results, including a summary and detailed information in both tabular and graphical form, along with a 3D structure visualizer for closer inspection of the problematic structures. These reports are accessible via several tabs on the specifics page, namely Summary, Details, Processing Errors/Warnings, and Overview. These tabs will be described in detail in sections 3.2.1 - 3.2.4.Inspecting the tabular and graphical validation reports accessible on the specifics page is the most comfortable and effective way to evaluate the results. Additionally, you may use the JSON Data download button at the top right corner of the specifics page in order to download the complete validation reports and perform any additional analyses on your own.

====Summary====

On the ValidatorDB specifics page, the first view of the results is available in the Summary tab (Figures 1 B,4A). For each validated residue, the Summary tab provides an overview of potential issues encountered, as described in section 2.7.

If more than one residue were validated in one run, a list of these residues will be at the top of the page. In order to examine the validation summary for each residue, you will need to either click on that specific residue in the list, or just scroll down the page till you reach it. Each validated residue is identified by its 3-letter code, as well as its chemical formula and common name. Validation statistics are given as absolute numbers and percentages over all the motifs that were processed for each residue.

The table with the validation report is organized into two main sections, referring to incomplete(Missing Atoms or Rings) and complete structures (With All Atoms and Rings) respectively. The formal distinction between ring atoms and non-ring atoms (simply denoted as atoms ) is meant to allow a quick localization of potential issues in residues containing rings, especially where atom identifiers are not useful. Chirality is evaluated only for the complete structures, since the absence of some atoms makes it difficult to check the chirality of some of the remaining atoms. Further, the problematic atoms are highlighted, in order to better localize the problems in the structures.

Last, a 2D representation of the model residue, and a pie chart with the validation results are provided for visual representation purposes. You can download them via the small icon at the top right corner of the chart, and later use them in your presentations.

====Details====

Whereas the Summary tab provides statistics of the issues over all validated motifs for each validated residue, the Details tab of the ValidatorDB specifics page allows you to inspect the issues in select groups of motifs, and further in each individual motif(Figure 5A). Note that you may also access the details of any particular group of motifs also by clicking on a specific issue in any Summary tab table.

The Details tab is organized into a table where each row contains information regarding a single validated motif. The content of the table (i.e., which motifs are included, and what information is displayed) is dictated by the values of three selection fields at the top of the table. Click on the first field, and select the validated residue by its name (3-letter code) from the drop down menu. Only the motifs that were matched to that residue name will be displayed in the table. Click on the second field and select the type of issue (e.g., wrong chirality) from the drop down menu. Only the motifs which exhibit that type of issue will be displayed in the table. The number of motifs that fit each selection is given in brackets. If you want to make your selection even more specific, use the selection filed Id filter.

Which table columns are filled depend mostly on the type of issue selected in the filter. The most important columns are Id, Issues/Warnings, Missing atoms/rings, Atoms, Processing warnings. The other columns give additional information, usually helpful in identifying the source of the error in the structure. The column Id refers to a unique identifier assigned to each motif in order to keep a transparent trace of the motif's origin, as it contains the PDB ID, as well as the serial index of the first atom in the motif, as it appears in the original PDB entry. The column Issues/Warnings reports the number of issues or warnings found for each particular motif. The column Missing atoms/rings explains which atoms are missing in each validated motif, whereas Atoms shows the position of incorrect chirality. Missing atoms are listed by their atom identifier in the model, whereas atoms with wrong chirality are listed by their identifier in the validated motif. Clicking on a column header allows to sort the motifs according to the property specified in the header.

====3D visualization====
The 3D viewer implemented in the ValidatorDB interface offers one step further in the analysis of each individual validated motif, and is accessible via the Details tab on the specifics page(Figure 5B). In the table, simply click on the Id of a motif of interest in order to open the 3D viewer, where you can inspect the structural inaccuracies more closely. Here you will be able to view and manipulate with the 3D representations of the validated motif and model residue, to help you better assess the position and relevance of the structural issues found during validation. Additionally, a 2D representation of the model is provided for clarity, which is especially helpful for larger motifs. Basic information about the validated motif is also given, along with a complete report of the validation results, where all the potential issues are listed.

====Processing warnings and processing errors====

The validation reports in ValidatorDB also mention various unusual aspects encountered during validation. Sometimes the processed PDB entries contain information that is ambiguous, conflicting or which deviates strongly from the expected reference. ValidatorDB reports such events as processing warnings or processing errors, depending on the severity of the deviations. Such information can be found in the Processing Errors/Warnings tab on the specifics page. The selection field at the top of the page helps filter the warnings and errors. Simply click on the drop down menu and select the category of warnings or errors that you would like to explore. Processing warnings are issues that may cause incorrect Validation, such as atoms that are too close in the 3D space, or unusual bond lengths given by the CONECT records. ValidatorDB typically reports several kinds of warnings: substitutions, foreign atoms, different naming, alternate locations and zero model RMSD, planar chiral center, unusual bond lengths, etc. It is always good to check and make sure that negative validation results (e.g., missing atoms) are not in fact caused by ignoring some atoms in an ill-formed structure.

Processing errors are major issues preventing the finalization of the validation, such as parts of the residue which are completely disconnected from the rest of the structure, probably due to missing atoms at multiple locations throughout the structure. Any major errors in the input file, such as atoms that are completely disconnected from the rest of the structure, are reported as processing errors, and these structures are not processed at all.

It is important to note the difference between processing warnings and processing errors. A warning may simply lead to ignoring a faulty atom, but the motif is validated. On the other hand, a processing error prevents entire motifs from being validated, so you will not find these motifs in the statistics available on either the synopsis or specifics page. The number of motifs with processing errors can be easily calculated as the difference between total motifs of relevant residues in the PDB, and the number of analyzed motifs (currently around 2000 motifs, about 0.5% of relevant motifs in the PDB). Further, because ValidatorDB
automatically extracts all motifs of a relevant residue and assigns them a unique and informative motif Id, you will be able to easily find the motif in its original PDB entry, and explore it.

====Overview====

To keep consistency with the synopsis page, the specifics page also allows visualization of general validation statistics for a selected number of residues via the Overview tab. This representation is entirely compatible with that of the Overview tab on the synopsis page(Figure 5A), and in fact makes up a subset of that data set. All color coding conventions are kept, and tool tips provide descriptions of each graphical element.

==References==
<references/>

ValidatorDB

2014-06-26T00:01:25Z

Dave: /* How to get around the web page */

The advancement of research in structural biology has provided a large body of structural data deposited in various databases. One great example is the Protein Data Bank (PDB), which has been growing exponentially, and which currently consists of more than 100,000 structures of biomolecules and their complexes. Such large bodies of data, especially accumulated over a short period of time using high throughput techniques, will inherently be plagued by various problems.

Validation arose as a major issue in the structural biology community when it became apparent that some published structures contained serious errors, and only sometimes it is properly explained(e.g., due to insufficient electron density in a certain area). Structural databases generally require that the new submissions be checked prior to acceptance. The tools employed for presubmission validations work fairly well for residues like amino acids or nucleotides. However, an essential step in the validation process is checking the ligand structure, because ligands play a key role in protein function, and also because they are the main source of errors in structures. Ligand validation, as well as the validation of uncommon residues, are very challenging tasks, because of the high diversity and nontriviality of their structure, and the general lack of information about correct structures. Therefore, software tools focused on ligand validation were developed relatively recently,<ref>Lütteke T, von der Lieth C-W. {BMC Bioinformatics} (2004) 5, 69.</ref><ref>Kleywegt GJ, Harris MR. Acta Crystallographica D. Biological Crystallography (2007) 63: 935–8.</ref>, and the topic is still under active development<ref>ftp://ftp.ebi.ac.uk/pub/databases/pdb/validation_reports/</ref>. These tools are able to validate one or more structures (even thousands of structures), but they are not able to provide the broad scientific community with a more complex image of the quality of structures in dedicated and well established structural databases. For example, a general overview and corresponding statistical evaluation of validation results for residues and ligands in the entire PDB is not yet available, despite the exponential growth of the PDB and the development of structural validation tools in recent years.

We had recently developed MotiveValidator<ref>Svobodová Vařeková R, Jaiswal D, Sehnal D, Ionescu CM, Geidl S, Pravda L, Horský V, Wimmerová M, Koca J, Nucleic Acids Research (2014) doi:10.1093/nar/gku426</ref>, an interactive platform for the speedy validation of ligands, residues and fragments using a novel, straightforward approach based on the validation of residue annotation. MotiveValidator employs advanced algorithms for the detection and comparison of structural motifs<ref>Sehnal D, Svobodová Vařeková R, Huber HJ, Geidl S, Ionescu CM, Wimmerová M, Koca J, Journal of Chemical Information and Modeling 52(2), (2012): 343-359</ref>, along with tools for chirality verification<ref>O'Boyle NM, Banck M, James CA, Morley C, Vandermeersch T, Hutchison GR, Journal of Chemoinformatics 3, (2011): 33</ref> and interactive visualization of 3D structures <ref>http://www.chemdoodle.com</ref>. Using MotiveValidator, we further created ValidatorDB, a comprehensive resource of validation results for residues and ligands in the Protein Data Bank. Along with validation results for individual residues and ligands, ValidatorDB also provides a summary and statistical evaluation of the validation results at various levels of detail within the PDB. Thus, ValidatorDB offers a comprehensive overview of the quality of the ligand structures in the entire PDB. ValidatorDB contains precomputed validation results for ligands and residues in the Protein Data Bank. The database is updated on a weekly basis.

The residues deemed relevant for validation are all ligands and residues with reasonable size (more than six heavy atoms), with the exception of standard amino acids and nucleotides. The validation is performed using MotiveValidator, and the residue models from wwPDB Chemical Component Dictionary (wwPDB CCD) are used as reference structures for validation.

==Availability and technical details==

===Where to find ValidatorDB===
ValidatorDB is freely available online since May 2014 at http://ncbr.muni.cz/MotiveValidatorDB. There is no login requirement for accessing ValidatorDB.

===What you need in order to access ValidatorDB===
ValidatorDB is basically a database, or rather a collection of validation results for ligands and residues in Protein Data Bank. The database is maintained at the National Centre for Biomolecular Research within Masaryk University, Czech Republic, and updated weekly. All you need in order to access ValidatorDB is an internet browser and has JavaScript enabled. The only functionality that relies on your system is the display of 3D models, for which your browser will need to support WebGL. If you experience trouble displaying the 3D models, please check http://get.webgl.org in order to find out how to enable WebGL on your system.

===How to get around the web page===

As soon as you type in the address http://ncbr.muni.cz/ValidatorDB, you will reach the ValidatorDB synopsis page, which contains a brief, general description of ValidatorDB, along with 3 tabs. The different tabs on the ValidatorDB synopsis page provide access to overviews and statistical evaluation of validation results for the entire PDB, for each residue across all PDB IDs containing that residue, and for all analyzed residues in each PDB ID, in graphical or tabular form. Click on each tab to discover what type of overview can be accessed. Further, the ValidatorDB specifics page, which is accessible by looking up specific residues or PDB IDs in the synopsis page, allows to view the results for selected residues in more detail. The specifics page is also organized into tabs that allow different levels of analysis of the results. Last but not least, remember to check the tool tips by hovering the mouse cursor over any graphical or textual element in the ValidatorDB interface.

Before moving on to more extensive descriptions of features, it is important to clearly establish the meaning of a few key terms and principles within the ValidatorDB environment. See [[MotiveValidator:Terminology|Terminology]].

==Basic Principles==

===Residues and ligands relevant for validation===

As mentioned in section 1, well studied residues like amino acids and nucleotides are routinely validated upon submission of new structures to the PDB. Furthermore, reports of the quality of their structure are already accessible. The challenge addressed by
ValidatorDB lies in providing access to validation results for residues other than the well studied amino acids and nucleotides. This generally includes ligands and uncommon residues (e.g. substituted amino acids), which exhibit high diversity and nontriviality in their structure, and for which there is generally much less information regarding correct structures. Thus, within the ValidatorDB environment, we further refine the meaning of the terms residue and ligand to refer to residues and ligands relevant for validation. Specifically, these are all ligands and residues with reasonable size (more than six heavy atoms), with the exception of amino acids and nucleotides. All other features of the terms residue and ligand described in sections 2.1 and 2.2 are maintained. Henceforth, all references to residues and ligands in the ValidatorDB web pages (including Wiki and tutorial) have the meaning of residues and ligands relevant for validation. The PDB currently holds over 170,00 residues and ligands relevant for validation.

===Validation===
[[File:VDB_manual_figures2.png|thumb|right|Validation process: figure 1]]
As stated in section, the validation results stored in ValidatorDB are updated every week. Within the ValidatorDB environment, the term validation refers to the process of determining whether a residue or ligand is structurally complete and correctly annotated. This means checking if the topology and chirality of each motif of a validated residue (section 2.4) correspond to those of the model residue (section 2.5) with the same name as the validated residue.
The validation of residues and ligands in the entire PDB takes place in a few distinct steps. First, for each PDB entry, the residues which are relevant for validation are detected based on their name (3-letter code) and number of atoms (more than 6 heavy atoms). Amino acid residues and nucleotides are excluded based on their residue name. Then, for each validated residue, the corresponding model (same 3-letter code as the validated residue) is retrieved from wwPDB CCD, and each motif of this residue is validated against the model.

ValidatorDB is then built as the collection of validation results for all motifs of all residues in all PDB entries(Figure 1A).
The validation of each motif against the model residue can be illustrated on a galactose (GAL)motif from the PDB entry 1bzw
(Figure 1B). The validated residue GAL is extracted form PDB entry 1bzw in the form of an input motif , which contains all the atoms of the validated residue, together with all atoms found within one or two bonds of any atom from the validated residue
(surroundings). Then, by superimposing the input motif and model residue, the validated motif is obtained as the subset of atoms in the input motif which have a correspondent atom in the model residue. Comparing each atom and bond in the validated motif to those in the model residue produces the validation results.

==Validation results==
For each validated motif, ValidatorDB contains several types of results. Since the evaluation of the validated motif relies on comparing all atoms and bonds in the validated motif to those in the model residue, the first results that can be encountered are errors. Namely:

*Missing atoms: an atom in the model residue has no corresponding atom in the validated motif.

*Missing rings: at least one missing atom originates from cycles (rings).

*Wrong chirality: an atom from the validated motif has different chirality than the corresponding atom from the model residue.

*Wrong chirality (planar): the chirality error was found on a planar chiral center. Because of their spacial distribution, planar chiral centers are very sensitive even to small perturbations in the position of the substituents. Therefore, some of the errors reported here might not be significant.

*Uncertain chirality: the presence of unusual bonds may cause an improper evaluation of chirality.

Chirality is only evaluated for those motifs which are complete. This is because the absence of some atoms can prevent the proper evaluation of chirality on the chiral centers present in the validated motif. Therefore, note that all motifs which are counted in the Wrong chirality category are in fact complete. At the same time, the motifs with no missing atoms and no chirality error are actually counted in a category called Correct chirality.

--------------------------
Suspicious discrepancies between the atoms and inter-atomic bonds in the validated motif and in the model residue are reported as warnings. Namely:

*Substitution: an atom from the validated motif is of a different chemical element than the corresponding atom in the model residue (e.g. O mapped to N). This happens often at linkage sites.

*Different naming: an atom from the validated motif has a different PDB atom name than the corresponding atom from the model residue (e.g. the C1 atom mapped to the C7 atom). This happens often when the original PDB files were produced by different software.

*Foreign atom: an atom from the model residue was mapped to an atom from outside the validated residue (i.e. from its surroundings).

*Alternate locations: in the original PDB file, the validated residue contains atoms which were given in alternate locations (i.e., most probably different rotamers). Only the first rotamer was considered during validation.

*Zero model RMSD: the superimposition between the model residue and the validated motif has a root mean square deviation of zero, i.e., the validated motif is identical to the model residue used as reference.

Disabling discrepancies between the atoms and inter-atomic bonds in the validated motif and in the model residue are reported as
processing errors, and such motifs are not validated.

Typical validation results that can be found in ValidatorDB are illustrated on the galactose motif mentioned in section 2.6(Fig 1C). As a general rule, in the ValidatorDB interface, errors are marked in red (missing atoms) or dark yellow (wrong chirality), correct structures in green, and warnings in cyan.

==Database contents==
ValidatorDB contains precomputed validation results for ligands and residues in the Protein Data Bank. The database is updated on a weekly basis. The validation is performed using Validator, and the residue models from wwPDB CCD are used as reference templates for validation. All residues of significant size (a minimum of 6 heavy atoms) have been included in ValidatorDB, with the exception of amino acids and nucleotides, which are checked thoroughly upon submission of the structure to the PDB, and thus do not require additional validation.

The validation results available in ValidatorDB inform whether each motif (occurrence, instance) of a ligand or residue in the PDB exhibits the appropriate topology and stereochemistry expected from its annotation (3-letter code), or how it differs from this annotation. Additionally, all issues related to incorrect or suspicious topology and stereochemistry are explicitly described in a comprehensive and intuitive manner (e.g., location of missing atoms or chirality inversions).

ValidatorDB is organized on two main levels, namely PDB-wide results (synopsis page), and results restricted to specific residues of interest (specifics page). The two levels present the same type of validation results (as described in section 2.7), although the available features differ to some extent (e.g., the specifics page allows 3D visualization of motifs). We shall describe each level of the database in detail below.

==Synopsis page==

The ValidatorDB synopsis page(Figures1A, 3) contains a brief description of ValidatorDB, along with information about the last database update (date and number of structures that have been processed during the validation). Specifically, in May 2014, over 100,000 PDB entries had been processed, containing over 230,000 motifs of 17,000 residues relevant for validation.
Additionally, the synopsis page allows to access the validation results for specific residues of interest via the LookUp bar
(Figure 1A). Simply type a comma separated list of residue names (3-letter codes) into the LookUp bar, and you will be redirected to the specifics page containing validation results for the residues you requested. If you specify a list of PDB IDs (4-letter codes)instead, then the corresponding specifics page will contain validation results for all relevant residues and ligands in the PDB entries you specified. See section 3.2 for a description of the contents of the specifics page, and how to interpret these contents. The ValidatorDB synopsis page further provides access to various data sets of PDB-wide validations via 3 different tabs, namely Overview, Details by Residue, and Details by PDB entry. A full description of each of these tab is given below (sections 2.1.1-2.1.3).

====Overview====
The Overview tab of the synopsis page provides a very general statistical evaluation of results across the entire PDB in graphical form (Figures 1A,3A). The elements of the graph represent percentages of the total number of motifs (over 200,000) of residues relevant for validation. A graphic element will be displayed in the Overview graph only if it represents at least 0.5% of the total number of motifs. Each element of the graph is described in a tool tip, but note that here the term residue actually refers to occurrence of residue(motif).

The elements of the graph can be assigned to roughly 6 categories, depending on which kind of information they contain (e.g., incomplete residue, chirality issues, warnings, etc.). The categories are marked by different colors (Figure 3A). Most of the graph elements have been explained in section 3.7 of this manual. The additional elements are Analyzed, which refers to the total number of motifs that could be processed, Missing Atoms or Rings, which is the sum of Missing (Only) Atoms and Missing Rings, and Has All Atoms and Rings, which is the total number of complete residues.

====Details by Residue====

The Details by Residue tab (Figure 3B) contains an interactive table summarizing the results for each residue validated across the entire PDB. Each row corresponds to one residue, identified by its residue name (3-letter code). The information in the table is organized according to the validation results as presented in section 2.7 of this manual. The color coding for the table header and the font inside the table is the same as in the categories defined in the Overview tab. Each element of the table header is described in a tool tip, but note that here the term residue actually refers to occurrence of residue (motif).

The table is interactive. Clicking on any element in the table header allows to sort the table entries according to that element. Click on any residue name in order to access the ValidatorDB specifics page with detailed validation results for that residue (see section 3.2).

The filter at the top right corner allows to retrieve the table row with a specific residue. Simply type the residue name into the filter. All results can be downloaded in .csv format using the download button at the top left corner.

====Details by PDB entry====

The Details by PDB Entry tab (Figure 3C) contains an interactive table summarizing the results for all residues validated in each PDB entry. Each row corresponds to one PDB entry, identified by its PDB ID (4-letter code). The information in the table is organized according to the validation results as presented in section 2.7 of this manual. The color coding for the table header and the font inside the table is the same as in the categories defined in the Overview tab. Each element of the table header is described in a tool tip, but note that here the term residue actually refers to occurrence of residue (motif).

The table is interactive. Clicking on any element in the table header allows to sort the table entries according to that element. Click on any PDB in order to access the ValidatorDB specifics page with detailed validation results for all residues in that PDB entry (see section 3.2).

The filter at the top right corner allows to retrieve the table rows with a specific residue, or the table rows with selected PDB IDs. Simply type the residue name or PDB ID into the filter. All results can be downloaded in .csv format using the download button at the top left corner.

==Specifics page==

The ValidatorDB specifics page is accessible from the synopsis page, either via the LookUp bar on the Overview tab (Figure 1A), or via the residue names and PDB IDs in the interactive tables on the tabs Details by Residue(Figure 3B) and Details by PDB Entry (Figure 3C), respectively. Depending on how it was accessed, the specifics page might retrieve validation results for one or more residues, a fact mentioned at the very top of the page(Figure 1B).

The ValidatorDB specifics page (Figures 1B,4,5)provides a straightforward report of the validation results, including a summary and detailed information in both tabular and graphical form, along with a 3D structure visualizer for closer inspection of the problematic structures. These reports are accessible via several tabs on the specifics page, namely Summary, Details, Processing Errors/Warnings, and Overview. These tabs will be described in detail in sections 3.2.1 - 3.2.4.Inspecting the tabular and graphical validation reports accessible on the specifics page is the most comfortable and effective way to evaluate the results. Additionally, you may use the JSON Data download button at the top right corner of the specifics page in order to download the complete validation reports and perform any additional analyses on your own.

====Summary====

On the ValidatorDB specifics page, the first view of the results is available in the Summary tab (Figures 1 B,4A). For each validated residue, the Summary tab provides an overview of potential issues encountered, as described in section 2.7.

If more than one residue were validated in one run, a list of these residues will be at the top of the page. In order to examine the validation summary for each residue, you will need to either click on that specific residue in the list, or just scroll down the page till you reach it. Each validated residue is identified by its 3-letter code, as well as its chemical formula and common name. Validation statistics are given as absolute numbers and percentages over all the motifs that were processed for each residue.

The table with the validation report is organized into two main sections, referring to incomplete(Missing Atoms or Rings) and complete structures (With All Atoms and Rings) respectively. The formal distinction between ring atoms and non-ring atoms (simply denoted as atoms ) is meant to allow a quick localization of potential issues in residues containing rings, especially where atom identifiers are not useful. Chirality is evaluated only for the complete structures, since the absence of some atoms makes it difficult to check the chirality of some of the remaining atoms. Further, the problematic atoms are highlighted, in order to better localize the problems in the structures.

Last, a 2D representation of the model residue, and a pie chart with the validation results are provided for visual representation purposes. You can download them via the small icon at the top right corner of the chart, and later use them in your presentations.

====Details====

Whereas the Summary tab provides statistics of the issues over all validated motifs for each validated residue, the Details tab of the ValidatorDB specifics page allows you to inspect the issues in select groups of motifs, and further in each individual motif(Figure 5A). Note that you may also access the details of any particular group of motifs also by clicking on a specific issue in any Summary tab table.

The Details tab is organized into a table where each row contains information regarding a single validated motif. The content of the table (i.e., which motifs are included, and what information is displayed) is dictated by the values of three selection fields at the top of the table. Click on the first field, and select the validated residue by its name (3-letter code) from the drop down menu. Only the motifs that were matched to that residue name will be displayed in the table. Click on the second field and select the type of issue (e.g., wrong chirality) from the drop down menu. Only the motifs which exhibit that type of issue will be displayed in the table. The number of motifs that fit each selection is given in brackets. If you want to make your selection even more specific, use the selection filed Id filter.

Which table columns are filled depend mostly on the type of issue selected in the filter. The most important columns are Id, Issues/Warnings, Missing atoms/rings, Atoms, Processing warnings. The other columns give additional information, usually helpful in identifying the source of the error in the structure. The column Id refers to a unique identifier assigned to each motif in order to keep a transparent trace of the motif's origin, as it contains the PDB ID, as well as the serial index of the first atom in the motif, as it appears in the original PDB entry. The column Issues/Warnings reports the number of issues or warnings found for each particular motif. The column Missing atoms/rings explains which atoms are missing in each validated motif, whereas Atoms shows the position of incorrect chirality. Missing atoms are listed by their atom identifier in the model, whereas atoms with wrong chirality are listed by their identifier in the validated motif. Clicking on a column header allows to sort the motifs according to the property specified in the header.

====3D visualization====
The 3D viewer implemented in the ValidatorDB interface offers one step further in the analysis of each individual validated motif, and is accessible via the Details tab on the specifics page(Figure 5B). In the table, simply click on the Id of a motif of interest in order to open the 3D viewer, where you can inspect the structural inaccuracies more closely. Here you will be able to view and manipulate with the 3D representations of the validated motif and model residue, to help you better assess the position and relevance of the structural issues found during validation. Additionally, a 2D representation of the model is provided for clarity, which is especially helpful for larger motifs. Basic information about the validated motif is also given, along with a complete report of the validation results, where all the potential issues are listed.

====Processing warnings and processing errors====

The validation reports in ValidatorDB also mention various unusual aspects encountered during validation. Sometimes the processed PDB entries contain information that is ambiguous, conflicting or which deviates strongly from the expected reference. ValidatorDB reports such events as processing warnings or processing errors, depending on the severity of the deviations. Such information can be found in the Processing Errors/Warnings tab on the specifics page. The selection field at the top of the page helps filter the warnings and errors. Simply click on the drop down menu and select the category of warnings or errors that you would like to explore. Processing warnings are issues that may cause incorrect Validation, such as atoms that are too close in the 3D space, or unusual bond lengths given by the CONECT records. ValidatorDB typically reports several kinds of warnings: substitutions, foreign atoms, different naming, alternate locations and zero model RMSD, planar chiral center, unusual bond lengths, etc. It is always good to check and make sure that negative validation results (e.g., missing atoms) are not in fact caused by ignoring some atoms in an ill-formed structure.

Processing errors are major issues preventing the finalization of the validation, such as parts of the residue which are completely disconnected from the rest of the structure, probably due to missing atoms at multiple locations throughout the structure. Any major errors in the input file, such as atoms that are completely disconnected from the rest of the structure, are reported as processing errors, and these structures are not processed at all.

It is important to note the difference between processing warnings and processing errors. A warning may simply lead to ignoring a faulty atom, but the motif is validated. On the other hand, a processing error prevents entire motifs from being validated, so you will not find these motifs in the statistics available on either the synopsis or specifics page. The number of motifs with processing errors can be easily calculated as the difference between total motifs of relevant residues in the PDB, and the number of analyzed motifs (currently around 2000 motifs, about 0.5% of relevant motifs in the PDB). Further, because ValidatorDB
automatically extracts all motifs of a relevant residue and assigns them a unique and informative motif Id, you will be able to easily find the motif in its original PDB entry, and explore it.

====Overview====

To keep consistency with the synopsis page, the specifics page also allows visualization of general validation statistics for a selected number of residues via the Overview tab. This representation is entirely compatible with that of the Overview tab on the synopsis page(Figure 5A), and in fact makes up a subset of that data set. All color coding conventions are kept, and tool tips provide descriptions of each graphical element.

==References==
<references/>

ValidatorDB

2014-06-26T00:01:12Z

Dave: /* How to get around the web page */

The advancement of research in structural biology has provided a large body of structural data deposited in various databases. One great example is the Protein Data Bank (PDB), which has been growing exponentially, and which currently consists of more than 100,000 structures of biomolecules and their complexes. Such large bodies of data, especially accumulated over a short period of time using high throughput techniques, will inherently be plagued by various problems.

Validation arose as a major issue in the structural biology community when it became apparent that some published structures contained serious errors, and only sometimes it is properly explained(e.g., due to insufficient electron density in a certain area). Structural databases generally require that the new submissions be checked prior to acceptance. The tools employed for presubmission validations work fairly well for residues like amino acids or nucleotides. However, an essential step in the validation process is checking the ligand structure, because ligands play a key role in protein function, and also because they are the main source of errors in structures. Ligand validation, as well as the validation of uncommon residues, are very challenging tasks, because of the high diversity and nontriviality of their structure, and the general lack of information about correct structures. Therefore, software tools focused on ligand validation were developed relatively recently,<ref>Lütteke T, von der Lieth C-W. {BMC Bioinformatics} (2004) 5, 69.</ref><ref>Kleywegt GJ, Harris MR. Acta Crystallographica D. Biological Crystallography (2007) 63: 935–8.</ref>, and the topic is still under active development<ref>ftp://ftp.ebi.ac.uk/pub/databases/pdb/validation_reports/</ref>. These tools are able to validate one or more structures (even thousands of structures), but they are not able to provide the broad scientific community with a more complex image of the quality of structures in dedicated and well established structural databases. For example, a general overview and corresponding statistical evaluation of validation results for residues and ligands in the entire PDB is not yet available, despite the exponential growth of the PDB and the development of structural validation tools in recent years.

We had recently developed MotiveValidator<ref>Svobodová Vařeková R, Jaiswal D, Sehnal D, Ionescu CM, Geidl S, Pravda L, Horský V, Wimmerová M, Koca J, Nucleic Acids Research (2014) doi:10.1093/nar/gku426</ref>, an interactive platform for the speedy validation of ligands, residues and fragments using a novel, straightforward approach based on the validation of residue annotation. MotiveValidator employs advanced algorithms for the detection and comparison of structural motifs<ref>Sehnal D, Svobodová Vařeková R, Huber HJ, Geidl S, Ionescu CM, Wimmerová M, Koca J, Journal of Chemical Information and Modeling 52(2), (2012): 343-359</ref>, along with tools for chirality verification<ref>O'Boyle NM, Banck M, James CA, Morley C, Vandermeersch T, Hutchison GR, Journal of Chemoinformatics 3, (2011): 33</ref> and interactive visualization of 3D structures <ref>http://www.chemdoodle.com</ref>. Using MotiveValidator, we further created ValidatorDB, a comprehensive resource of validation results for residues and ligands in the Protein Data Bank. Along with validation results for individual residues and ligands, ValidatorDB also provides a summary and statistical evaluation of the validation results at various levels of detail within the PDB. Thus, ValidatorDB offers a comprehensive overview of the quality of the ligand structures in the entire PDB. ValidatorDB contains precomputed validation results for ligands and residues in the Protein Data Bank. The database is updated on a weekly basis.

The residues deemed relevant for validation are all ligands and residues with reasonable size (more than six heavy atoms), with the exception of standard amino acids and nucleotides. The validation is performed using MotiveValidator, and the residue models from wwPDB Chemical Component Dictionary (wwPDB CCD) are used as reference structures for validation.

==Availability and technical details==

===Where to find ValidatorDB===
ValidatorDB is freely available online since May 2014 at http://ncbr.muni.cz/MotiveValidatorDB. There is no login requirement for accessing ValidatorDB.

===What you need in order to access ValidatorDB===
ValidatorDB is basically a database, or rather a collection of validation results for ligands and residues in Protein Data Bank. The database is maintained at the National Centre for Biomolecular Research within Masaryk University, Czech Republic, and updated weekly. All you need in order to access ValidatorDB is an internet browser and has JavaScript enabled. The only functionality that relies on your system is the display of 3D models, for which your browser will need to support WebGL. If you experience trouble displaying the 3D models, please check http://get.webgl.org in order to find out how to enable WebGL on your system.

===How to get around the web page===

As soon as you type in the address http://ncbr.muni.cz/ValidatorDB, you will reach the ValidatorDB synopsis page, which contains a brief, general description of ValidatorDB, along with 3 tabs. The different tabs on the ValidatorDB synopsis page provide access to overviews and statistical evaluation of validation results for the entire PDB, for each residue across all PDB IDs containing that residue, and for all analyzed residues in each PDB ID, in graphical or tabular form. Click on each tab to discover what type of overview can be accessed. Further, the ValidatorDB specifics page, which is accessible by looking up specific residues or PDB IDs in the synopsis page, allows to view the results for selected residues in more detail. The specifics page is also organized into tabs that allow different levels of analysis of the results. Last but not least, remember to check the tool tips by hovering the mouse cursor over any graphical or textual element in the ValidatorDB interface.

Before moving on to more extensive descriptions of features, it is important to clearly establish the meaning of a few key terms and principles within the ValidatorDB environment. See [[MotiveValidator:Terminology|Terminology]]

==Basic Principles==

===Residues and ligands relevant for validation===

As mentioned in section 1, well studied residues like amino acids and nucleotides are routinely validated upon submission of new structures to the PDB. Furthermore, reports of the quality of their structure are already accessible. The challenge addressed by
ValidatorDB lies in providing access to validation results for residues other than the well studied amino acids and nucleotides. This generally includes ligands and uncommon residues (e.g. substituted amino acids), which exhibit high diversity and nontriviality in their structure, and for which there is generally much less information regarding correct structures. Thus, within the ValidatorDB environment, we further refine the meaning of the terms residue and ligand to refer to residues and ligands relevant for validation. Specifically, these are all ligands and residues with reasonable size (more than six heavy atoms), with the exception of amino acids and nucleotides. All other features of the terms residue and ligand described in sections 2.1 and 2.2 are maintained. Henceforth, all references to residues and ligands in the ValidatorDB web pages (including Wiki and tutorial) have the meaning of residues and ligands relevant for validation. The PDB currently holds over 170,00 residues and ligands relevant for validation.

===Validation===
[[File:VDB_manual_figures2.png|thumb|right|Validation process: figure 1]]
As stated in section, the validation results stored in ValidatorDB are updated every week. Within the ValidatorDB environment, the term validation refers to the process of determining whether a residue or ligand is structurally complete and correctly annotated. This means checking if the topology and chirality of each motif of a validated residue (section 2.4) correspond to those of the model residue (section 2.5) with the same name as the validated residue.
The validation of residues and ligands in the entire PDB takes place in a few distinct steps. First, for each PDB entry, the residues which are relevant for validation are detected based on their name (3-letter code) and number of atoms (more than 6 heavy atoms). Amino acid residues and nucleotides are excluded based on their residue name. Then, for each validated residue, the corresponding model (same 3-letter code as the validated residue) is retrieved from wwPDB CCD, and each motif of this residue is validated against the model.

ValidatorDB is then built as the collection of validation results for all motifs of all residues in all PDB entries(Figure 1A).
The validation of each motif against the model residue can be illustrated on a galactose (GAL)motif from the PDB entry 1bzw
(Figure 1B). The validated residue GAL is extracted form PDB entry 1bzw in the form of an input motif , which contains all the atoms of the validated residue, together with all atoms found within one or two bonds of any atom from the validated residue
(surroundings). Then, by superimposing the input motif and model residue, the validated motif is obtained as the subset of atoms in the input motif which have a correspondent atom in the model residue. Comparing each atom and bond in the validated motif to those in the model residue produces the validation results.

==Validation results==
For each validated motif, ValidatorDB contains several types of results. Since the evaluation of the validated motif relies on comparing all atoms and bonds in the validated motif to those in the model residue, the first results that can be encountered are errors. Namely:

*Missing atoms: an atom in the model residue has no corresponding atom in the validated motif.

*Missing rings: at least one missing atom originates from cycles (rings).

*Wrong chirality: an atom from the validated motif has different chirality than the corresponding atom from the model residue.

*Wrong chirality (planar): the chirality error was found on a planar chiral center. Because of their spacial distribution, planar chiral centers are very sensitive even to small perturbations in the position of the substituents. Therefore, some of the errors reported here might not be significant.

*Uncertain chirality: the presence of unusual bonds may cause an improper evaluation of chirality.

Chirality is only evaluated for those motifs which are complete. This is because the absence of some atoms can prevent the proper evaluation of chirality on the chiral centers present in the validated motif. Therefore, note that all motifs which are counted in the Wrong chirality category are in fact complete. At the same time, the motifs with no missing atoms and no chirality error are actually counted in a category called Correct chirality.

--------------------------
Suspicious discrepancies between the atoms and inter-atomic bonds in the validated motif and in the model residue are reported as warnings. Namely:

*Substitution: an atom from the validated motif is of a different chemical element than the corresponding atom in the model residue (e.g. O mapped to N). This happens often at linkage sites.

*Different naming: an atom from the validated motif has a different PDB atom name than the corresponding atom from the model residue (e.g. the C1 atom mapped to the C7 atom). This happens often when the original PDB files were produced by different software.

*Foreign atom: an atom from the model residue was mapped to an atom from outside the validated residue (i.e. from its surroundings).

*Alternate locations: in the original PDB file, the validated residue contains atoms which were given in alternate locations (i.e., most probably different rotamers). Only the first rotamer was considered during validation.

*Zero model RMSD: the superimposition between the model residue and the validated motif has a root mean square deviation of zero, i.e., the validated motif is identical to the model residue used as reference.

Disabling discrepancies between the atoms and inter-atomic bonds in the validated motif and in the model residue are reported as
processing errors, and such motifs are not validated.

Typical validation results that can be found in ValidatorDB are illustrated on the galactose motif mentioned in section 2.6(Fig 1C). As a general rule, in the ValidatorDB interface, errors are marked in red (missing atoms) or dark yellow (wrong chirality), correct structures in green, and warnings in cyan.

==Database contents==
ValidatorDB contains precomputed validation results for ligands and residues in the Protein Data Bank. The database is updated on a weekly basis. The validation is performed using Validator, and the residue models from wwPDB CCD are used as reference templates for validation. All residues of significant size (a minimum of 6 heavy atoms) have been included in ValidatorDB, with the exception of amino acids and nucleotides, which are checked thoroughly upon submission of the structure to the PDB, and thus do not require additional validation.

The validation results available in ValidatorDB inform whether each motif (occurrence, instance) of a ligand or residue in the PDB exhibits the appropriate topology and stereochemistry expected from its annotation (3-letter code), or how it differs from this annotation. Additionally, all issues related to incorrect or suspicious topology and stereochemistry are explicitly described in a comprehensive and intuitive manner (e.g., location of missing atoms or chirality inversions).

ValidatorDB is organized on two main levels, namely PDB-wide results (synopsis page), and results restricted to specific residues of interest (specifics page). The two levels present the same type of validation results (as described in section 2.7), although the available features differ to some extent (e.g., the specifics page allows 3D visualization of motifs). We shall describe each level of the database in detail below.

==Synopsis page==

The ValidatorDB synopsis page(Figures1A, 3) contains a brief description of ValidatorDB, along with information about the last database update (date and number of structures that have been processed during the validation). Specifically, in May 2014, over 100,000 PDB entries had been processed, containing over 230,000 motifs of 17,000 residues relevant for validation.
Additionally, the synopsis page allows to access the validation results for specific residues of interest via the LookUp bar
(Figure 1A). Simply type a comma separated list of residue names (3-letter codes) into the LookUp bar, and you will be redirected to the specifics page containing validation results for the residues you requested. If you specify a list of PDB IDs (4-letter codes)instead, then the corresponding specifics page will contain validation results for all relevant residues and ligands in the PDB entries you specified. See section 3.2 for a description of the contents of the specifics page, and how to interpret these contents. The ValidatorDB synopsis page further provides access to various data sets of PDB-wide validations via 3 different tabs, namely Overview, Details by Residue, and Details by PDB entry. A full description of each of these tab is given below (sections 2.1.1-2.1.3).

====Overview====
The Overview tab of the synopsis page provides a very general statistical evaluation of results across the entire PDB in graphical form (Figures 1A,3A). The elements of the graph represent percentages of the total number of motifs (over 200,000) of residues relevant for validation. A graphic element will be displayed in the Overview graph only if it represents at least 0.5% of the total number of motifs. Each element of the graph is described in a tool tip, but note that here the term residue actually refers to occurrence of residue(motif).

The elements of the graph can be assigned to roughly 6 categories, depending on which kind of information they contain (e.g., incomplete residue, chirality issues, warnings, etc.). The categories are marked by different colors (Figure 3A). Most of the graph elements have been explained in section 3.7 of this manual. The additional elements are Analyzed, which refers to the total number of motifs that could be processed, Missing Atoms or Rings, which is the sum of Missing (Only) Atoms and Missing Rings, and Has All Atoms and Rings, which is the total number of complete residues.

====Details by Residue====

The Details by Residue tab (Figure 3B) contains an interactive table summarizing the results for each residue validated across the entire PDB. Each row corresponds to one residue, identified by its residue name (3-letter code). The information in the table is organized according to the validation results as presented in section 2.7 of this manual. The color coding for the table header and the font inside the table is the same as in the categories defined in the Overview tab. Each element of the table header is described in a tool tip, but note that here the term residue actually refers to occurrence of residue (motif).

The table is interactive. Clicking on any element in the table header allows to sort the table entries according to that element. Click on any residue name in order to access the ValidatorDB specifics page with detailed validation results for that residue (see section 3.2).

The filter at the top right corner allows to retrieve the table row with a specific residue. Simply type the residue name into the filter. All results can be downloaded in .csv format using the download button at the top left corner.

====Details by PDB entry====

The Details by PDB Entry tab (Figure 3C) contains an interactive table summarizing the results for all residues validated in each PDB entry. Each row corresponds to one PDB entry, identified by its PDB ID (4-letter code). The information in the table is organized according to the validation results as presented in section 2.7 of this manual. The color coding for the table header and the font inside the table is the same as in the categories defined in the Overview tab. Each element of the table header is described in a tool tip, but note that here the term residue actually refers to occurrence of residue (motif).

The table is interactive. Clicking on any element in the table header allows to sort the table entries according to that element. Click on any PDB in order to access the ValidatorDB specifics page with detailed validation results for all residues in that PDB entry (see section 3.2).

The filter at the top right corner allows to retrieve the table rows with a specific residue, or the table rows with selected PDB IDs. Simply type the residue name or PDB ID into the filter. All results can be downloaded in .csv format using the download button at the top left corner.

==Specifics page==

The ValidatorDB specifics page is accessible from the synopsis page, either via the LookUp bar on the Overview tab (Figure 1A), or via the residue names and PDB IDs in the interactive tables on the tabs Details by Residue(Figure 3B) and Details by PDB Entry (Figure 3C), respectively. Depending on how it was accessed, the specifics page might retrieve validation results for one or more residues, a fact mentioned at the very top of the page(Figure 1B).

The ValidatorDB specifics page (Figures 1B,4,5)provides a straightforward report of the validation results, including a summary and detailed information in both tabular and graphical form, along with a 3D structure visualizer for closer inspection of the problematic structures. These reports are accessible via several tabs on the specifics page, namely Summary, Details, Processing Errors/Warnings, and Overview. These tabs will be described in detail in sections 3.2.1 - 3.2.4.Inspecting the tabular and graphical validation reports accessible on the specifics page is the most comfortable and effective way to evaluate the results. Additionally, you may use the JSON Data download button at the top right corner of the specifics page in order to download the complete validation reports and perform any additional analyses on your own.

====Summary====

On the ValidatorDB specifics page, the first view of the results is available in the Summary tab (Figures 1 B,4A). For each validated residue, the Summary tab provides an overview of potential issues encountered, as described in section 2.7.

If more than one residue were validated in one run, a list of these residues will be at the top of the page. In order to examine the validation summary for each residue, you will need to either click on that specific residue in the list, or just scroll down the page till you reach it. Each validated residue is identified by its 3-letter code, as well as its chemical formula and common name. Validation statistics are given as absolute numbers and percentages over all the motifs that were processed for each residue.

The table with the validation report is organized into two main sections, referring to incomplete(Missing Atoms or Rings) and complete structures (With All Atoms and Rings) respectively. The formal distinction between ring atoms and non-ring atoms (simply denoted as atoms ) is meant to allow a quick localization of potential issues in residues containing rings, especially where atom identifiers are not useful. Chirality is evaluated only for the complete structures, since the absence of some atoms makes it difficult to check the chirality of some of the remaining atoms. Further, the problematic atoms are highlighted, in order to better localize the problems in the structures.

Last, a 2D representation of the model residue, and a pie chart with the validation results are provided for visual representation purposes. You can download them via the small icon at the top right corner of the chart, and later use them in your presentations.

====Details====

Whereas the Summary tab provides statistics of the issues over all validated motifs for each validated residue, the Details tab of the ValidatorDB specifics page allows you to inspect the issues in select groups of motifs, and further in each individual motif(Figure 5A). Note that you may also access the details of any particular group of motifs also by clicking on a specific issue in any Summary tab table.

The Details tab is organized into a table where each row contains information regarding a single validated motif. The content of the table (i.e., which motifs are included, and what information is displayed) is dictated by the values of three selection fields at the top of the table. Click on the first field, and select the validated residue by its name (3-letter code) from the drop down menu. Only the motifs that were matched to that residue name will be displayed in the table. Click on the second field and select the type of issue (e.g., wrong chirality) from the drop down menu. Only the motifs which exhibit that type of issue will be displayed in the table. The number of motifs that fit each selection is given in brackets. If you want to make your selection even more specific, use the selection filed Id filter.

Which table columns are filled depend mostly on the type of issue selected in the filter. The most important columns are Id, Issues/Warnings, Missing atoms/rings, Atoms, Processing warnings. The other columns give additional information, usually helpful in identifying the source of the error in the structure. The column Id refers to a unique identifier assigned to each motif in order to keep a transparent trace of the motif's origin, as it contains the PDB ID, as well as the serial index of the first atom in the motif, as it appears in the original PDB entry. The column Issues/Warnings reports the number of issues or warnings found for each particular motif. The column Missing atoms/rings explains which atoms are missing in each validated motif, whereas Atoms shows the position of incorrect chirality. Missing atoms are listed by their atom identifier in the model, whereas atoms with wrong chirality are listed by their identifier in the validated motif. Clicking on a column header allows to sort the motifs according to the property specified in the header.

====3D visualization====
The 3D viewer implemented in the ValidatorDB interface offers one step further in the analysis of each individual validated motif, and is accessible via the Details tab on the specifics page(Figure 5B). In the table, simply click on the Id of a motif of interest in order to open the 3D viewer, where you can inspect the structural inaccuracies more closely. Here you will be able to view and manipulate with the 3D representations of the validated motif and model residue, to help you better assess the position and relevance of the structural issues found during validation. Additionally, a 2D representation of the model is provided for clarity, which is especially helpful for larger motifs. Basic information about the validated motif is also given, along with a complete report of the validation results, where all the potential issues are listed.

====Processing warnings and processing errors====

The validation reports in ValidatorDB also mention various unusual aspects encountered during validation. Sometimes the processed PDB entries contain information that is ambiguous, conflicting or which deviates strongly from the expected reference. ValidatorDB reports such events as processing warnings or processing errors, depending on the severity of the deviations. Such information can be found in the Processing Errors/Warnings tab on the specifics page. The selection field at the top of the page helps filter the warnings and errors. Simply click on the drop down menu and select the category of warnings or errors that you would like to explore. Processing warnings are issues that may cause incorrect Validation, such as atoms that are too close in the 3D space, or unusual bond lengths given by the CONECT records. ValidatorDB typically reports several kinds of warnings: substitutions, foreign atoms, different naming, alternate locations and zero model RMSD, planar chiral center, unusual bond lengths, etc. It is always good to check and make sure that negative validation results (e.g., missing atoms) are not in fact caused by ignoring some atoms in an ill-formed structure.

Processing errors are major issues preventing the finalization of the validation, such as parts of the residue which are completely disconnected from the rest of the structure, probably due to missing atoms at multiple locations throughout the structure. Any major errors in the input file, such as atoms that are completely disconnected from the rest of the structure, are reported as processing errors, and these structures are not processed at all.

It is important to note the difference between processing warnings and processing errors. A warning may simply lead to ignoring a faulty atom, but the motif is validated. On the other hand, a processing error prevents entire motifs from being validated, so you will not find these motifs in the statistics available on either the synopsis or specifics page. The number of motifs with processing errors can be easily calculated as the difference between total motifs of relevant residues in the PDB, and the number of analyzed motifs (currently around 2000 motifs, about 0.5% of relevant motifs in the PDB). Further, because ValidatorDB
automatically extracts all motifs of a relevant residue and assigns them a unique and informative motif Id, you will be able to easily find the motif in its original PDB entry, and explore it.

====Overview====

To keep consistency with the synopsis page, the specifics page also allows visualization of general validation statistics for a selected number of residues via the Overview tab. This representation is entirely compatible with that of the Overview tab on the synopsis page(Figure 5A), and in fact makes up a subset of that data set. All color coding conventions are kept, and tool tips provide descriptions of each graphical element.

==References==
<references/>

PatternQuery:Use Cases

2014-06-11T15:27:02Z

Dave: Dave moved page MotiveQuery: Use Cases to MotiveQuery:Use Cases without leaving a redirect

<div class="toclimit-4">

==Statement of purpose==
MotiveQuery (MQ) represents a cutting edge and powerful platform for complex, swift and accurate molecular motifs selection and analysis over a vast variety of structural data. In the following text you can find a numerous use cases which will help you to deep dive into the language and the web service itself. Moreover, following text can also serve as a brief language reference. The full language reference is accessible via our [[MotiveQuery_Language_Reference | wiki pages]]. '''This is not the exhaustive list of queries there are new features to come in the next version.'''

In order to tune up your queries or just to try an interactive work with the language, feel free to use [http://webchem.ncbr.muni.cz/Platform/App/MotiveExplorer MotiveExplorer (ME)] application, where you can upload a PDB molecule of choice and immediately see the result of queries. ME requires an up-to-date web browser and the [http://www.microsoft.com/silverlight/ Silverlight] framework installed. It has been tested under Windows and Mac OS operating systems.

==How to read following text==

The text is separated to three plus one part which differs by data type queries are operated (Atoms, Residues and Motives). 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 Motives, which contain numerous advanced queries demonstrating versatility and power of MQ. These queries operate on all results provided by both Atom and Residue queries. The additional part represents a few use cases of complex queries demonstrating possible application of MQ language.

Each query looks like this:
===Name of the query()===
*'''[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 <code>Residues("HEM")</code>. Copy this query to the command text box in Motive 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 Atoms() take 0..n strings in parenthesis ("C", "N", etc.) and based on the input returns a list of individual atoms.

==Terminology==
By an atom we mean an individual point in Cartesian coordinate system as provided by ATOM or HETATOM records in PDB input files. Residue refers to any component of a biomacromolecule or a biomacromolecular complex. This includes amino acid residues, nucleotides and ligand, which are commonly referred to as residues as they provide building blocks for proteins and nucleic acids. A single residue is defined by its id and name defined in PDB input file. Subsequently, a motive is any sequence of either atoms or residues generated by MQ. Therefore, both atoms and residues can be considered as motives.

=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.
*<code>Atoms("Fe")</code> - Returns all iron atoms in the given structure.
*<code>Atoms("Fe", "N")</code> - 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.
* <code>AtomNames("CA")</code> – Returns all CA atoms.
* <code>AtomNames("CA", "N")</code> –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
* <code>AtomIds(1)</code> – Returns atom with id=1 from the given structures.
* <code>AtomIds(1,2,5) </code>- 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).
* <code>AtomIdRange(1, 10)</code> – 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.
* <code>NotAtomNames("C", "N", "CA", "O")</code> – 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
* <code>NotAtomIds(1)</code> - Returns atom with id other but 1 from the given structures.
* <code>NotAtomIds(1,2,5)</code> - 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.
* <code>Atoms("Fe")</code> – returns all the atoms of the structure, but iron.
* <code>Atoms("Fe", "N")</code> 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 .
* <code>RingAtoms(Atoms("N"), Rings(2 * ["C"] + ["N"] + ["C"] + ["N"]))</code> – 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.
* <code>Residues("HEM")</code> – Returns a list of HEM residues.
* <code>Residues ("HEM", "ALA")</code> – 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.
* <code>NotResidues("HEM")</code> – 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”.
* <code>ResidueIds ("14 A", "15 A")</code> – 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.
* <code>ResidueIdRange("A", 50, 100)</code> – 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.
* <code>NotAminoAcids()</code> – Returns all the nonstandard residues incorporated in the protein structure with the exception of HOH and WAT residues, which stands for solvent.
* <code>NotAminoAcids(NoWaters=False)</code> – 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: <code>Positive, Negative, Aromatic, Polar, NonPolar</code>
* <code>AminoAcids()</code> – Returns all standard amino acids.
* <code>AminoAcids(ChargeType=”Polar”)</code> – 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.
* <code>HetResidues()</code> – A set of hetatom residues.
* ''Type: HetResidues() -> Residues''

==Motives==
===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.
* <code>Rings(2 * ["C"] + ["N"] + ["C"] + ["N"])</code> – Returns the histidine aromatic ring.
* <code>Rings(4 * ["C"] + ["O"])</code> – 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.
* <code>Residues("HEM").ToAtoms()</code> – Returns all the atoms of HEM residues as a sequence of individual atoms.
* ''Type: ToAtoms(motives: Motives) -> Motives''

====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.
* <code>Residues("HEM").AmbientResidues(2).ToResidues()</code> – Returns the sequence of individual residues from the 2Å surrounding of the HEM residue, inclusive HEM.
* <code>Atoms("C").ToResidues()</code> – Returns a sequence of motifs. Each motif contains only carbon atoms grouped together according to their parent residue.
* ''Type: ToResidues(motives: Motives) -> Motives''

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

====RegularMotives()====
* 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.
* <code> RegularMotives("HH")</code> – Finds two consecutive histidine residues.
* <code> RegularMotives("G.{1,2}G")</code> – Finds two glycine residues separated by one or two other residues.
* <code> RegularMotives("G.{1,2}G").Filter(lambda m: m.IsConnected())</code> – Finds two glycine residues separated by one or two residues and verifies that all of them are bonded.
* ''Type: RegularMotives(regex: Value) -> Motives''

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

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

===Topology function===
====AmbientAtoms()====
* '''[1hho]''' Returns all the atoms, which are within n Å from the geometrical center of a given motif.
* <code>Atoms("Fe").AmbientAtoms(4)</code> – returns all the atoms, which are closer than 4Å from the center of mass of iron atom.
* ''Type: AmbientAtoms(motive: Motives, r: Number) -> Motives''

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

====Near()====
* '''[1hho]''' Clusters all the specified motives, which are pairwise closer in Ångströ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’.
* <code>Near(0, Rings(6*['C']), Rings(4*['C'] + ['N']))</code> – Returns motives containing only purine. In this example the purine part of tryptophan side chain will be returned.
* <code>Near(2 , Atoms("C"), Atoms("C"), Atoms("C"), Atoms("C"))</code> – Returns motives which contain exactly 4 carbon atoms within a sphere of 2Å.
* ''Type: Near(r: Number, motives: Motives+) -> Motives''

===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.
* <code>Residues().Filter(lambda m: m.IsConnectedTo(Atoms("Fe"))) </code>– returns a set of motives from all residues which are covalently bonded to the iron atom (excluded the HEM residue).
* <code> Residues().Filter(lambda m: m.Count(Atoms("O")) == 2)</code> returns all the residues containing exactly two oxygen atoms.
* ''Type: Filter(motives: Motives, filter: Motive->Bool) -> Motives''

====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.
* <code>Residues("HEM").ConnectedResidues(2).Filter(lambda m: m.Count(Atoms("S")) == 1)</code> – 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.
* <code>Residues("CYS").ConnectedResidues(1).Filter(lambda m: m.Count(Residues("VAL")) == 2)</code> – Returns a cysteine residue which is surrounded from both sides by valine residues.
* ''Type: Count(where: Motive, what: Motives) -> Integer''.

====Contains()====
* '''[4hhb]''' <code>Contains()</code> 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 <code>(Count() > 0)</code>
* <code>Residues("HEM").AmbientResidues(2).Filter(lambda m: m.Contains(Residues("HIS")))</code> – Returns motives, where any atom of HEM residue is at most 2Å distant from the histidine.
* <code>Residues().Filter(lambda m: m.Contains(Atoms("S")))</code> – Returns all the residue which has a sulphur incorporated in their structure. For this particular example it is similar to the query <code>Residues("CYS", "MET")</code>.
* ''Type: Contains(where: Motive, what: Motives) -> Bool''

===Connectivity===
====IsConnected()====
* '''[4m9e, 4m9v]''' Checks, whether a particular motif is composed of a single component
* <code>Atoms("Zn").AmbientAtoms(4).Filter(lambda m: m.IsConnected())</code> – Atoms which are at most 4 Å 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 <code>Atoms("Zn").AmbientAtoms(4)</code>
* ''Type: IsConnected(motive: Motive) -> Bool.''

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

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

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

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

==Selected Use Cases==
==== Find all post-translational modified aminoacids ====
*i.e. Those incodporated in the protein backbone and not hetero atoms
<pre>NotAminoAcids().Filter(lambda m: m.Count(HetResidues()) == 0) </pre>
This query queries all the non-standard amino acids for their presence among Hetatom entries. Equivalently:**<pre>NotAminoAcids().Filter(lambda m: m.Contains(HetResidues()).Not())</pre>

====Find all heteroatoms, which are not covalently bonded to the protein structure====
* Takes all the heteroatoms and queries them for being connected to any amino acid of a given protein
<pre>HetResidues().Filter(lambda m: m.IsNotConnectedTo(AminoAcids()))</pre>

====Identify Zinc fingers====
*There is a variety of different zinc fingers based on the surrounding residues, in our example we will focus on those comprising two zinc and two his residues (Cys2His2).

<pre>Atoms("Zn").ConnectedResidues(1).Filter(lambda m: (m.Count(Residues("His")) == 2) & (m.Count(Residues("Cys")) == 2)) </pre>

At first the zinc atoms are selected together with their bonded residues. Additionally, these motives are filtered according to the content of their amino acids.

====Identify all the residues, which contain a sugar ring====
* This task can be decomposed to two individual subtasks, since sugars contain either pentose or furanose ring. Pentose ring contains 4 carbon and an oxygen atom. Similarly, furanose ring is composed of 5 carbon atoms and an oxygen atom.

<pre>Or(Rings(4 * ["C"] + ["O"]) .ConnectedResidues(0), Rings(5 * ["C"] + ["O"]) .ConnectedResidues(0)) </pre>

By specifying the <code>Ring()</code> queries, we select only the ring part of the molecule. By extending the <code>Ring()</code> query with <code>ConnectedResidues(0)</code> only the residue which includes this ring is selected. Last but not least we can join both queries with <code>Or()</code> in order to merge results.

====Identify all binding sites of PA-IIL lectine in different organisms====
*Binding sites of this type of lectine comprise of two calcium atoms close to each other and a binded sugar residue.
<pre>Cluster(4, Atoms("Ca")).Filter(lambda m: m.Count(Atoms("Ca")) == 2).ConnectedResidues(1).Filter(lambda m: (m.Count(Rings(5 * ["C"] + ["O"])) > 0) | (m.Count(Rings(4 * ["C"] + ["O"])) > 0)) </pre>

At first we select all the calcium atoms and clusters them, if they are in a vicinity of 4Å and less. Additionally, we check if there are exactly 2 such atoms. Subsequently all the binded residues are found and finally, only the motives containing either pentose <code>(Rings(5 * ["C"] + ["O"]))</code> or furanose <code>(Rings(4 * ["C"] + ["O"]))</code> are returned.

Equivalently:

<pre>Cluster(4, Atoms("Ca")).Filter(lambda m: m.Count(Atoms("Ca")) == 2).ConnectedResidues(1).Filter(lambda m: m.Contains(Or((Rings(5 * ["C"] + ["O"])), Rings(4 * ["C"] + ["O"]))))</pre>