*Thank you, Rolf, for working on the .select() business. After taking a
close look at it, I decided the select() function was getting too cryptic,
and I agree that there were some inconsistencies there. What is given below
is much simpler. This long email message summarizes the JmolSQL business,
starting with Jmol 11.3.16_2015.09.28. See http://chemapps.stolaf.edu/
<http://chemapps.stolaf.edu/>*
*jmol/zip/jmol-14.3.16_2015.09.28.zip JmolSQLJmolSQL is a Jmol math syntax
that is designed to query information related to molecular structure. The
idea is that associative arrays, with key/value pairs, and especially
arrays of associative arrays, are data, and those arrays themselves can be
thought of as a mini database. These sorts of data can be found in Jmol in
the a model's auxiliary info (variable _M), including validation data
returned from LOAD =xxxx/val (_M.validation), sequence domain data returned
from LOAD =xxxx/dom (_M.domains), and secondary structure information
returned from LOAD =xxxx/dssr (_M.dssr) or LOAD=xxxx/rna3d (_M.rna3d). In
addition, the getProperty() function returns a wide variety of data
relating to model attributes, including getProperty("atomInfo") and
getProperty("bondInfo") among several others. The original conception of
JmolSQL was in the context of the getProperty() function -- for
example:load $caffeineprint getProperty("atomInfo[SELECT atomno,coord WHERE
shape LIKE 'trigonal planar']") { "atomno" : 1 "coord" : {1.312
-1.0479 0.0025} } { "atomno" : 3 "coord" : {1.7906001
0.20809999 9.999999E-4} } ...More recent development widens this use to
any array data, and use of the .select() function rather than getProperty()
is recommended for general use. Thus, alternatively we can use:print
getProperty("atomInfo").*
*select("atomno,coord WHERE shape LIKE 'trigonal planar'
")object.SELECT("keys WHERE/WHEREIN phrase")There are three parts to
JmolSQL: object, keys, and an optional WHERE or WHEREIN phrase. The object
can be either an associative array [key1:value1, key2:value2, key3:value3]
or an array of associative arrays, usually all having the same set of
keys.Associative ArraysWhen the top-level object is an associative array,
.select() can be used to select out subsets of that array, either as a
single associative array or as an array of values.abc.select("...")The
simplest form of .select() returns a subset of abc. Wild cards can be
interspersed with additional keys, for example, "a*,b" or "*_id". In each
such case, the case-sensitive LIKE operation is used to match keys.abc = [
A:[b:1],B:[b:2],AA:[b:3, d:50] ]print abc.select("A").format("JSON"){ "A":
{ "b": 1 } }abc = [ A:[b:1],B:[b:2],AA:[b:3, d:50] ]print
abc.select("A*").format("JSON"*
*){ "A": { "b": 1 },"AA": { "b": 3,"d": 50 } }abc.select("(...)")Using
parentheses around the list of keys delivers a list of values of b for only
the the subset of xyz for which a=1:abc = [ A:[b:1],B:[b:2],AA:[b:3, d:50]
]print abc.select("(A,B)").format("*
*JSON")[ { "b": 2 },{ "b": 1 } ]Arrays of Associative ArraysIn addition to
operating on an associative array directly, JmolSQL can operate on an array
of associative arrays. Generally we assume here that the elements of that
array are associative arrays that all have the same set of keys. This is
the essence of a database. Whether or not the associative arrays have the
same keys is not important for Jmol. For example, the
getProperty("atomInfo") returns an array giving the information for each
atom that is loaded:*
*load $caffeine*
*x = getProperty("atomInfo")*
*print x.count*
*24print x[1]*
*{ "_ipt" : 0 "atomIndex" : 0 "atomno" : 1 "bondCount" : 3
"clickabilityFlags" : 48 "colix" : -32761 "color" : "[x3050f8]"
"coord" : {1.312 -1.0479 0.0025} "element" : "nitrogen" "elemno" :
7 "formalCharge" : 0 "info" : "N1 #1" "model" : "1"
"partialCharge" : 0.0 "radius" : 0.7416667 "shape" : "trigonal
planar" "spacefill" : 0.3565 "sym" : "N" "visibilityFlags" : 63
"visible" : true "x" : 1.312 "y" : -1.0479 "z" : 0.0025 }*
*These data can be "queried" using JmolSQL.*
*xyz.select("...")Creates the sublist of associative arrays having the
selected subset of keys:xyz = [ [a:1,b:11],[a:2,b:22],[a:3,b:*
*33] ]print xyz.select("b").format("JSON")[ { "b": 11 },{ "b": 22 },{ "b":
33 } ]print x.select("atomno,element") { "atomno" : 1 "element"
: "nitrogen" } { "atomno" : 2 "element" : "carbon" } {
"atomno" : 3 "element" : "carbon" } { "atomno" : 4
"element" : "oxygen" } ...xyz.select("(...)")Adding parentheses
creates a list of only the values for the specified keys:xyz = [
[a:1,b:11],[a:2,b:22],[a:3,b:*
*33] ]print xyz.select("(b)").format("*
*JSON")[ 11,22,33 ]xyz = [ [a:1,b:11],[a:2,b:22],[a:3,b:*
*33] ]print xyz.select("(a,b)").format("*
*JSON")[ 11,1,22,2,33,3 ]*
*load $caffeine*
*print getProperty("atomInfo").*
*select("(element)").pivot*
*{ "carbon" : 8 "hydrogen" : 10 "nitrogen" : 4 "oxygen" :
2 }The assumption when using (keys) is that you want to know all these
values, but you don't care what order they are in (because that will not be
predictable) and you don't care about their exact context. An example is a
list of bonds for which we just want to know all the atoms involved, but
the atoms are listed under "atom1" and "atom2" in each bond array.load
=1ehz/dssrselect on @{_M.dssr.hbonds.select("(*
*atom1_id,atom2_id)")}206 atoms selectedUsing WHEREWHERE is used to select
a subset of the elements of an array based on specifickey-value
relationships.xyz.select("... WHERE ...")Delivers all key/value pairs in
the subset of xyz element associative arrays for which the WHERE clause is
true for that element. xyz = [ [a:1,b:11],[a:2,b:22],[a:3,b:*
*33] ]print xyz.select("* where a<3 and b<20").format("JSON")[ { "b":
11,"a": 1 } ]load $caffeineprint getProperty("atomInfo").*
*select("atomno,element WHERE shape LIKE 'trigonal planar'
").format("JSON")[ { "element": "nitrogen","atomno": 1 },{ "element":
"carbon","atomno": 3 },{ "element": "nitrogen","atomno": 5 },{ "element":
"carbon","atomno": 7 },{ "element": "carbon","atomno": 9 },{ "element":
"nitrogen","atomno": 10 },{ "element": "carbon","atomno": 12 },{ "element":
"carbon","atomno": 13 } ]xyz.select("(...) where ...")Using parentheses
around the list of keys delivers a list of values for only the subset of
xyz for which the WHERE clause is true:xyz = [
[a:1,b:11],[a:2,b:22],[a:3,b:*
*33] ]print xyz.select("(b) where a>1").format("JSON")[ 22,33 ]load
$caffeine print getProperty("atomInfo").*
*select("(shape) WHERE shape").pivot{ "bent" : 1 "tetrahedral" : 3
"trigonal planar" : 8 }Note that "WHERE shape" here just excludes all
cases where shape is the empty string, since empty strings in Jmol evaluate
as FALSE. (In this case that involves hydrogen atoms.)For example, finding
all the hydrogen bonds created by DSSR for a given residue:load =1ehz/dssrx
= _M.dssr.hbonds.select("(*
*distance) where res_long like '*|A|C|72|*'");print x.format("JSON")print
format("%5.3f",x.average)[ 2.832,2.879,2.838 ] 2.850*
*Array "Drilling"*
*WHERE will "drill down" through arrays of arrays to find elements that are
associative arrays, returning a flat array of those objects:xyz = [
[[a:1,b:11], [a:0,b:0]],[[[a:2,b:22]]],[[a:*
*3,b:33,aa:44]] ]print xyz.select("a* where a>0").format("JSON")[ { "a": 1
},{ "a": 2 },{ "a": 3,"aa": 44 } ]xyz = [ [[a:1,b:11],
[a:0,b:0]],[[[a:2,b:22]]],[[a:*
*3,b:33,aa:44]] ]print xyz.select("(b) where a>0").format("JSON")[ 11,22,33
] WHERE vs. WHEREINStarting with Jmol 14.4, JmolSQL includes an additional
option, WHEREIN. This option allows selecting specific key/value pairs for
which the value is itself an associative array, and *that array* has a
specific set of key/value relationships. Thus, theclause is checked one
level deeper in the structure.For example, given the associative arrayabc =
[key_1:[type:"a", i:1],key_2:[type:"b", i:2],key_3:[type:"a", i:3]]we can
select out only those keys for which type='a':abc = [key_1:[type:"a",
i:1],key_2:[type:"b", i:2],key_3:[type:"a", i:3]]print abc.select("*
WHEREIN type='a'").format("JSON");{ "key_3": { "i": 3,"type": "a"
},"key_1": { "i": 1,"type": "a" } }All of the options that involve WHERE
also apply to WHEREIN. For example,multiple keys can be specified, and keys
can be surrounded by parentheses to return just the values instead of
key/value pairs:abc = [key_1:[type:"a", i:1],key_2:[type:"b",
i:2],key_3:[type:"a", i:3]]print abc.select("(key_1,key2) WHEREIN
type='a'").format("JSON");[ { "i": 1,"type": "a" } ]In addition, WHEREIN
can be applied to arrays as well as associative arrays. In this case, the
WHEREIN phrase applies to the elements of that array, whichare assumed to
be associative arrays. For example, we can get a list of justthe occupied
orbitals produced by Gaussian that are of a given symmetry:load
http://chemapps.stolaf.edu/jmol/jsmol/data/no2_nbo.log.gz
<http://chemapps.stolaf.edu/jmol/jsmol/data/no2_nbo.log.gz> 2 filter
"alpha"print _M.moData.select("mos wherein occupancy>0").select("(*
*symmetry)").pivot{ "(A1)--O" : 6 "(A2)--O" : 1 "(B1)--O" : 1
"(B2)--O" : 4 }Note that this use of WHEREIN with arrays in this way can
also be accomplished *
*more directly with WHERE:*
*load http://chemapps.stolaf.edu/jmol/jsmol/data/no2_nbo.log.gz
<http://chemapps.stolaf.edu/jmol/jsmol/data/no2_nbo.log.gz> 2 filter
"alpha"print _M.moData.mos.select("(*
*symmetry) where occupancy>0").pivot{ "(A1)--O" : 6 "(A2)--O" : 1
"(B1)--O" : 1 "(B2)--O" : 4 }load
http://chemapps.stolaf.edu/jmol/jsmol/data/no2_nbo.log.gz
<http://chemapps.stolaf.edu/jmol/jsmol/data/no2_nbo.log.gz> 2 filter
"alpha"x= _M.moData.select("mos wherein occupancy>0 and symmetry like
'(B2)*' ")print x.select("(index)").format("*
*JSON")[ 1,5,8,10
]-------------------------------------------------------------------------------------------------------------Jmol.___JmolVersion="14.3.16_*
*2015.09.28"load http://chemapps.stolaf.edu/jmol/jsmol/data/no2_nbo.log.gz
<http://chemapps.stolaf.edu/jmol/jsmol/data/no2_nbo.log.gz> 2 filter
"alpha"x= _M.moData.select("mos wherein occupancy>0 and symmetry like
'(B2)*' ")print x.select("(index)").format("*
*JSON")[ 1,5,8,10 ]*
*new feature: array.sort("key") -- sorts an array of associative arrays by
the specified associative array key. -- example: load sf6.smol x=
_M.moData.mos.select("energy,*
*index where energy<0") x.sort("energy").reverse print x {
"energy" : -0.67001194 "index" : 35 } {
"energy" : -0.67001194 "index" : 34 } {
"energy" : -0.67001194 "index" : 33 } {
"energy" : -0.70143324 "index" : 32 } ...
new feature: JmolSQL xxxx.select("<keys> WHEREIN <clause>") -- replaces
** idea -- assumes values of xxxx are themselves associative arrays --
indicates that the clause should be applied only to the values for the
selected keys -- returns an associative array that holds only those keys
for which the clause is true *for them* -- works also for array xxxx where
each element of xxxx is an associative array, in which case it returns
a subarray of xxxx involving the matching values. -- example: abc =
[ A:[b:1], B:[b:2], C:[b:3, d:50], AA:[b:4] ] print abc.select("A*
wherein b>2").format("JSON") { "AA": { "b": 4 } } Compare
this to the following, where we are are checking for validity of abc
itself: abc = [ A:[b:1], B:[b:2], C:[b:3, d:50], AA:[b:4] ] print
abc.select("A* where B.b=2").format("JSON") { "A": { "b": 1 },"AA":
{ "b": 4 } } abc2 = [ [ A:[b:1], B:[b:2], C:[b:3, d:50],
AA:[b:4] ], [ A:[b:11], B:[b:22], C:[b:33, d:5050], AA:[b:40] ]
] print abc2.select("A* wherein b>2").format("JSON") [ { "AA": {
"b": 4 } },{ "A": { "b": 11 },"AA": { "b": 40 } } ] new feature:
JmolSQL xxxx.select("(<keys>) WHERE/WHEREIN <clause>") -- parentheses
around keys replaces ";" idea -- indicates to return an array of values
rather than a key/value pair -- works also for array xxxx where each
element of xxxx is an array or associative array, in which case it
returns an array of matching values, without keys. -- example: load
=1ehz/dssr print _M.dssr.hbonds.select("*
*distance where res_long like '*|C|72|*'") { "distance" :
2.832 } { "distance" : 2.879 } {
"distance" : 2.838 } print _M.dssr.hbonds.select("(*
*distance) where res_long like '*|C|72|*'") 2.832 2.879
2.838 print _M.dssr.hbonds.select("(*
*distance) where res_long like '*|C|72|*'").average 2.8496666 *
------------------------------------------------------------------------------
_______________________________________________
Jmol-users mailing list
Jmol-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/jmol-users
