The reaction Command

The reaction command is the generic command used to manipulate reactions. The syntax of this command follows the standard schema of command/subcommand/majorhandle . Reactions are major objects and thus do not need any minor object labels for identification.

Examples:

reaction get $xhandle X_IDENT

This is the list of currently officially supported subcommands:

reaction add

reaction add xhandle ?ReactionSMILES/SMIRKS/BASE64Blob? ?decodermode?
reaction add xhandle ?ehandle?...
reaction add xhandle ?{ehandle role}?...

Add ensembles to a reaction. The syntax of the various variants to specify ensembles and their reaction roles are the same as in the reaction create command.

Example:

reaction add [reaction create] $reagent_ehandle $product_ehandle

reaction append

reaction append xhandle 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:

reaction append $xhandle X_NAME “_new”

reaction assign

reaction assign xhandle srcprop dstprop

Copy data from one property to another. Both properties must be associated with the same object class. The source property (but currently not the destination property) may be specified as an indexed property subfield. There must be a conversion path between the data types of the two properties or property subfields involved for the operation to succeed. For example, assigning a string property to a numeric property succeeds only if the string data items contain suitable numbers.

The original property data remains valid. The command variant reaction rename directly exchanges the property name without any data duplication or conversion, if that is possible. In any case, the original property data is no longer present after the execution of this command variant.

If the properties are not associated with reactions (prefix X_ ), the operation is performed on all reaction ensembles.

Examples:

reaction assign $xh A_XY A_XY%

This code snippet creates a backup atomic 2D layout coordinates on all reaction ensembles.

reaction rename $xh X_IDENT X_NAME

Reassign the data in property X_IDENT to property X_NAME . If possible, this is done without memory reallocation and decoding/encoding procedures.

reaction cast

reaction cast xhandle dataset/ens/reaction/table ?propertylist?

Transform the reaction into a different object. Depending on the target object class, the result is as follows:

If the optional property list is specified, an attempt is made to compute the listed properties before the cast operation, so that they may become a part of the new object. No error is raised if a computation fails.

The command returns the handle of the new object, or the input object handle in case of mode reaction .

reaction clear

reaction clear xhandle ?role? ?deleteensembles?

Remove and optionally delete ensembles of a reaction. By default, all reaction ensembles are moved out of the reaction, but they are not deleted. If a reaction role is given (possible roles are taken from the enumeration of property E_REACTION_ROLE , the default set is unknown, reagent, product, solvent, catalyst, intermediate, impurity, byproduct, agent and waste ), only those ensembles with the specified role are removed. If the deleteensemble flag is set, targeted ensembles are not simply removed from reaction membership, but destroyed.

The command returns the count of removed or deleted ensembles.

Examples:

reaction clear $xhandle
reaction clear $xhandle solvent 1

The first example removes all ensembles from the reaction, but keeps them in memory, and they can still be accessed via their handles. The second example removes all solvent ensembles from the reaction and destroys them.

reaction copy

reaction copy src_xhandle dst_xhandle

Create a copy of the input reaction in the framework of an existing reaction. The old data of the destination reaction is destroyed, but its handle is reused for the copy. The destination handle can be an empty string. In that case, the reaction is duplicated and a new handle assigned.

This command is useful when references to a reaction handle are potentially stored in unknown locations, and the reaction needs to be updated.

The return value of the command is the handle of destination reaction. It is allowed to copy a reaction onto itself.

reaction create

reaction create ?ReactionSMILES/SMIRKS/RInChI/BASE64Blob/KEGGID/patran? ?decodermode?
reaction create ?ehandle?...
reaction create ?{ehandle role}?...

This command creates a new reaction. Without any parameters, an empty reaction without any ensembles in it is made. The return value is the new reaction handle.

Example:

set xhandle [reaction create]

The first variant for creating a reaction with data is the use of a single-argument line notation. The supported line notations include Reaction SMILES or SMIRKS , RInChI strings, hex-encoded versions thereof, a KEGG reaction identifier in the form RPxxxxx, a Cactvs base64-encoded serialized reaction object string (see reaction pack ), or a base64-encoded compressed file content, such as an MDL RXN file record. For the last variant, the compression algorithm may be raw zlib, gzip or zip and is automatically detected. Additionally, any of those forms may be passed as a data URI. If a data URI is detected, its payload is extracted and used as argument in a second pass. The data for the decoding of KEGG IDs is downloaded from the KEGG site via an http connection and requires that the interpreter is allowed port 80 Internet access.

Similar to the ens create command, it is also possible to prefix the structure encoding, if it is a line notation or an encoding without line breaks, with smiles: smirks: rinchi: or kegg: in order to explicitly name the encoding of these formats.

The only multi-line encoding recognized by this command are Lhasa Patran reaction patterns. They are automatically decoded in a form which makes them suitable for use in lhasa reaction processor objects. Reactions stored in uncompressed files must be read by means of a molfile read command.

Without setting a specific decoder mode in the following optional argument, the data string is decoded in the format-specific default mode (i.e. as standard SMILES strings for the SMILES family) and molecules with a complete hydrogen set are generated if the encoding supports such a distinction.

For Reaction SMILES variants, the explicit decoder modes smarts, strictsmarts, hadd, nohadd, pattern or patran and transform can be requested. In smarts or strictsmarts mode, full SMARTS or SMIRKS encodings are recognized, which are useful for reaction substructure searches or SMIRKS transforms. The difference between smarts and strictsmarts is that the latter enforces aliphaticity checks (see ens create ). No implicit hydrogen is added in that mode. The nohadd mode does not supports SMARTS constructs, but no implicit hydrogens are instantiated either.The hadd mode adds a standard hydrogen set. The transform mode is similar to the smarts mode, but additionally hydrogen atoms encoded explicitly are not instantiated but rather translated into a hydrogen count query specification. This is useful for some classes of SMIRKS transforms. SMILES atom mapping specifications are allowed in all modes. The explicit pattern or patran modes should be used when decoding patran patterns - but then this is already the default for this type of data.

In case the argument is a Reaction SMILES variant or an RInChI string, and an agent in Daylight nomenclature is specified (the middle section between the >> characters), it is assigned the reaction role agent , which is rather unspecific. It may subsequently be changed by setting the E_REACTION_ROLE property of the agent ensemble.

Ensembles which are decoded from the arguments have normal object handles and may be addressed via these just like ensembles which are not part of a reaction.

Examples:

set xhandle [reaction create C=O>Cc1ccccc1>CO]
ens set [reaction ens $xhandle agent] E_REACTION_ROLE solvent
set xhandle [reaction create {[C:1]=[O:2]>>[C:1][O:2]} smarts]
set xhandle [reaction create KEGG:RP09586]

A second reaction create command variant uses a set of ensemble handles as arguments and makes these ensembles members of the newly created reaction. The reaction role of the ensembles is determined by default by their position in the argument list. The first ensemble is the reagent , followed by product, solvent, catalyst, intermediate, impurity, byproduct, agent and waste in that order. It is possible to skip a role by providing an empty string as parameter placeholder. If necessary, ensembles are removed from an existing reaction and transferred to the new one, since an ensemble cannot be a member of more than one reaction at a time. In case the default order-dependent reaction role assignment is not convenient, any argument may be specified as a list of two components instead. In that notation, the first list element is the normal ensemble handle and the second the applicable role designator encoded as a string from above set.

Examples:

set xhandle [reaction create $reagent_ehandle [ens create CO] {} {[Pt]}]

This example creates a reaction from an existing reagent ensemble and then adds a product ensemble and platinum as catalyst . The solvent parameter position is skipped by entering an empty string.

Finally, it is possible to explicitly specify the role by not just providing an ensemble handle as parameter, but a list consisting of an ensemble handle and its reaction role.

Example:

set xhandle [reaction create [list $product_handle product] \ 
	[list [ens create {[Pt]} catalyst]]

reaction dataset

reaction dataset xhandle ?filterlist?

Return the dataset handle of the dataset the reaction is a member of. It the reaction is not member of a dataset, or does not pass all of the optional filters, an empty string is returned.

Example:

reaction dataset $xhandle

reaction defined

reaction defined xhandle property

This command checks whether a property is defined for the reaction. 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 reaction valid command is used for this purpose.

reaction delete

reaction delete all
reaction delete xhandlelist ?xhandlelist?...

Delete reactions and the ensembles which are part of the deleted reactions. The special parameter all may be used to delete all reactions currently registered in the application. Alternatively, any number of lists of reaction handles may be specified for specific reaction deletions.

The command returns the number of deleted reactions.

Example:

reaction delete $xhandle
reaction delete $xhandlelist1 $xhandlelist2

reaction dget

reaction dget xhandle 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 reaction get command. The difference between reaction get and reaction 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, reaction get and reaction dget are equivalent.

reaction dup

reaction dup xhandle ?dataset? ?position?

Duplicate the specified reaction and its ensembles. The return value is the new reaction handle. The duplicated reaction ensembles are also assigned unique handles.

The duplicate reaction is placed into the same dataset as the source, if that one is in a dataset. Specifying an explicitly empty dataset argument places the duplicate outside any dataset, regardless of the dataset membership of the source reaction.

If the duplicate is moved to a dataset, it is appended to the dataset end by default. This happens also if the position parameter is explicitly specified as end or an empty string. Otherwise, the reaction is inserted at the given position, starting with 0. If the requested position is larger than the current size of the dataset, the reaction is appended.

Example:

set xhdup [reaction dup $xhandle]

reaction ens

reaction ens xhandle ?filterlist?

Return a list of the handles of the ensembles which are a part of the reaction. Optionally, these ensembles may be filtered by a simple filter list.

Example:

reaction ens $xhandle metal

Find all ensembles in the reaction which contain one or more metal atoms.

reaction exists

reaction exists xhandle ?filterlist?

Check whether a reaction handle is valid. The command returns 0 or 1. Optionally, the reaction may be filtered by a standard filter list, and if it does not pass the filter, it is reported as not valid. If filters in the filter list operate on ensembles, it is sufficient if a single ensemble of the reaction passes the filter.

Example:

reaction exists $xhandle solvent

Check whether the reaction with the handle in variable $xhandle exists and, if it exists, whether it contains a solvent ensemble.

reaction expand

reaction expand xhandle ?allowambigous? ?noimplicith?

This command expands all superatoms in the ensembles of the reaction. The mechanisms for the expansion of superatoms are described in detail for the atom expand command. This command is functionally equivalent, working on all atoms in all of the reaction ensembles instead a single atom.

Example:

reaction expand $xhandle

The command returns the total number of successfully expanded atoms in all reaction ensembles.

reaction expr

reaction expr xhandle expression

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

reaction filter

reaction filter xhandle filterlist

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

Example:

reaction filter [reaction create {C=C>[Pt]>CC}] platinum

checks whether the reaction involves a platinum atom in any role.1 If the filter operates on ensembles or minor objects, it is sufficient to have a single ensemble or ensemble minor object pass the filter condition.

reaction forget

reaction forget xhandle ?minor_obj_class?

This command is essentially the same as the ens forget command. It is applied to all ensembles in the reaction.

reaction get

reaction get xhandle 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:

reaction get $xhandle {X_IDENT X_NAME}

yields the ID and name of the reaction as a list. If the information is not available, an attempt is made to compute it. If the computation fails, an error results.

reaction get $xhandle {E_FORMULA E_WEIGHT}

reports the formula and molecular weight of all reaction ensembles. The result is delivered as a nested list. The first list contains the formulae, the second list contains the weights.

Currently, it is not possible to use filters with this command (and the other retrieval command variants) which are not operating directly on the reaction object, but on objects lower in the hierarchy such as ensembles or atoms.

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

Instead of using a property name or a reaction attribute, it is also possible to use any valid value of property E_REACTION_ROLE to directly access specific ensembles of the reaction. The allowed values are dynamically read from the property definition and thus customizable.

Example:

set ehp [reaction get $xh product]
set ehp [reaction ens $xh product]

These commands yield the same results, but the first directly tests the values of E_REACTION_ROLE of the reaction ensembles, while the second one uses the predefined product filter.

Variants of the reaction get command are reaction new, reaction dget, reaction jget, reaction jnew, reaction jshow, reaction nget, reaction show, reaction sqldget, reaction sqlget, reaction sqlnew, and reaction sqlshow .

In addition to property data and reaction role selectors, a reaction object possesses a few attributes, which can be retrieved with the get command (but not by its related sister subcommands like dget, sqlget, etc.). Some of them are also modifiable via reaction set. These attributes are:

reaction getparam

reaction getparam xhandle property ?key? ?default?

Retrieve a named computation parameter from valid property data. If the key is not present in the parameter list, an empty string is returned. If the default argument is supplied, that value is returned in case the key is not found.

If the key parameter is omitted, a complete set of the parameters used for computation of the property value is returned in key/value format.

This command does not attempt to compute property data. If the specified property is not present, an error results.

Example:

reaction getparam $xhandle X_GIF format

returns the actual format of the image, which could be GIF , PNG , or various bitmap formats.

reaction hadd

reaction hadd xhandle ?filterset? ?flags? ?changeset?

Add a standard set of hydrogens to the ensembles of the reaction. If the filterset parameter is specified, only those atoms which pass the filter set are processed.

Additional operation flags may be activated by setting the flags parameter to a list of flag names, or a numerical value representing the bit-ored values of the selected flags. By default, the flag set is empty, corresponding to the use of an empty string or none as parameter value. These flags are currently supported:

Adding hydrogens with this command is less destructive to the property data set of the reaction ensembles than adding them with individual atom create/bond create commands, except in case the protonate flag is set, because many properties are designed to be indifferent to explicit hydrogen status changes, but are invalidated if the structure is changed in other ways.

If the effects of the hydrogen addition step to the validity of the property data set should not be handled according to this standard procedure, it is possible to explicitly generate additional property invalidation events by specifying an event list as the optional last parameter, for example a list of atom and bond to trigger both the atom change and bond change events.

The command returns the number of hydrogens which were added to all reaction ensembles.

Example:

set xhandle [reaction create {[C]=[C]>>[C]-[C]}]
reaction hadd $xhandle

adds a total of ten hydrogens to the two reaction ensembles, transforming them into hydrogen-complete ethene and ethane.

reaction hdup

reaction hdup xhandle ?dataset? ?position?

This command performs the same operation as the reaction dup command, but additionally adds a standard set of hydrogens to all ensembles of the duplicated reaction.

reaction hstrip

reaction hstrip ehandle ?flags? ?changeset?

This command removes hydrogens from all ensembles in the reactions. By default, all hydrogen atoms on the ensemble are removed.

The flags parameter can be used to make the operation more selective. It may be a list of the following flags:

If the flags parameter is an empty string, or none , it is ignored. The default flag value is wedgetransfer - but the default value is overridden if any flags are set!

If the changeset parameter is used, all property change events listed in the parameter are triggered.

Hydrogen stripping is not as disruptive to the data content of the reaction ensembles as normal atom deletion, except in case the deprotonate flag is set. The system assumes that this operation is done as part of some file output or visualization preparation. However, if any new data is computed after stripping, the computation functions see the stripped structure, and proceed to work on that reduced structure without knowledge that there are implicit hydrogens.

The command returns the total number of hydrogens stripped from all reaction ensembles.

Example:

reaction hstrip $xhandle [list keeporiginal wedgetransfer]

reaction hydrogenate

reaction hydrogenate xhandle ?filterset? ?changeset?

Reduce all bonds in the reaction to single bonds, except those excluded by the filter set.

If a change set is supplied, its interpretation is the same as in reaction hadd.

The command returns the number of added hydrogens.

reaction index

reaction index xhandle

Get the position of the reaction in the object list of its dataset. If the reaction is not member of a dataset, -1 is returned.

reaction jget

reaction jget xhandle propertylist ?filterset? ?parameterlist?

This is a variant of reaction get which returns the result data as a JSON formatted string instead of Tcl interpreter objects. The command is usable only for property data, not attribute retrieval.

reaction jnew

reaction jnew xhandle propertylist ?filterset? ?parameterlist?

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

reaction jshow

reaction jshow xhandle propertylist ?filterset? ?parameterlist?

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

reaction ldup

reaction ldup ?xhandlelist?...

Duplicate all reactions in the handle list(s) in default mode.

The return value is a single list (even if multiple source lists are used) of the duplicated reaction handles. If an argument list element is an empty string, it indicates a missing object, and the output list also receives an empty string element at its position, without raising an error.

reaction lhdup

reaction lhdup ?xhandlelist?...

Duplicate all reaction in the handle list(s) in default mode, and add hydrogens.

The return value is a single list (even if multiple source lists are used) of the duplicated reaction handles. If an argument list element is an empty string, it indicates a missing object, and the output list also receives an empty string element at its position, without raising an error.

reaction list

reaction list ?filterlist?

This command returns a list of the reaction handles currently registered in the application. This list may optionally be filtered by a standard filter list. If the filter operates on the reaction ensembles and not on the reaction object, it is sufficient if a single reaction ensemble passes the filter.

Example:

reaction list solvent

lists the handles of all reactions in the application which contain a solvent ensemble.

reaction lock

reaction lock xhandle propertylist/reaction/all ?compute?

Lock property data of the reaction, meaning that it is no longer subject to the standard data consistency manager control. The data consistency manager deletes specific property data if anything is done to the reaction which would invalidate the information. Blocking the consistency manager can be useful when building reactions from components in a script. Property data remains locked until is it explicitly unlocked.

The property data to lock can be selected by providing a list of the following identifiers:

The lock can be released by a reaction unlock command.

Example:

set xhandle [reaction create {C=C>[Pt]>CC}]
reaction lock $xhandle X_GIF 1
reaction clear $xhandle agent
reaction unlock $xhandle X_GIF

In this example, first a reaction depiction in property data X_GIF is generated and locked. After that, the reaction and reaction ensembles can be manipulated without losing the image data. The agent is removed in the next step - but the X_GIF image which shows the catalyst and which normally would have been deleted when the agent is removed is kept. Finally, the image property data is put back under the standard control of the data consistency manager.

reaction max

reaction max xhandle propertylist ?filterset?

Get the maximum values of the properties named in the propertylist parameter. The return value of the command is a list of the maximum property values. While it is possible to work with reaction properties, this is pointless since there is only a single instance of a reaction property per reaction. Usually, ensemble or ensemble minor object properties are retrieved. The objects whose property values are used for the determination of the maximum values may optionally be filtered by a standard filter set.

Example:

reaction max $xhandle E_WEIGHT {1 reagent product}

computes the maximum molecular weight from the reagent and product ensembles, ignoring other reaction ensembles such as solvents or catalysts.

reaction metadata

reaction metadata xhandle property field ?value?

Obtain property metadata information, or set it. The handling of property metadata is explained in more detail in its own introductory section. The related commands reaction setparam and reaction getparam can be used for convenient manipulation of specific keys in the computation parameter field. Metadata can only be read from or set on valid property data.

Examples:

array set gifparams [reaction metadata $xhandle X_GIF parameters]
reaction metadata $xhandle X_CONDITIONS comment “Check with legal dept whether oxidation in molten Pu metal requires regulatory approval”

The first line retrieves the computation parameters of the property X_GIF as keyword/value pairs. These are read into the array variable gifparams , and may subsequently be accessed as $gifparams(format) , $gifparams(height) , etc. The second example shows how to attach a comment to a property value.

reaction min

reaction min xhandle propertylist ?filterset?

Get the minimum values of the properties named in the propertylist parameter. The return value of the command is a list of the minimum property values. While it is possible to work with reaction properties, this is pointless since there is only a single instance of a reaction property per reaction. Usually, ensemble or ensemble minor object properties are retrieved. The objects whose property values are used for the determination of the minimum values may optionally be filtered by a standard filter set.

Example:

reaction min $xhandle E_WEIGHT {1 reagent product}

computes the minimum molecular weight from the reagent and product ensembles, ignoring other reaction ensembles such as solvents or catalysts.

reaction move

reaction move xhandle ?datasethandle|remotehandle? ?position?

Make a reaction a member of a dataset, or remove it from a dataset. If the dataset handle parameter is omitted, or an empty string, the reaction is removed from its current dataset. If it was not a dataset member, this command does nothing. The dataset handle may be the name of a remote dataset for moving reactions over a network connection.

If a dataset handle is specified, the reaction is added to the dataset, and removed from any dataset it was member of before the execution of the command. By default the reaction is added to the end of the dataset object list, but he final optional parameter allows the specification of an object list index. The first position is index zero. If the parameter value end is used, or the index is bigger than the current number of dataset objects minus one, the reaction is appended as by the default. It is legal to use this command for moving reactions within the same dataset.

Another special position value is random . This value moves to the reaction to a random position in the dataset. Using this mode with remote datasets is currently not supported.

The dataset handle cannot be a transient dataset.

The return value of the command is the dataset membership of the reaction prior to the move. It is either a dataset handle, or an empty string if it was not member of a dataset.

Examples:

reaction move $xhandle $dhandle 0
reaction move $xhandle

In the first sample line, the reaction is inserted as the first element in a dataset. The second line reverts this operation and removes the reaction from the dataset.

This command can be used with a remote dataset descriptor. In that case, the reaction is packed into a serialized object representation, transmitted over the network and restored as member of the remote dataset at the specified position. The local reaction is deleted if the transfer succeeds.

reaction mutex

reaction mutex xhandle mode

Manipulate the object mutex. During the execution of a script command, the mutex of the major object(s) associated with the command are automatically locked and unlocked, so that the operation of the command is thread-safe. This applies to builds that support multi-threading, either by allowing multiple parallel script interpreters in separate threads or by supporting helper threads for the acceleration of command execution or background information processing.

This command locks major objects for a period of time that exceeds a single command. A lock on the object can only be released from the same interpreter thread that set the lock. Any other threaded interpreters, or auxiliary threads, block until a mutex release command has been executed when accessing a locked command object. This command supports the following modes:

There is no trylock command variant because the command already needs to be able to acquire a transient object mutex lock for its execution.

reaction need

reaction need xhandle propertylist ?mode?

Standard command for the computation of property data, without immediate retrieval of results. This command is explained in more detail in the section about retrieving property data.

The return value is the reaction handle.

Example:

reaction need $xhandle E_WEIGHT recalc

reaction new

reaction new xhandle 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 reaction get command. The difference between reaction get and reaction new is that the latter forces the re-computation of the property data, regardless whether it is present and valid, or not.

reaction nget

reaction nget xhandle 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 reaction get command. The difference between reaction get and reaction nget is that the latter always returns numeric data, even if symbolic names for the values are available.

reaction nitrostyle

reaction nitrostyle xhandle style

Change the internal encoding of nitro groups and similar functional groups in the ensembles of the reaction. Possible values for the style parameter are:

The command returns the reaction handle.

reaction pack

reaction pack xhandle ?maxsize? ?request_propertylist? ?suppress_propertylist?

Pack the reaction object into a base64-encoded compressed serialized object string. This string does not contain any non-printable characters and is a full dump of the internal state of the object, omitting only property data that was declared to be so easily re-computed that a dump is not worthwhile. The reaction ensembles and their property data are part of the dump. Further object relationships, such as datasets the reaction or reaction ensembles might be a member in, or tables the reaction or its ensembles are associated with are not saved.

The maximum size of the object string (default -1, meaning unlimited size) can be configured by the optional maxsize parameter. The size is specified in bytes. If the pack string would be longer than the maximum size, an error results.

The other two optional parameters allow to request a specific property set to be part of the package, even if it normally would not be included, and to explicitly omit properties from the dump. No property computation is performed, and suppressed properties are not purged from the reaction.

Reactions can be restored from a packed object string by the reaction unpack or reaction create commands.

The reaction object and its ensembles remain in existence after using this command.

Example:

set dbstring [reaction pack [reaction create CC=O>>CCO]]

reaction properties

reaction properties xhandle ?pattern? ?intersectmode?

Get a list of valid properties of the reaction proper and the reaction ensembles. By default, reaction properties (prefix X_ ), dataset properties (prefix D_ ), as well as the properties of the ensembles in the reaction (prefix E_ ) and the properties of their minor objects (atoms, bonds, etc.) are listed.

Property subsets may be selected by a non-empty filter pattern. In case of reaction ensemble or minor ensemble object properties which are not present in all reaction ensembles, the default intersect mode is union , meaning that all properties are reported for which at least one instance exists. The alternative mode intersect only lists those ensemble properties which are present in all reaction ensembles.

This command may also be invoked as reaction props .

Example:

reaction properties $xhandle X_*
reaction props $xhandle E_* intersect

The first example returns a list of the currently valid reaction properties. The second example lists all reaction properties which are present in all reaction ensembles.

reaction purge

reaction purge xhandle propertylist/reaction/specialname ?emptyonly?

Delete property data from the reaction. The properties may be reaction properties (prefix X_ ), dataset properties (prefix D_ ) or properties of the reaction ensembles, such as ensemble or atom properties. If a property marked for deletion is not present on an object, it is silently ignored. If the reaction is not a dataset member, a request for the deletion of dataset properties is also ignored.

If the object class name reaction is used instead of a specific property name, all reaction property data ( X_ prefix) is deleted from the reaction.

If another object class name, such as ens or atom , is used instead of a property name, all properties of that class set on the reaction ensembles are deleted, if they are not locked, or filtered out by the optional empty-only flag.

Besides normal property and class names, a few convenient special names for common property deletion tasks on the ensembles of the reaction are defined and can be used as a replacement for the property list. These include:

The optional boolean flag emptyonly can be used to restrict the deletion to those properties where all the values for a property associated with a major object (such as on all atoms in an ensemble for atom properties, or just the single ensemble property value for ensemble properties) are set to the default property value.

Examples:

reaction purge $xhandle X_IDENT
reaction purge $xhandle E_IDENT 1

The first example deletes the property data X_IDENT for the selected reaction if it is present. The second example deletes property E_IDENT from all ensembles in the reaction if the property value on that ensemble is equal to the default value for E_IDENT .

reaction remove

reaction remove xhandle ?enslist?...

Remove the ensembles in the ensemble lists from the reaction. If an ensemble from the list is not part of the reaction, it is ignored. Removed ensembles are not destroyed and remain accessible via their handles.

The command returns the number of removed ensembles.

Examples:

reaction remove $xhandle $ehandle
reaction remove $xhandle [reaction ens $xhandle]

The first example removes the ensemble from the reaction if it is part of the reaction. The second example removes all ensembles from the reaction - this is essentially the same as reaction clear .

reaction rename

reaction rename xhandle srcproperty dstproperty

This is a variant of the reaction assign command. Please refer the command description in that paragraph.

reaction reorder

reaction reorder xhandle 

Sort the ensembles in the reaction into standard sequence ( reagent/product/solvent/catalyst/ intermediate/impurity/byproduct/agent/waste ). In addition, empty reagent and product (but not solvent , etc.) ensembles are automatically created in the reaction in case they are not present.

The command returns the ensemble handle.

reaction reverse

reaction reverse xhandle

Reverse the direction of the reaction. Only the roles of ensembles with reagent and product roles are changed.

The command returns the original reaction handle.

reaction scan

reaction scan xhandle expression ?mode? ?parameters?

Perform a query on the reaction object. The syntax of the query expression and the optional selection list is the same as that of the dataset scan command with a transient dataset consisting of the current reaction only. For more details, please refer to the paragraphs on dataset scan and molfile scan .

The return value depends on the mode. The default query mode, different from the default in dataset scan , is exists .

In case the query contains ensemble structure match conditions which are not part of a reaction query, or there are ensemble data retrieval specifications, these are tested on and applied to the reagent ensemble of the reaction. Reactions which do not possess a reagent ensemble (half reactions, etc.) are ignored.

reaction set

reaction set xhandle property value ?property value?...

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

Examples:

reaction set $xhandle X_NAME “New multi-component reaction”
reaction set $xhandle E_IDENT “X-124”

The first line is a simple set operation for a reaction property. The second line shows how to set properties of multiple ensembles in one step. The same property value is assigned to all ensembles.

reaction setparam

reaction setparam xhandle property key value ?key value?...

Set or update a property computation parameter in the metadata parameter list of a valid property. This command is described in the section about retrieving property data. The current settings of the computation parameters in the property definition are not changed.

Example:

reaction setparam $xhandle X_GIF comment “Top Secret”

reaction show

reaction show xhandle 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 reaction get command. The difference between reaction get and reaction 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, reaction get and reaction show are equivalent.

reaction sort

reaction sort xhandle ?sort_property? ?relabel? ?duplicate? ?datasethandle? ?position?

This command applies the ens sort command to all reaction ensembles. Please refer to the descriptors of the ens sort command for an explanation of the parameters.

The command returns the reaction handle.

reaction split

reaction split xhandle ?dropsize? ?splitproperty?

Split the molecules of the ensembles in the reaction into individual ensembles. The return value is a list of all ensemble handles in the reaction after the operation, similar to the output of a reaction ens command. The initial reaction ensembles are modified, and their old handles may be reused as one of the new single-molecule ensemble handles. If an input ensemble contains only a single molecule, and that molecule passes the optional size filter, the command is a no-op for that ensemble. All result ensembles remain members of the reaction in their old reaction role.

The optional dropsize parameter is a minimum for the number of heavy atoms (property M_HEAVY_ATOM_COUNT ) in any of the molecules. If this is not an empty string, molecules which have less atoms than the minimum are not duplicated. If all molecules in a reaction ensemble are smaller than the required size, the ensemble is destroyed.

The optional split property argument can be used to split an ensemble on values of a molecule property, which needs to be either already set or computable, instead of simply separating fragments on connectivity. All molecules in an input ensemble which have a common value of this property are put into a joint result ensemble, and each distinct property value starts a new result ensemble. Molecules with a common property value do not need to be present in the input ensemble in a consecutive sequence, nor are there any special requirements for the data type or value range of the split property, as long as the data type has a comparison function. If the values of the split property are distinct over all molecules in an input ensemble, the outcome of command is indistinguishable from running it without any split property.

Comparison of property values is performed separately within every reaction ensemble, not across the complete ensemble set in the reaction.

reaction sqldget

reaction sqldget xhandle 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 reaction get command. The differences between reaction get and reaction 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.

reaction sqlget

reaction sqlget xhandle 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 reaction get command. The difference between r eaction get and reaction sqlget is that the SQL command variant formats the data as SQL values rather than for Tcl script processing.

reaction sqlnew

reaction sqlnew xhandle 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 reaction get command. The differences between reaction get and reaction 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.

reaction sqlshow

reaction sqlshow xhandle 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 reaction get command. The differences between reaction get and reaction 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.

reaction subcommands

reaction subcommands

Lists all subcommands of the reaction command. Note that this command does not require a reaction handle.

reaction swapin

reaction swapin xhandle

Swap a reaction from the disk store fully back to memory, and disable further automatic loading and shelving. If the reaction was not swapped out, the command does nothing.

The command returns the reaction handle.

reaction swapout

reaction swapout xhandle

Release most of the reaction data from memory and store it in a temporary disk store. The reaction handle remains valid. As soon as it is used in a command again after this command has been executed, the swapped reaction data is automatically reloaded from file, and then stored again when the object lock is released. To disable the automatic swapping of a reaction, use the reaction swapin command.

This command is intended to be used in cases where a large number of reactions must be kept in memory. Its use is not generally encouraged - it is only useful in case the programmer knows about access patterns. In other cases, the standard virtual memory mechanism of the operating system might yield better performance results.

The reactions are stored as binary blobs in a key/value store in a process-specific swap directory cactvs%d , ( %d is replaced by the process ID) which is created automatically in the standard temporary directory. When a reaction is deleted, its swap record is also removed, if one was created during the lifetime of the reaction. When a Cactvs application program exits, the swap store as well as the swap directory are automatically deleted, even without explicit deletion of the last set of reactions in memory. In case of program crashes, the swap directory and its contents may however survive. If reaction swapping is used with unstable applications, the temporary directory should be checked from time to time.

The command returns the reaction handle.

Example:

rection swapout $xhandle

reaction tables

reaction tables ehandle ?filterlist?

Return a list of the handles of all table objects the reaction is associated with. Optionally, the table set may be filtered by a simple filter list. If the reaction is not related to any table, or none of these tables passes the filter list, an empty string is returned.

This command is only available if the toolkit was compiled with table support.

Example:
reaction tables $xhandle

reaction taint

reaction taint xhandle propertylist/changeset ?purge?

Trigger a property data tainting event which acts on the reaction data, and the data of all ensembles in the reaction. If the reaction is a member of a dataset, or its ensembles are, the dataset and its objects are not tainted.

The command arguments are the same as for the ens taint command and explained there.

reaction transfer

reaction transfer xhandle propertylist ?target_xhandle?

Copy property data from one reaction to another, without going through an intermediate scripting language object representation, or dissociate property data from the reaction. If a property in the argument property list is not already valid on the source reaction, an attempt is made to compute it.

If a target object is specified, and a property is not a reaction object property, the operation is implicitly performed on pairs of reaction ensembles with the same reaction role (property E_REACTION_ROLE ) as if a ens transfer command were issued. In this command mode, the return value is the handle of the target reaction. The source and target reactions cannot be the same object.

If no target object is specified, the visible effect of the command is the same as a simple reaction get , i.e. the result is the property data value or value list. The property data is then deleted from the source object. In case the data type of the deleted property was a major object (i.e. an ensemble, reaction, table, dataset or network), it is only unlinked from the source object, but not destroyed. This means that the object handles returned by the command can henceforth the used as independent objects. They can be deleted by a normal object deletion command, and are no longer managed by the source object.

Examples:

reaction transfer $xh X_IDENT $xh2
reaction transfer $xh A_MAPPING $xh2

The first example is a simple data copy. The second example transfers atom property A_MAPPING between the reagent and product ensembles of the reaction, and any other reaction ensemble where the property is valid, and a pair of ensembles with the same reaction role can be found. The order of the atoms in an ensemble pair is not required to be identical - property A_LABEL is used to identify corresponding atoms.

reaction trim

reaction trim xhandle ?propertylist?

Reduce the information content of a reaction to a standard minimum set and discard any additional information. This process minimizes the storage requirements of the reaction. The properties of the minimum set are computed if required. The retained property set is designed to support a faithful representation of the connectivity of the reaction ensembles including bond and atom labels and types as well as formal charges, stereochemistry, isotopes and atom mapping information, but not of any 2D or 3D coordinates or auxiliary additional attributes of atoms, bonds or other chemical objects or the reaction object proper.

The optional fourth argument is a list of properties which should be retained in addition to the standard set. If any of these are not present on the reaction (or its ensembles) that is to be trimmed, they are silently ignored and no attempt is made to compute them. Specifying properties of the standard retention set in this list is allowed but has no additional effect.

The return value of the command is a list of the remaining properties of the reaction and the reaction ensembles. The properties of the latter are reported as the union of the properties of the individual reaction ensembles (see reaction props command).

Example:

reaction trim $xhandle {X_SMILES E_NAME X_NAME}

reaction unlock

reaction unlock xhandle propertylist/reaction/all

Unlock property data for the reaction, meaning that they are again under the control of the standard data consistency manager.

The property data to unlock can be selected by providing a list of the following identifiers:

Property data locks are obtained by the reaction lock command.

Example:

set xhandle [reaction create {C=C>[Pt]>CC}]
reaction lock $xhandle X_GIF 1
reaction clear $xhandle agent
reaction unlock $xhandle X_GIF

In this example, first a reaction depiction in property data X_GIF is generated and locked. After that, the reaction and reaction ensembles can be manipulated without losing the image data. The agent is removed in the next step - but the X_GIF image which shows the catalyst and which normally would have been deleted when the agent is removed is kept. Finally, the image property data is put back under the standard control of the data consistency manager.

reaction unpack

reaction unpack packstring

Unpack a base64-encoded serialized object string which was created by a reaction pack command. The return value of this function is the handle of the newly created reaction object, which is an exact duplicate of the packed original reaction.

Reactions may also be unpacked by a reaction create command.

Example:

set packdata [reaction pack [reaction create C=O>>CO]]

set xhandle [reaction unpack $packdata]

reaction valid

reaction valid xhandle propertylist

Returns a list of boolean values indicating whether values for the named properties are currently set for the reaction. No attempt at computation is made.

Example:

reaction valid $xhandle X_IDENT

reports whether the reaction has a standard ID (has a valid X_IDENT property) or not.

reaction has is an alias to this command.

reaction verify

reaction verify xhandle property

Verify the values of the specified property on the reaction. The property data must be valid, and a reaction property. If the data can be found, it is checked against all constraints defined for the property, and, if such a function has been defined, is tested with the value verification function of the property.

If all tests are passed, the return value is 1, 0 if the data could be found but fails the tests, and an error condition otherwise.

reaction weed

reaction weed xhandle keywords

This command performs standard clean-up operations on all ensembles in the reaction. The supported operations are described in more detail in the section on the equivalent ens weed command.

The return value of this command is the reaction handle.


1. A filter testing for the presence of any element is automatically created when an element name is used as a filter name. Element filters except for the most common ones ( carbon , etc.) do not show up in the filter list before they are instantiated.