The ringsystem Command

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.

Examples:

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

ringsystem 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:

ringsystem append $ehandle 1 Y_NAME “_centroid”

ringsystem atoms

ringsystem atoms ehandle label ?filterset? ?filtermode?

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

Example:

ringsystem atoms $ehandle carbon

returns the labels of the carbon atoms in the ring system.

ringsystem bonds

ringsystem bonds ehandle label ?filterset? ?filtermode?

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

Examples:

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

ringsystem create ehandle atomlist

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.

Example:

ringsystem create $ehandle {1 2 3}

ringsystem defined

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

Example:

ringsystem defined $ehandle 1 Y_NAME

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

ringsystem delete

ringsystem delete ehandle ?label?...

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

ringsystem 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 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.

ringsystem exists

ringsystem exists ehandle label ?filterlist?

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

Example:

ringsystem exists $ehandle 99

ringsystem expr

ringsystem expr ehandle label expression

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

ringsystem fill

ringsystem 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:

ringsystem fill $ehandle 1 A_COLOR red

sets the color of the first atom ring system 1 contains to red .

ringsystem filter

ringsystem filter ehandle label filterlist

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

Example:

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

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

Examples:

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

ringsystem 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:

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 .

Further examples:

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

ringsystem groups

ringsystem groups ehandle label ?filterset? ?filtermode?

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

Example:

ringsystem groups $ehandle 1

ringsystem hydrogenate

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

Example:

ringsystem hydrogenate $eh 1 {!arobond !ccbond}

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

ringsystem index

ringsystem index ehandle label

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.

Example:

ringsystem index $ehandle 99

ringsystem jget

ringsystem jget ehandle label propertylist ?filterset? ?parameterlist?

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

ringsystem jnew

ringsystem jnew ehandle label propertylist ?filterset? ?parameterlist?

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

ringsystem jshow

ringsystem jshow ehandle label propertylist ?filterset? ?parameterlist?

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

ringsystem ligands

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

Example:

set subcnt [ringsystem ligands $eh $ylabel {!hydrogen} count]

ringsystem local

ringsystem 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:

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

ringsystem match ehandle label ssehandle ?sslabel? ?matchflags? ?ignoreflags? ?atommapvar? ?bondmapvar? ?molmapvar?

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.

Example:

set ss [ens create {c1ccccc1.c1ncccc1} smarts]
set rs_contains_phenyl [ringsystem match $ehandle $label $ss 1]

ringsystem mols

ringsystem mols ehandle label ?filterset? ?filtermode?

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

Examples:

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

ringsystem 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 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

ringsystem 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 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

ringsystem pis ehandle label ?filterset? ?filtermode?

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.

Examples:

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 rings

ringsystem rings 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:

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

ringsystem ringsystem ehandle label

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

Example:

ringsystem ringsystem $ehandle #0

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

ringsystem set

ringsystem 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:

ringsystem set $ehandle 1 Y_NAME “The central pharmacophore”

ringsystem show

ringsystem 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 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

ringsystem sigmas ehandle label ?filterset? ?filtermode?

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.

Examples:

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

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

ringsystem sqlget

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

ringsystem sqlnew

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

ringsystem sqlshow

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

ringsystem subcommands

ringsystem subcommands

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

ringsystem surfaces

ringsystem surfaces ehandle label ?filterset? ?filtermode?

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.

Example:

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.