The group Command

The group command is the generic command used to manipulate groups. The syntax of this command follows the standard schema of command/subcommand/majorhandle/minorlabel.

Pseudo group labels first , last and random are special values, which select the first group in the group list, the last, or a random group.

Example:

group get $ehandle 1 G_SIZE

This is the list of officially supported subcommands:

group add

group add ehandle label object/objectlist...
g.add(?object/objectsequence?,...),

Add more atoms or groups as members to an existing group. A group cannot be added to itself, and the formation of cyclic dependencies is illegal. It is however possible to add an atom or group more than once to a group, and an atom or a group may be a member of an arbitrary number of groups.

Adding objects to a group triggers a groupchange property invalidation event and may thus have an influence on the validity of chemical object data.

The use of an empty object list is possible and does not change the group, nor is an invalidation event issued.

The object list syntax is the same as in the group create command.

The command returns the original group label or reference.

Examples:

group add $ehandle $glabel 1
group add $ehandle $glabel [list “group” [group create $ehandle [list 5 7]]]

The first sample line simply adds the atom with label 1 to the group. The second line adds a newly created group with atoms 5 and 7 to the existing group as a recursive group element.

group append

group append ehandle label ?property value?...
g.append({?property:value,?...})
g.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.

Example:

group append $ehandle 1 G_NAME “_linker”

group atoms

group atoms ehandle label ?filterset? ?filtermode?
g.atoms(?filters=?,?mode=?)

List the labels or references of all atoms which are in the group. There are two different modes of operation, depending on whether the group contains at least one atom as member object.

If there is a member atom: Group member objects which are not atoms, such as bonds or recursive groups, are omitted from output, as are atoms which are only indirectly a group member via a recursive group.

Without atoms in the group, atoms which are components of the group objects are listed, e.g. the atoms of bonds that are in the group.

In other respects, this is a standard cross-referencing command. The usage of the filterset and filtermode parameter is explained in the section about object cross-references.

Example:

set gh [group create $ehandle [list 1 2 3]]
group atoms $ehandle $gh carbon

gets the labels of the carbon atoms in the group.

set gh [group create $ehandle [list [list „bond“ 1]]]
group atoms $ehandle $gh

while this command on a group which only contains bonds, but no atoms, reports the atom labels of the bond in the group.

group bonds

group bonds ehandle label ?filterset? ?filtermode?
g.bonds(?filters=?,?mode=?)

Retrieve the labels or references of bonds which are associated with a group. There are two different modes of operation, depending on whether the group contains at least one bond as member object.

If there is a member bond: Group member objects which are not bonds, such as atoms or recursive groups, are omitted from output, as are bonds which are only indirectly a group member via a recursive group.

Otherwise, a bond is considered to be associated with a group if all atoms of the bond are group members. All bond atoms must be in the same group object, i.e. indirect memberships via recursive groups are ignored. Bonds are not associated with a group if only some of their atoms are members of the group.

In other respects, this is a standard cross-referencing command. The usage of the filterset and filtermode parameter is explained in the section about object cross-references.

Example:

set gh [group create $ehandle [list 1 2 3]]
group bonds $ehandle $gh {1 doublebond triplebond}

gets the bond labels of all double and triple bonds between the group atoms.

set gh [group create $ehandle [list [list „bond“ 1]]]
group bonds $ehandle $gh

while this command directly lists the bond in the group.

group create

group create ehandle objectlist...
Group(?objectref?,...)
Group.Create(?object?ref,...)
Group(eref,?objectref/objectrefsequence/objectlabel?,...)
Group.Create(eref,?objectref/objectrefsequence/objectlabel?,...)

Create a new group containing atoms or other minor objects, including other groups as member elements.

The object list parameter is a list of object identifiers. An object identifier is either a single-element simple identifier, in which case it is interpreted as an atom identifier (usually a label, but all other identifiers are possible), or a two-element list. If the second form is used, the list must consist of an object class name, followed by an object identifier (usually a label, but all types of minor object identifiers are possible).

Specifying a member object which cannot be resolved produces an error. However, it is no error for an atom or a group to be listed more than once as a member of a group, nor is there any restriction of how many groups an atom or other minor object can be a member. However, circular relationships are illegal, and a group cannot be a member of itself. Duplicate objects in a group are allowed and not filtered when a group is set up.

Creating a new group triggers the group and groupchange invalidation events and may thus influence the validity of chemical object data.

The creation of empty groups by supplying an empty object list is possible.

The return value of this function is the label of the new group.

Examples:

set g1 [group create $ehandle {1 2 3}]
set g2 [group create $ehandle [list [list “group” $g1] 4 [list “atom” #5]]]

The first line creates a simple group with atoms 1, 2 and 3. The second line builds a recursive group which contains the first group (identified as a group reference by prefixing its label with a group object class name), the atom with label 4, and the atom with index 5 (which could have any label).

group defined

group defined ehandle label property
g.defined(property)

This command checks whether a property is defined for the group. 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:

group defined $ehandle 1 G_XYZ

checks whether group 1 is of a type for which G_XYZ is defined.

group delete

group delete ehandle ?label?...
group delete ehandle all
g.delete()
Group.Delete(eref,”all”)
Group.Delete(gref,...)
Group.Delete(eref,?glabel/gref/grefsequence?,...)

Delete a set of groups. Groups are either identified by a standard group identifier (usually a label), or the reserved word all.

If a deleted group contains as a member another group, that group is also deleted in a recursive fashion. If this behavior is not wanted, recursive groups should be explicitly unlinked from their base groups by means of the group remove command.

Deleting a group triggers the group and groupchange invalidation events and may thus influence the validity of chemical object data. If an empty object list is used, the command does nothing, and no invalidation event is generated.

This command returns the number of deleted groups on the first level, i.e. recursive group deletions are not counted.

Examples:

group delete $ehandle all
group delete $ehandle [ens groups $ehandle xatom]

The first example deletes all groups in the ensemble. The second example deletes all those groups which contain one or more hetero atoms as members.

group dget

group dget ehandle label propertylist ?filterset? ?parameterdict?
g.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 group get command. The difference between group get and group 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, group get and group dget are equivalent.

group dup

group dup ehandle label ?datasethandle? ?position?
g.dup(?target=?,?position=?)

Duplicate the atoms and bonds of a group into a new ensemble. The function returns the new ensemble handle or reference.

By default, the new ensemble is appended to the same dataset as the original ensemble, or placed outside of any dataset if the input ensemble was not a dataset member. If the optional target dataset parameter is specified, the duplicate is directly moved to that dataset. If an empty string is passed (or None for Python ), the duplicate is not made a dataset member, even if the input ensemble is in a dataset.

Example:

group dup $ehandle 1 [dataset create]

duplicates the group with label one and move the new single-molecule ensemble into a newly created dataset.

group ens

g.ens()

Python -only method to get the ensemble reference from a group reference.

group exists

group exists ehandle label ?filterlist?
g.exists(?filters=?)
Group.Exists(eref,label,?filters=?)

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

Example:

group exists $ehandle 99

group expr

group expr ehandle label expression
g.expr(expression)

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

group fill

group fill ehandle label ?property value?...
g.fill({property:value,...})
g.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.

Example:

group fill $ehandle 1 B_COLOR red

sets the color of the first bond group 1 contains or is associated with to red.

group filter

group filter ehandle label filterlist
g.filter(filters)

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

Example:

group filter $ehandle 1 [list carbon doublebond]

checks whether the group contains one or more carbon atoms and one or more double bonds. The double bond does not need to be with a carbon atom.

group formulamatch

group formulamatch ehandle label formula_expression ?other_elements?
g.formulamatch(query=,?other_elements=?)

Match the group 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:

group formulamatch $eh 1 >C6

Tests whether the group contains six carbon atoms. At least one atom which is not carbon must be present.

group formulamatch $eh 1 C5-6(Cl+Br+I)2- 1

Tests whether the group has five or six carbon atoms, two ore more heavy halogens, and potentially any other elements.

group get

group get ehandle label propertylist ?filterset? ?parameterdict?
g.get(property=,?filters=?,?parameters=?)
g[property]
g.property

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

Examples:

group get $ehandle 1 {G_SIZE A_ELEMENT}

yields a list with two elements, consisting of the group size (count of group members) as the first element and the element numbers of all atoms in the groups 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.

group get $ehandle 1 B_ORDER ringbond

gives the bond orders of all bonds of associated with the group which are ring bonds.

For the use of the optional property parameter list argument, refer to the documentation of the ens get command.

Variants of the group get command are group new, group dget, group nget, group show, group sqldget, group sqlget, group sqlnew and group sqlshow .

Further examples:

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

group group

group group ehandle label
Group.Ref(eref,identifer)

Standard cross-referencing command to obtain the label or reference of the group as stored in property G_LABEL . This is explained in more detail in the section about object cross-references. Note that there is also a group groups (plural groups ) command which has a different function.

Example:

group group $ehandle #0

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

group groups

group groups ehandle label ?filterset? ?filtermode?
g.groups(?filters=?,?mode=?)

List the labels or references of all groups which are members of the group. Group member objects, such as atoms, which are not groups are omitted, as are groups which are only indirectly a group member via a recursive group.

In other respects, this is a standard cross-referencing command. The usage of the filterset and filtermode parameter is explained in the section about object cross-references. Note that there is also a group group (singular group ) command which has a different function.

Example:

group groups $ehandle 1

gets the labels of the groups which are a (recursive) member of group 1.

group hdup

group hdup ehandle label ?datasethandle? ?position?
g.hdup(?target=?,?position=?)

This command provides the same functionality as group dup , except that it also adds a standard set of hydrogens to the new ensemble.

group index

group index ehandle label
g.index()

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

Example:

group index $ehandle 99

group jget

group jget ehandle label propertylist ?filterset? ?parameterdict?
g.jget(property=,?filters=?,?parameters=?)

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

group jnew

group jnew ehandle label propertylist ?filterset? ?parameterdict?
g.jnew(property=,?filters=?,?parameters=?)

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

group jshow

group jshow ehandle label propertylist ?filterset? ?parameterdict?
g.jshow(property=,?filters=?,?parameters=?)

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

group local

group local ehandle label propertylist ?filterset? ?parameterdict?
g.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.

Example:

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

group match

group match ehandle label ss_ehandle ?ss_label? ?matchflags? ?ignoreflags? 	?atommatchvar? ?bondmatchvar? ?molmatchvar?
g.match(substructure=,?substructuregroup=?,?matchflags=?,?ignoreflags=?,	?atommatchvariable=?,?bondmatchvariable=?,?molmatchvariable=?)

Check whether the selected group matches a substructure. Only the first substructure group, or the group 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 group. Both the atoms in the group 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 match 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 match variable is needed, an empty string can be used to skip the unused match variable argument positions.

Example:

set ss [ens create {c1ccccc1} smarts]
set g_contains_phenyl_ring [group match $ehandle $label $ss]

group mols

group mols ehandle label ?filterset? ?filtermode?
g.mols(?filters=?,?mode=?)

Standard cross-referencing command to obtain the labels or references of the molecules the atoms in the group are a member of. This is explained in more detail in the section about object cross-references.

Examples:

group mols $ehandle 1
group mols $ehandle 1 heterocycle

The first example is simple retrieval, the second line filters the molecules and lists only the labels of those molecules which contain one or more heterocycles.

group new

group new ehandle label propertylist ?filterset? ?parameterdict?
g.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 group get command. The difference between group get and group new is that the latter forces the re-computation of the property data, regardless whether it is present and valid, or not.

group nget

group nget ehandle label propertylist ?filterset? ?parameterdict?
g.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 group get command. The difference between group get and group nget is that the latter always returns numeric data, even if symbolic names for the values are available.

group objects

group objects ehandle label ?filterset? ?filtermode?
g.objects(?filters=?,?mode=?)

This is a cross-referencing command specific to groups. The standard operation of cross-referencing commands and the use of the optional parameters are explained in the object referencing section of this manual.

The difference of this command to the group atoms, group bonds or group groups commands is that this command lists all object classes present in the group. Every listed item is output as a list with two elements - the first being the object class ( atom , bond or group ), the second being the object label or reference. This list is suitable for use in a group create or group add statement.

The command returns the label or reference of the new group.

Example:

group create $ehandle [group objects $ehandle 1]

This command duplicates the group with label 1.

group pis

group pis ehandle label ?filterset? ?filtermode?
g.pis(?filters=?,?mode=?)

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

Examples:

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

group ref

Group.Ref(eref,identifier)

Python only method to get a group reference. See group group command.

group remove

group remove ehandle label objectlist...
g.remove(?object/objectsequence?,...)

Remove group items from a group. The removed objects are not deleted from the ensemble, they simply are no longer a group member. The syntax of the object list is the same as in the group add and group create commands. The groups the objects are removed from also remain in existence.

Removing an object from a group triggers a groupchange property invalidation event and may thus have an influence on the validity of chemical object data.

The command returns the number of removed group elements.

Examples:

group remove $ehandle 1 [group atoms $ehandle 1 hydrogen]

This command removes all hydrogen atoms from group 1.

group rings

group rings ehandle label ?filterset? ?filtermode?
g.rings(?filters=?,?mode=?)

Standard cross-referencing command to obtain the labels or references of the rings the group is associated with. This is explained in more detail in the section about object cross-references. Rings which only partially overlap with the group are included.

Examples:

group rings $ehandle 1
group rings $ehandle 1 [list heterocycle aroring]

The first example returns the labels of all rings the group overlaps with. If the group does not overlap with any ring, an empty list is returned. Only labels of rings in the SSSR or ESSSR set are returned, even if the currently computed ring set is larger. The second example filters the rings - only heteroaromatic rings are reported.

group ringsystems

group ringsystems ehandle label ?filterset? ?filtermode?
g.ringsystems(?filters=?,?mode=?)

Standard cross-referencing command to obtain the labels or references of the ring systems the group is associated with. This is explained in more detail in the section about object cross-references. Ring system which only partially overlap with the selected group are listed.

Examples:

group ringsystems $ehandle 1
group ringsystems $ehandle 1 [list heterocycle aroring]

The first example returns the labels of all ring systems the group is associated with. If the group does not overlap with any ringsystem, an empty list is returned. The second example filters the ring systems - a ring system label is added to the output list only if that ring system contains one or more hetero aromats.

group set

group set ehandle label ?property value?...
g.set(?property,value?,...)
g.set({property:value,...})
g.property = value
g[property] = value

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

The command returns the first data value.

Example:

group set $ehandle 1 G_CONSTRAINT [list “distance” [list 3.0 4.0]]

group show

group show ehandle label propertylist ?filterset? ?parameterdict?
g.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 group get command. The difference between group get and group 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, group get and group show are equivalent.

group sigmas

group sigmas ehandle label ?filterset? ?filtermode?
g.sigmas(?filters=?,?mode=?)

Standard cross-referencing command to obtain the labels or references of the σ systems the group is associated with. This is explained in more detail in the section about object cross-references. An association is assumed if any atoms of the σ system is a group member. Recursive groups are not searched.

Examples:

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

group sqldget

group sqldget ehandle label propertylist ?filterset? ?parameterdict?
g.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 group get command. The differences between group get and group 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.

group sqlget

group sqlget ehandle label propertylist ?filterset? ?parameterdict?
g.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 group get command. The difference between group get and group sqlget is that the SQL command variant formats the data as SQL values rather than for Tcl or Python script processing.

group sqlnew

group sqlnew ehandle label propertylist ?filterset? ?parameterdict?
g.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 group get command. The differences between group get and group 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.

group sqlshow

group sqlshow ehandle label propertylist ?filterset? ?parameterdict?
g.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 group get command. The differences between group get and group 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.

group subcommands

group subcommands
dir(Group)

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

group surfaces

group surfaces ehandle label ?filterset? ?filtermode?
g.surfaces(?filters=?,?mode=?)

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

Example:

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

group xbonds

group xbonds ehandle label ?filterset? ?filtermode?
g.xbonds(?filters=?,?mode=?)

Retrieve the labels or references of bonds which cross from the group atoms to atoms which are not in the group. This corresponds to the MDL SDfile M SBL” field, except when the group type is a data group, or a type not covered by the SDF encoding. This reference command always re-computes these bonds from the group atoms. The original bond set when reading an SGroup SDF is stored in property G_XBONDS or G_BONDS (for data groups).

In other respects, this is a standard cross-referencing command. The usage of the filterset and filtermode parameter is explained in the section about object cross-references.

Example:

set gh [group create $ehandle [list 1 2 3]]
group xbonds $ehandle $gh

gets the bond labels of all crossing bonds.