The ringsystem command is the generic command used to manipulate ring systems. The syntax of this command follows the standard schema of command/subcommand/majorhandle/minorlabel .
Pseudo ring system labels first , last and random are special values, which select the first ring system in the ring system list, the last, or a random ring system.
ring get $ehandle 1 Y_NATOMS
The command can also be invoked as shortened alias
ringsys
.
The default property name prefix for ringsystem-level properties is Y_ . The R_ prefix is used for more commonly encountered ring properties.
This is the list of officially supported subcommands:
ringsystem append ehandle label ?property value?...
y.append({?property:value,?...})
y.append(?property,value,?...)
Standard data manipulation command for appending property data. It is explained in more detail in the section about setting property data.
The command returns the first data value.
ringsystem append $ehandle 1 Y_NAME “_centroid”
ringsystem atoms ehandle label ?filterset? ?filtermode?
y.atoms(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the atom in the ring system. This is explained in more detail in the section about object cross-references.
ringsystem atoms $ehandle carbon
ringsystem bonds ehandle label ?filterset? ?filtermode?
y.bonds(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the bonds the ring system contains. This is explained in more detail in the section about object cross-references.
Technically, a ring system contains atoms, not bonds. This command lists all bonds which exist between atoms in the ring system and which are of a type which matches the current ring bond mask and which are ring bonds.
rinsysg bonds $ehandle 1
ringsystem bonds $ehandle 1 {1 doublebond triplebond} count
The first example returns all labels of the bonds ring system 1 contains. The second example returns the number of double or triple bonds in the ring system.
ringsystem create ehandle ?atom/atomlist?...
Ringsystem(eref,?aref/arefsequence/alabel?,...)
Ringsystem(aref,...)
Ringsystem.Create(eref,?aref/arefsequence/alabel?,...)
Ringsystem.Create(aref,...)
This command can be used to manually create a ring system or pseudo ring system from an arbitrary collection of atoms. No check is made whether the atoms actually form a valid ring system. The result value of the command is the label of the newly created ring system. This command generates a ringsystem property invalidation event and may thus indirectly influence the ensemble data.
By default, ring systems are automatically created whenever they are referenced and not yet set up for the context ensemble.
The command returns the label or reference of the new ringsystem.
ringsystem create $ehandle {1 2 3}
ringsystem defined ehandle label property
y.defined(property)
This command checks whether a property is defined for the ring system. This is explained in more detail in the section about property validity checking. Note that this is not a check for the presence of property data! The
ens valid
command is used for this purpose.
ringsystem defined $ehandle 1 Y_NAME
checks whether ring system 1 is of a type for which property Y_NAME is defined.
ringsystem delete ehandle ?label?...
ringsystem delete ehandle all
y.delete()
Ringsystem.Delete(eref,”all”)
Ringsystem.Delete(yref,...)
Ringsystem.Delete(eref,?ylabel/yref/yrefsequence?,...)
This command removes ring systems from the ensemble ring system list and destroys them. A ringsystem property invalidation event is generated and thus the command may indirectly change the ensemble data.
The command returns the number of deleted items.
This command is rarely used. Ring systems are usually generated and destroyed automatically.
ringsystem dget ehandle label propertylist ?filterset? ?parameterdict?
y.dget(property=,?filters=?,?parameters=?)
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
ringsystem get
command. The difference between
ringsystem get
and
ringsystem dget
is that the latter does not attempt computation of property data, but rather initializes the property values to the default and return that default if the data is not yet available. For data already present,
ringsystem get
and
ringsystem dget
are equivalent.
y.ens()
Python -only method to get the ensemble reference from a ringsystem reference.
ringsystem exists ehandle label ?filterlist?
r.exists(?filters=?)
Ringsystem.Exists(eref,label,?filters=?)
Check whether this ring system exists. Optionally, a filter list can be supplied to check for the presence of specific features. The command returns boolean 0 if the ring system does not exist, or fails the filter, and 1 in case of successful testing.
ringsystem exists $ehandle 99
ringsystem expr ehandle label expression
y.exp(rexpression)
Compute a standard SQL -style property expression for the ring system. This is explained in detail in the chapter on property expressions.
ringsystem fill ehandle label ?property value?...
y.fill({property:value,...})
y.fill(?property,value?,...)
Standard data manipulation command for setting data, ignoring possible mismatches between the lengths of the lists of objects associated with the property and the value list. It is explained in more detail in the section about setting property data.
The command returns the first fill value.
ringsystem fill $eh 1 A_COLOR [lrepeat [ringsystem atoms $ehandle 1 {} count] red
ringsystem filter ehandle label filterlist
y.filter(filters)
Check whether a ring system passes a filter list. The return value is boolean 1 for success and 0 for failure.
ringsystem filter $ehandle 1 [list carbon doublebond]
checks whether the ring system contains one or more carbon atoms and one or more double bonds. The double bond does not need to include a carbon atom.
ringsystem formulamatch ehandle label formula_expression ?other_elements?
y.formulamatch(query=,?other_elements=?)
Match the ringsystem against a formula expression. Its syntax is the same as in formula queries in
molfile scan
and other scan commands.
There are several methods to specify whether any elements not mentioned in the formula expression may or must be present. If the other_elements flag is used, it has the highest priority. If may be set to 0 (no other elements allowed), 1 (allowed) or 2 (required), and if it is set, any prefix in the formula expression is ignored. If it is not used, a prefix in the formula expression may be used to control the matching. Supported prefixes are = (no other elements), >= (other elements allowed) and > (required). If no prefix is used, the default mode is an exact match without other elements.
The return value is the boolean match result.
ringsystem formulamatch $eh 1 >C6
Tests whether the ring system contains six carbon atoms. At least one atom which is not carbon must be present.
ringsystem formulamatch $eh 1 C5-6(Cl+Br+I)2- 1
Tests whether the ring system has five or six carbon atoms, two ore more heavy halogens, and potentially any other elements.
ringsystem get ehandle label propertylist ?filterset? ?parameterdict?
y.get(property=,?filters=?,?parameters=?)
y[property]
y.property
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
ringsystem get $ehandle 1 {Y_NATOMS A_ELEMENT}
yields a list with two elements, consisting of the ring system size as the first element and the element numbers of all atoms in the ring system as a nested list as the second result list element. If the information is not yet available, an attempt is made to compute it. If the computation fails, an error results.
ringsystem get $ehandle 1 B_ORDER cxbond
reports the bond orders of all bonds of the ring system which are carbon-hetero bonds.
For the use of the optional property parameter list argument, refer to the documentation of the
ens get
command.
Variants of the
ringsystem get
command are
ringsystem dget, ringsystem new, ringsystem nget, ringsystem show, ringsystem sqldget, ringsystem sqlget, ringsystem sqlnew,
and
ringsystem sqlshow
.
ringsystem get $ehandle 1 E_NAME
ringsystem get $ehandle 1 A_FLAGS(boxed)
ringsystem groups ehandle label ?filterset? ?filtermode?
y.groups(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the groups the ring system overlaps with. This is explained in more detail in the section about object cross-references. An overlap between a ring system and a group is established when there are common atoms which are contained in both objects.
ringsystem groups $ehandle 1
ringsystem hydrogenate ehandle label ?filterset? ?changeset?
y.hydrogenate(?filters=?,?changeset=?)
Reduce all bonds in the ringsystem to single bonds except those excluded by the filter set.
If a change set is supplied, its interpretation is the same as in
mol hadd.
The command returns the number of added hydrogens.
ringsystem hydrogenate $eh 1 {!arobond !ccbond}
This reduces all non-aromatic hetero bonds in ringsystem 1 to single bonds.
ringsystem index ehandle label
y.index()
Get the index of the ring system. The index is the position in the ring system list of the ensemble. The first position is index 0.
ringsystem index $ehandle 99
ringsystem jget ehandle label propertylist ?filterset? ?parameterdict?
y.jget(property=,?filters=?,?parameters=?)
This is a variant of
ringsystem get
which returns the result data as a
JSON
formatted string instead of
Tcl
or
Python
interpreter objects.
ringsystem jnew ehandle label propertylist ?filterset? ?parameterdict?
y.jnew(property=,?filters=?,?parameters=?)
This is a variant of
ringsystem new
which returns the result data as a
JSON
formatted string instead of
Tcl
or
Python
interpreter objects.
ringsystem jshow ehandle label propertylist ?filterset? ?parameterdict?
y.jshow(property=,?filters=?,?parameters=?)
This is a variant of
ringsystem show
which returns the result data as a
JSON
formatted string instead of
Tcl
or
Python
interpreter objects.
ringsystem ligands ehandle label ?filterset? ?filtermode? ?sphere?
y.ligands(?filters=?,?mode=?,?sphere=?)
Get the labels of atoms that are ligands to the current ring system, i.e. they are not member of the ring system, but bonded to it. The filterset and filtermode parameters work as with other object cross-reference commands.
This command supports a special filtermode parameter in addition to the standard set ( exists , count , exclude , include ). The bonds parameter, followed by a bit set combination from the allowed values ring , sidechain or bridge can be used for topological filtering of the traversable bonds. By default, no topological bond filtering is applied.
The default sphere number is one, meaning only the direct ring system substituents are reported. A higher positive number extracts more distant atoms, but still excludes the ring system atoms. A negative sphere number works the same way, but the result set includes atoms seen in inner spheres. Duplicate atoms encountered in different spheres are not reported by default.
If the filter set contains a bond filter, it is applied to the bond linking the first sphere atom to the ring system or leading from an inner to the outer sphere atom. This means it is not sufficient for an atom to possess any bond which passes the filter, but it must be the bond to the ring system or sphere expansion atom.
set subcnt [ringsystem ligands $eh $ylabel {!hydrogen} count]
ringsystem local ehandle label propertylist ?filterset? ?parameterdict?
y.local(property=,?filters=?,?parameters=?)
Standard data manipulation command for reading and recalculating object data. It is explained in more detail in the section about retrieving property data.
ringsystem local $ehandle 1 A_LABEL_STEREO
Note that very few computation routines currently support the local re-computation of data - in most cases, this command falls back to a global re-computation.
ringsystem match ehandle label ssehandle ?sslabel? ?matchflags? ?ignoreflags? ?atommatchvar? ?bondmatchvar? ?molmatchvar?
y.match(substructure=,?substructureringsystem=?,?matchflags=?,?ignoreflags=?, ?atommatchvariable=?,?bondmatchvariable=?,?molmatchvariable=?)
Check whether the selected ringsystem matches a substructure. Only the first substructure ring system, or the ring system selected by the substructure label parameter, is tested. The substructure may be part of any structure ensemble, and even be in the same ensemble as the primary command ring system. Both the atoms in the ringsystem and the bonds between them are checked.
The precise operation of the substructure match routine can be tuned by providing a standard set of match flags and feature ignore flags. The default match flag set has set bits for the bondorder , atomtree and bondtree comparison features, and an empty ignore set. If a flag set is specified as an empty string, the default set is used. In order to reset a flag set, an explicit none value must be used.
The command returns 1 for a successful match, 0 otherwise. If an optional atom, bond, or molecule map variable is specified, it is set to a nested list of matching substructure/structure atom, bond or molecule labels. If no match can be found, the variable is set to an empty list. In case only a bond or molecule map variable is needed, an empty string can be used to skip the unused map variable argument positions.
set ss [ens create {c1ccccc1.c1ncccc1} smarts]
set rs_contains_phenyl [ringsystem match $ehandle $label $ss 1]
ringsystem mols ehandle label ?filterset? ?filtermode?
y.mols(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the molecules the ring system participates in. This is explained in more detail in the section about object cross-references. Under specific circumstances, it is possible to have ring systems which span more than one molecule.
ringsystem mols $ehandle 1
ringsystem mols $ehandle 1 [list heterocycle aroring]
The first example returns the labels of all molecules the ring system is a part of. The second example filters the molecules - only molecules which contain heteroaromatic rings are reported. The ring filter is applied to the molecule because this is the return object, not the ring, so this filter does not require the ring the command was issued for to be in that class.
ringsystem new ehandle label propertylist ?filterset? ?parameterdict?
y.new(property=,?filters=?,?parameters=?)
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
ringsystem get
command. The difference between
ringsystem get
and
ringsystem new
is that the latter forces the re-computation of the property data, regardless whether it is present and valid, or not.
ringsystem nget ehandle label propertylist ?filterset? ?parameterdict?
y.new(property=,?filters=?,?parameters=?)
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
ringsystem get
command. The difference between
ringsystem get
and
ringsystem nget
is that the latter always returns numeric data, even if symbolic names for the values are available.
ringsystem pis ehandle label ?filterset? ?filtermode?
y.pis(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the π systems the ring system overlaps with. This is explained in more detail in the section about object cross-references.
ringsystem pis $ehandle 1
π systems are a rather exotic feature and not commonly used. These are essentially descriptions of bonding interactions which use p or d orbitals, such as in standard covalent multiple bonds. A simple double bond is described with one σ system and one π system in this representation.
Ringsystem.Ref(eref,identifier)
Python
only method to get a ringsystem reference. See
ringsystem ringsystem
command.
ringsystem rings ehandle label ?filterset? ?filtermode?
y.rings(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the ring system the ring is a member of. This is explained in more detail in the section about object cross-references.
ringsystem rings $ehandle 1
ringsystem rings $ehandle 1 [list heterocycle aroring]
The first example returns the labels of the rings which are contained in the ring system. The second example filters the ring system - a ring label is obtained only if that ring system contains one or more heteroaromatic rings. These filters are applied to the individual rings in the ring system, not the command ringsystem.
ringsystem ringsystem ehandle label
Ringsystem.Ref(eref,identifier)
Standard cross-referencing command to obtain the label or reference of the ring. This is explained in more detail in the section about object cross-references.
ringsystem ringsystem $ehandle #0
returns the label of the first ring system of the ensemble ring system list.
ringsystem set ehandle label ?property value?...
y.set(?property,value?,...)
y.set({property:value,...})
y.property = value
y[property] = value
Standard data manipulation command. It is explained in more detail in the section about setting property data.
ringsystem set $ehandle 1 Y_NAME “The central pharmacophore”
ringsystem show ehandle label propertylist ?filterset? ?parameterdict?
y.show(property=,?filters=?,?parameters=?)
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
ringsystem get
command. The difference between
ringsystem
get
and ringsystem show
is that the latter does not attempt computation of property data, but raises an error if the data is not present and valid. For data already present,
ringsystem get
and
ringsystem show
are equivalent.
ringsystem sigmas ehandle label ?filterset? ?filtermode?
y.sigmas(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels of the σ systems the ring system overlaps with. This is explained in more detail in the section about object cross-references.
ringsystem sigmas $ehandle 1
σ systems are a rather exotic feature and not commonly used. These are essentially descriptions of bonding interactions which use s orbitals, such as normal, covalent single bonds, or the central bond in multiple bonds. A simple double bond is described with one σ system and one π system in this representation.
ringsystem sqldget ehandle label propertylist ?filterset? ?parameterdict?
y.sqldget(property=,?filters=?,?parameters=?)
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
ringsystem get
command. The differences between
ringsystem get
and
ringsystem sqldget
are that the latter does not attempt computation of property data, but initializes the property value to the default and returns that default, if the data is not present and valid; and that the
SQL
command variant formats the data as
SQL
values rather than for
Tcl
or
Python
script processing.
ringsystem sqlget ehandle label propertylist ?filterset? ?parameterdict?
y.sqlget(property=,?filters=?,?parameters=?)
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
ringsystem get
command. The difference between
ringsystem get
and
ringsystem sqlget
is that the
SQL
command variant formats the data as
SQL
values rather than for
Tcl
or
Python
script processing.
ringsystem sqlnew ehandle label propertylist ?filterset? ?parameterdict?
y.sqlnew(property=,?filters=?,?parameters=?)
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
ringsystem get
command. The differences between
ringsystem get
and
ringsystem sqlnew
are that the latter forces re-computation of the property data, and that the
SQL
command variant formats the data as
SQL
values rather than for
Tcl
or
Python
script processing.
ringsystem sqlshow ehandle label propertylist ?filterset? ?parameterdict?
y.sqlshow(property=,?filters=?,?parameters=?)
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
ringsystem get
command. The differences between
ringsystem get
and
ringsystem sqlshow
are that the latter does not attempt computation of property data, but raises an error if the data is not present and valid, and that the
SQL
command variant formats the data as
SQL
values rather than for
Tcl
or
Python
script processing.
ringsystem subcommands
dir(Ringsystem)
Lists all subcommands of the
ringsystem
command. Note that this command does not require an ensemble handle, or a label.
ringsystem surfaces ehandle label ?filterset? ?filtermode?
y.surfaces(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels of surface patches the ring system is associated with. This is explained in more detail in the section about object cross-references.
ringsystem surfaces $ehandle $label
Note that surface patches do not need to be associated with an atom, and if they are not, they are implicitly not associated with any ring system.