From a45e3f28821af8da946f2240ef93e5da8e16f941 Mon Sep 17 00:00:00 2001
From: Gerardo Tauriello <gerardo.tauriello@unibas.ch>
Date: Mon, 23 Apr 2018 15:23:17 +0200
Subject: [PATCH] Query doc updated and explain when quotation marks needed.
---
modules/mol/base/doc/query.rst | 64 +++++++++++++++++++++++-----------
1 file changed, 43 insertions(+), 21 deletions(-)
diff --git a/modules/mol/base/doc/query.rst b/modules/mol/base/doc/query.rst
index 54380f93f..6cf82e2c4 100644
--- a/modules/mol/base/doc/query.rst
+++ b/modules/mol/base/doc/query.rst
@@ -16,7 +16,7 @@ selections in a convenient way. Selections are carried out mainly by calling the
.. code-block:: python
- arginines=model.Select('rname=ARG')
+ arginines = model.Select('rname=ARG')
A simple selection query (called a predicate) consists of a property (here,
`rname`), a comparison operator (here, `=`) and an argument (here, `ARG`). The
@@ -24,7 +24,7 @@ return value of a call to the :meth:`EntityHandle.Select` method is always an
:class:`EntityView`. The :class:`EntityView` always contains a full hierarchy of
elements, never standalone separated elements. In the above example, the
:class:`EntityView` called `arginines` will contain all chains from the
-structure called 'model' that have at least one arginine. In turn these chains
+structure called `model` that have at least one arginine. In turn these chains
will contain all residues that have been identified as arginines. The residues
themselves will contain references to all of their atoms. Of course, queries are
not limited to selecting residues based on their type, it is also possible to
@@ -32,9 +32,9 @@ select atom by name:
.. code-block:: python
- c_betas=model.Select('aname=CB')
+ c_betas = model.Select('aname=CB')
-As before, c`betas is an instance of an :class:`EntityView` object and contains
+As before, `c_betas` is an instance of an :class:`EntityView` object and contains
a full hierarchy. The main difference to the previous example is that the
selected residues do not contain a list of all of their atoms but only the
C-beta. These examples clarify why the name 'view' was chosen for this result of
@@ -45,8 +45,17 @@ Both the selection statements that have been used so far take strings as their a
.. code-block:: python
- n_term=model.Select('rnum<=20')
-
+ n_term = model.Select('rnum<=20')
+
+If you want to supply arguments with special characters they need to be put in
+quotation marks. For instance, this is needed to select the chain named "_" or
+for any chain name conatining ".", " " or ",". Hence, chain "_" can be selected
+with:
+
+.. code-block:: python
+
+ model.Select('cname="_"')
+
Combining predicates
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -60,25 +69,25 @@ Compact forms are available for several selection statements. For example, to se
.. code-block:: python
- arg_and_asn=model.Select('rname=ARG or rname=ASN')
+ arg_and_asn = model.Select('rname=ARG or rname=ASN')
However, this is rather cumbersome as it requires the word `rname` to be typed twice. Since the only difference between the two parts of the selection is the argument that follows the word `rname`, the statement can also be written in an abbreviated form:
.. code-block:: python
- arg_and_asn=model.Select('rname=ARG,ASN')
+ arg_and_asn = model.Select('rname=ARG,ASN')
Another example: to select residues with numbers in the range 130 to 200, one could use the following statement
.. code-block:: python
- center=model.Select('rnum>=130 and rnum<=200')
+ center = model.Select('rnum>=130 and rnum<=200')
or alternatively use the much nicer syntax:
.. code-block:: python
- center=model.Select('rnum=130:200')
+ center = model.Select('rnum=130:200')
This last statement is completely equivalent to the previous one. This syntax
can be used when the selection statement requires a range of integer values
@@ -91,25 +100,38 @@ The query
.. code-block:: python
- around_center=model.Select('5 <> {0,0,0}')
+ around_center = model.Select('5 <> {0,0,0}')
-selects all chains, residues and atoms that lie with 5 Å to the origin of the reference system ({0,0,0}). The `<>` operator is called the ‘within’ operator.
-Instead of a point, the within statements can also be used to return a view containing all chains, residues and atoms within a radius of another selection statement applied to the same entity. Square brackets are used to delimit the inner query statement.
+selects all chains, residues and atoms that lie with 5 Å to the origin of the
+reference system ({0,0,0}). The `<>` operator is called the 'within' operator.
+Instead of a point, the within statements can also be used to return a view
+containing all chains, residues and atoms within a radius of another selection
+statement applied to the same entity. Square brackets are used to delimit the
+inner query statement.
.. code-block:: python
- around_hem=model.Select('5 <> [rname=HEM]')
+ around_hem = model.Select('5 <> [rname=HEM]')
model.Select('5 <> [rname=HEM and ele=C] and rname!=HEM')
Bonds and Queries
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When an :class:`EntityView` is generated by a selection, it includes by default only bonds for which both connected atoms satisfy the query statement. This can be changed by passing the parameters `EXCLUSIVE_BONDS` or `NO_BONDS` when calling the Select method. `EXCLUSIVE_BONDS` adds bonds to the :class:`EntityView` when at least one of the two atoms falls within the boundary of the selection. `NO_BONDS` suppresses the bond inclusion step completely.
+When an :class:`EntityView` is generated by a selection, it includes by default
+only bonds for which both connected atoms satisfy the query statement. This can
+be changed by passing the parameters `EXCLUSIVE_BONDS` or `NO_BONDS` when
+calling the Select method. `EXCLUSIVE_BONDS` adds bonds to the
+:class:`EntityView` when at least one of the two atoms falls within the boundary
+of the selection. `NO_BONDS` suppresses the bond inclusion step completely.
Whole Residue Queries
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-If the parameter `MATCH_RESIDUES` is passed when the Select method is called, the resulting :class:`EntityView` will include whole residues for which at least one atom satisfies the query. This means that if at least one atom in the residue falls within the boundaries of the selection, all atoms of the residue will be included in the View.
+If the parameter `MATCH_RESIDUES` is passed when the Select method is called,
+the resulting :class:`EntityView` will include whole residues for which at least
+one atom satisfies the query. This means that if at least one atom in the
+residue falls within the boundaries of the selection, all atoms of the residue
+will be included in the View.
More Query Usage
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -141,9 +163,9 @@ they are defined. Therefore, all generic properties start with a `g`, followed b
chain_handle.SetIntProp("testpropchain", 10)
# query statements
- sel_a=e.Select("gatestpropatom<=10.0")
- sel_r=e.Select("grtestpropres=1.0")
- sel_c=e.Select("gctestpropchain>5")
+ sel_a = e.Select("gatestpropatom<=10.0")
+ sel_r = e.Select("grtestpropres=1.0")
+ sel_c = e.Select("gctestpropchain>5")
Since generic properties do not need to be defined for all parts of an entity
(e.g. it could be specified for one single :class:`AtomHandle`), the query
@@ -154,11 +176,11 @@ statement which can be done using a ':' character:
# if one or more atoms have no generic properties
- sel=e.Select("gatestprop=5")
+ sel = e.Select("gatestprop=5")
# this will throw an error
# you can specify a default value:
- sel=e.Select("gatestprop:1.0=5")
+ sel = e.Select("gatestprop:1.0=5")
# this will run through smoothly and use 1.0 as
# the default value for all atoms that do not
# have the generic property 'testprop'
--
GitLab