The ring Command

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.

Examples:

ring get $ehandle 1 R_SIZE

This is the list of officially supported subcommands:

ring append

ring append ehandle label property value ?property value?..

Standard data manipulation command for appending property data. It is explained in more detail in the section about setting property data.

Example:

ring append $ehandle 1 R_NAME “_centroid”

ring atoms

ring atoms ehandle label ?filterset? ?filtermode?

Standard cross-referencing command to obtain the labels of the atom in the ring. This is explained in more detail in the section about object cross-references.

Example:

ring atoms $ehandle 1 carbon

returns the labels of the carbon atoms in the ring.

ring bonds

ring bonds ehandle label ?filterset? ?filtermode?

Standard cross-referencing command to obtain the labels 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.

Examples:

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

ring defined ehandle label 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.

Example:

ring defined $ehandle 1 R_AROMATIC

checks whether ring 1 is of a type for which property r_arOMATIC is defined.

ring delete

ring delete ehandle ?label?...

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.

The command returns the number of deleted items.

ring dget

ring dget ehandle label propertylist ?filterset? ?parameterlist?

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

ring exists ehandle label ?filterlist?

Check whether this ring exists. Optionally, a filter list can be supplied to check for the presence of specific features. The command returns 0 if the ring does not exist, or fails the filter, and 1 in case of successful testing.

Example:

ring exists $ehandle 99

ring expr

ring expr ehandle label expression

Compute a standard SQL -style property expression for the ring. This is explained in detail in the chapter on property expressions.

ring fill

ring fill ehandle label property value ?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.

Example:

ring fill $ehandle 1 B_COLOR red

sets the color of the first bond ring 1 contains to red .

ring filter

ring filter ehandle label filterlist

Check whether a ring passes a filter list. The return value is 1 for success and 0 for failure.

Example:

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

ring formulamatch ehandle label formula_expression ?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.

Example:

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

ring get ehandle label propertylist ?filterset? ?parameterlist?

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

Examples:

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 .

Further examples:

ring get $ehandle 1 E_NAME
ring get $ehandle 1 A_FLAGS(boxed)

ring groups

ring groups ehandle label ?filterset? ?filtermode?

Standard cross-referencing command to obtain the labels 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.

Example:

ring groups $ehandle 1

ring hydrogenate

ring hydrogenate ehandle label ?filterset? ?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.

Example:

ring hydrogenate $eh 1 {!arobond !ccbond}

This reduces all non-aromatic hetero bonds in ring 1 to single bonds.

ring index

ring index ehandle label

Get the index of the ring. The index is the position in the ring list of the ensemble. The first position is index 0.

Example:

ring index $ehandle 99

ring jget

ring jget ehandle label propertylist ?filterset? ?parameterlist?

This is a variant of ring get which returns the result data as a JSON formatted string instead of Tcl interpreter objects.

ring jnew

ring jnew ehandle label propertylist ?filterset? ?parameterlist?

This is a variant of ring new which returns the result data as a JSON formatted string instead of Tcl interpreter objects.

ring jshow

ring jshow ehandle label propertylist ?filterset? ?parameterlist?

This is a variant of ring show which returns the result data as a JSON formatted string instead of Tcl interpreter objects.

ring ligands

ring ligands ehandle label ?filterset? ?filtermode? ?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.

Example:

set nonringsubcnt [rings ligands $eh $rlabel {!hydrogen !ringatom} count]

ring local

ring local ehandle label propertylist ?filterset? ?parameters?

Standard data manipulation command for reading and recalculating object data. It is explained in more detail in the section about retrieving property data.

Example:

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

ring match ehandle label ss_ehandle ?ss_label? ?matchflags? ?ignoreflags? ?atommapvar? ?bondmapvar? ?molmapvar?

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.

Example:

set ss [ens create {c1ccccc1} smarts]
set r_is_phenyl [ring match $ehandle $label $ss]

ring mols

ring mols ehandle label ?filterset? ?filtermode?

Standard cross-referencing command to obtain the labels 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.

Examples:

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

ring new ehandle label propertylist ?filterset? ?parameterlist?

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

ring nget ehandle label propertylist ?filterset? ?parameterlist?

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

ring pis ehandle label ?filterset? ?filtermode?

Standard cross-referencing command to obtain the labels of the π systems the ring overlaps with. This is explained in more detail in the section about object cross-references.

Examples:

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 ring

ring ring ehandle label

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.

Example:

ring ring $ehandle #0

returns the label of the first ring of the ensemble ring list.

ring ringsystem

ring ringsystem ehandle label ?filterset? ?filtermode?

Standard cross-referencing command to obtain the labels of the ring system the ring is a member of. This is explained in more detail in the section about object cross-references.

Examples:

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

ring set ehandle label property value ?property value?..

Standard data manipulation command. It is explained in more detail in the section about setting property data.

Example:

ring set $ehandle 1 R_NAME “The central pharmacophore”

ring show

ring show ehandle label propertylist ?filterset? ?parameterlist?

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

ring sigmas ehandle label ?filterset? ?filtermode?

Standard cross-referencing command to obtain the labels of the σ systems the ring overlaps with. This is explained in more detail in the section about object cross-references.

Examples:

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

ring sqldget ehandle label propertylist ?filterset? ?parameterlist?

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 script processing.

ring sqlget

ring sqlget ehandle label propertylist ?filterset? ?parameterlist?

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 script processing.

ring sqlnew

ring sqlnew ehandle label propertylist ?filterset? ?parameterlist?

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 script processing.

ring sqlshow

ring sqlshow ehandle label propertylist ?filterset? ?parameterlist?

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 script processing.

ring subcommands

ring subcommands

Lists all subcommands of the ring command. Note that this command does not require an ensemble handle, or a label.

ring surfaces

ring surfaces ehandle label ?filterset? ?filtermode?

Standard cross-referencing command to obtain the labels of surface patches the ring is associated with. This is explained in more detail in the section about object cross-references.

Example:

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.