The ring command is the generic command used to manipulate rings. The syntax of this command follows the standard schema of command/subcommand/majorhandle/minorlabel .
Pseudo ring labels first , last and random are special values, which select the first ring in the ring list, the last, or a random ring.
ring get $ehandle 1 R_SIZE
This is the list of officially supported subcommands:
ring append ehandle label ?property value?...
r.append({?property:value,?...})
r.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.
ring append $ehandle 1 R_NAME “_centroid”
ring atoms ehandle label ?filterset? ?filtermode?
r.atoms(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the atom in the ring. This is explained in more detail in the section about object cross-references.
ring atoms $ehandle 1 carbon
ring bonds ehandle label ?filterset? ?filtermode?
r.bonds(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the bonds the ring contains. This is explained in more detail in the section about object cross-references. Technically, a ring contains atoms, not bonds. This command lists all bonds which exist between consecutive atoms in the ring and which are of a type which matches the current ring bond mask.
ring bonds $ehandle 1
ring bonds $ehandle 1 {1 doublebond triplebond} count
The first example returns all labels of the bonds ring 1 contains. The second example returns the number of double or triple bonds in the ring.
ring defined ehandle label property
r.defined(property)
This command checks whether a property is defined for the ring. 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.
ring defined $ehandle 1 R_AROMATIC
checks whether ring 1 is of a type for which property r_arOMATIC is defined.
ring delete ehandle ?label?...
ring delete ehandle all
r.delete()
Ring.Delete(eref,”all”)
Ring.Delete(rref,...)
Ring.Delete(eref,?rlabel/rref/rrefsequence?,...)
This command removes rings from the ensemble ring list and destroys them. A ring property invalidation event is generated and thus the command may indirectly change the ensemble data.
This command is rarely used. Rings are usually generated and destroyed automatically.
ring dget ehandle label propertylist ?filterset? ?parameterdict?
r.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
ring get
command. The difference between
ring get
and
ring 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,
ring get
and
ring dget
are equivalent.
ring exists ehandle label ?filterlist?
r.exists(?filters=?)
Ring.Exists(eref,label,?filters=?)
Check whether this ring exists. Optionally, a filter list can be supplied to check for the presence of specific features. The command returns boolean 0 if the ring does not exist, or fails the filter, and 1 in case of successful testing.
ring exists $ehandle 99
ring expr ehandle label expression
r.expr(expression)
Compute a standard SQL -style property expression for the ring. This is explained in detail in the chapter on property expressions.
ring fill ehandle label ?property value?...
r.fill({property:value,...})
r.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.
ring fill $ehandle 1 B_COLOR red
ring filter ehandle label filterlist
r.filter(filters)
Check whether a ring passes a filter list. The return value is boolean 1 for success and 0 for failure.
ring filter $ehandle 1 [list carbon doublebond]
checks whether the ring contains one or more carbon atoms and one or more double bonds. The double bond does not need to contain a carbon atom.
ring formulamatch ehandle label formula_expression ?other_elements?
r.formulamatch(query=,?other_elements=?)
Match the ring 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.
ring formulamatch $eh 1 >C6
Tests whether the ring contains six carbon atoms. At least one atom which is not carbon must be present.
ring formulamatch $eh 1 C5-6(Cl+Br+I)2- 1
Tests whether the ring has five or six carbon atoms, two ore more heavy halogens, and potentially any other elements.
ring get ehandle label propertylist ?filterset? ?parameterdict?
r.get(property=,?filters=?,?parameters=?)
r[property]
r.property
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
ring get $ehandle 1 {R_SIZE A_ELEMENT}
yields a list with two elements, consisting of the ring size as the first element and the element numbers of all atoms in the ring 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.
ring get $ehandle 1 B_ORDER cxbond
reports the bond orders of all bonds of the ring which are carbon-heteroatom bonds.
For the use of the optional property parameter list argument, refer to the documentation of the
ens get
command.
Variants of the
ring get
command are
ring dget, ring new, ring nget, ring show, ring sqldget, ring sqlget, ring sqlnew,
and
ring sqlshow
.
ring get $ehandle 1 E_NAME
ring get $ehandle 1 A_FLAGS(boxed)
ring groups ehandle label ?filterset? ?filtermode?
r.groups(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the groups the ring overlaps with. This is explained in more detail in the section about object cross-references. An overlap between a ring and a group is established when there are common atoms which are contained in both objects.
ring groups $ehandle 1
ring hydrogenate ehandle label ?filterset? ?changeset?
r.hydrogenate(?filters=?,?changeset=?)
Reduce all bonds in the ring 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.
ring hydrogenate $eh 1 {!arobond !ccbond}
This reduces all non-aromatic hetero bonds in ring 1 to single bonds.
ring index ehandle label
r.index()
Get the index of the ring. The index is the position in the ring list of the ensemble. The first position is index 0.
ring index $ehandle 99
ring jget ehandle label propertylist ?filterset? ?parameterdict?
r.jget(property=,?filters=?,?parameters=?)
This is a variant of
ring get
which returns the result data as a
JSON
formatted string instead of
Tcl
interpreter objects.
ring jnew ehandle label propertylist ?filterset? ?parameterdict?
g.jnew(property=,?filters=?,?parameters=?)
This is a variant of
ring new
which returns the result data as a
JSON
formatted string instead of
Tcl
interpreter objects.
ring jshow ehandle label propertylist ?filterset? ?parameterdict?
g.jshow(property=,?filters=?,?parameters=?)
This is a variant of
ring show
which returns the result data as a
JSON
formatted string instead of
Tcl
interpreter objects.
ring ligands ehandle label ?filterset? ?filtermode? ?sphere?
r.ligands(?filters=?,?mode=?,?sphere=?)
Get the labels of atoms that are ligands to the current ring, i.e. they are not member of the ring, 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 substituents are reported. A higher positive number extracts more distant atoms, but still excludes the ring 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 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 or sphere expansion atom.
set nonringsubcnt [rings ligands $eh $rlabel {!hydrogen !ringatom} count]
ring local ehandle label propertylist ?filterset? ?parameterdict?
r.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.
ring 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.
ring match ehandle label ss_ehandle ?ss_label? ?matchflags? ?ignoreflags? ? atommatchvar? ?bondmatchvar? ?molmatchvar?
r.match(substructure=,?substructurering=?,?matchflags=?,?ignoreflags=?, ?atommatchvariable=?,?bondmatchvariable=?,?molmatchvariable=?)
Check whether the selected ring matches a substructure. Only the first substructure ring, or the ring 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. Both the atoms in the ring 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} smarts]
set r_is_phenyl [ring match $ehandle $label $ss]
ring mols ehandle label ?filterset? ?filtermode?
r.mols(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the molecules the ring is contained in. This is explained in more detail in the section about object cross-references. Under specific circumstances, it is possible to have rings which span more than one molecule.
ring mols $ehandle 1
ring mols $ehandle 1 [list heterocycle aroring]
The first example returns the labels of all molecules the ring 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.
ring new ehandle label propertylist ?filterset? ?parameterdict?
r.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
ring get
command. The difference between
ring get
and
ring new
is that the latter forces the re-computation of the property data, regardless whether it is present and valid, or not.
ring nget ehandle label propertylist ?filterset? ?parameterdict?
r.nget(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
ring get
command. The difference between
ring get
and
ring nget
is that the latter always returns numeric data, even if symbolic names for the values are available.
ring pis ehandle label ?filterset? ?filtermode?
r.pis(?filter=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the π systems the ring overlaps with. This is explained in more detail in the section about object cross-references.
ring 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.
Ring.Ref(eref,identifier)
Python
only method to get a ring reference. See
ring ring
command.
ring ring ehandle label
Ring.Ref(eref,identifier)
Standard cross-referencing command to obtain the label of the ring as stored in property R_LABEL . This is explained in more detail in the section about object cross-references.
ring ring $ehandle #0
returns the label of the first ring of the ensemble ring list.
ring ringsystem ehandle label ?filterset? ?filtermode?
r.ringsystem(?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.
ring ringsystem $ehandle 1
ring ringsystem $ehandle 1 [list heterocycle aroring]
The first example returns the label of the ring system the ring is a member of. The second example filters the ring system - a ring system label is obtained only if that ring system contains one or more hetero aromats. These filters are applied to the ring system, meaning that they are implicitly applied to all rings in the ring system, not just the ring used for the query command.
Since a ring can only be a member of a single ring system, the command spells the target in singular.
ring set ehandle label ?property value?...
r.set(?property,value?,...)
r.set({property:value,...})
r.property = value
r[property] = value
Standard data manipulation command. It is explained in more detail in the section about setting property data.
ring set $ehandle 1 R_NAME “The central pharmacophore”
ring show ehandle label propertylist ?filterset? ?parameterdict?
r.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
ring get
command. The difference between
ring get
and
ring 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,
ring get
and
ring show
are equivalent.
ring sigmas ehandle label ?filterset? ?filtermode?
r.sigmas(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the σ systems the ring overlaps with. This is explained in more detail in the section about object cross-references.
ring 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.
ring sqldget ehandle label propertylist ?filterset? ?parameterdict?
r.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
ring get
command. The differences between
ring get
and
ring 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.
ring sqlget ehandle label propertylist ?filterset? ?parameterdict?
r.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
ring get
command. The difference between
ring get
and
ring sqlget
is that the
SQL
command variant formats the data as
SQL
values rather than for
Tcl
or
Python
script processing.
ring sqlnew ehandle label propertylist ?filterset? ?parameterdict?
r.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
ring get
command. The differences between
ring get
and
ring 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.
ring sqlshow ehandle label propertylist ?filterset? ?parameterdict?
r.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
ring get
command. The differences between
ring get
and
ring 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.
ring subcommands
dir(Ring)
Lists all subcommands of the
ring
command. Note that this command does not require an ensemble handle, or a label.
ring surfaces ehandle label ?filterset? ?filtermode?
r.surfaces(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of surface patches the ring is associated with. This is explained in more detail in the section about object cross-references.
ring 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.
ring xbonds ehandle label ?filterset? ?filtermode?
Get labels or references of crossing bonds which are not contained in the ring (defined as all bonds between any two consecutive registered atoms in the system), but have one atom in the ring. Bonds between atoms in the ring which are not part of the ring bond set are reported. For example, when looking at the six-membered outer envelope ring of bicyclobutane, the bridge between the two four-membered SSSR bonds is included in the result set.