dt_mer_superselect

Daylight v4.9
Release Date: 1 February 2008

Name

dt_mer_superselect - initiate a superstructure search

Generic Prototype

dt_mer_superselect(dt_Handle, dt_Handle, dt_Integer, dt_Integer, dt_Integer,
dt_Integer, dt_String) => dt_Integer

C Prototype

#include "dt_merlin.h"

dt_Integer dt_mer_superselect(dt_Handle hitlist, dt_Handle column, dt_Integer searchtype, dt_Integer action, dt_Integer find_next, dt_Integer * status, dt_Integer smilen, dt_String smiles)

FORTRAN Prototype

include 'dt_f_merlin.inc'

integer*4 dt_f_mer_superselect(hitlist, column, searchtype, action, find_next, status, smiles)

integer*4 hitlist
integer*4 column
integer*4 searchtype
integer*4 action
integer*4 find_next
integer*4 status
character*() smiles

Description

Begins a superstructure search task on the server.

The hitlist 'hitlist' specifies where the resulting hits will be placed and, depending on the value of 'action', may specify the subset of the database to be searched.

The 'column' specifies the data to be searched.

The 'searchtype' specifies the type of superstructure search to be performed. Valid values are:

DX_SUPER_SMILES

The parameter 'smiles' is interpreted as a SMILES. One can specify substructures with exactly specified atoms and bonds (only implicit hydrogens may change for the match).

DX_SUPER_SMARTS

The parameter 'smiles' is interpreted as a SMARTS. Atom and bond expresisons, and recursive SMARTS may be used.

DX_SUPER_SMILESPART

The parameter 'smiles' is interpreted as for the DX_SUPER_SMILES search. Component fingerprints, if available, will be used for screening. The query is searched as if there are parentheses around the entire query; that is, all atoms in the query must be in the same disconnected part of molecules.

DX_SUPER_SMARTSPART

The parameter 'smiles' is interpreted as for the DX_SUPER_SMARTS search. Component fingerprints, if available, will be used for screening. The query is searched as if there are SMARTS parentheses around the entire query; that is, all atoms in the query must be in the same disconnected part of molecules.

The 'action' specifies how the results of the search are to be combined with the original hitlist, as follows:

DX_ACTION_NEW_LIST

The original hitlist is discarded. The entire pool is searched. All rows which meet the criteria are included in the resulting hitlist.

DX_ACTION_ADD_HITS

All rows not on the original list are searched and hits are added to the current list.

DX_ACTION_ADD_NONHITS

All rows not on the original list are searched and non-hits are added to the current list.

DX_ACTION_DEL_HITS

The original hitlist is searched and hits are removed from the hitlist.

DX_ACTION_DEL_NONHITS

The original hitlist is searched and non-hits are removed from the hitlist.

DX_ACTION_NEXT_HIT

The original hitlist is searched and as soon as a hit is found, its hitlist index is returned. The hitlist is unchanged. Data in derived columns is modified, even though the hitlist is unchanged. The parameter find_next indicates where the position in the hitlist where the search is to begin. The first row examined is 'find_next' + 1.

DX_ACTION_NEXT_NONHIT

Like DX_ACTION_NEXT_HIT, except finds the next row which does not match the search criteria.

The parameter 'find_next' specifies where in the hitlist the search is to begin when the action is either DX_ACTION_NEXT_HIT or DX_ACTION_NEXT_NONHIT. A value of -1 indicates that the search should begin at the beginning of the hitlist. To continue a search from a previously-found hit, specify that hit's index (the value returned by the previous call to the search).

The superstructure search uses the graph represented by the given 'smiles' string and searches the database for molecules or reactions for which the given graph is a subgraph. When given a SMILES string, superstructure searching uses the fingerprint datatype to screen to quickly eliminate rows from consideration; if some or all fingerprints are missing, the search may be considerably slowed. When given a SMARTS string, fingerprints will be used for the 'fixed' portion of the SMARTS query, which usually speeds up the SMARTS search speed considerably.

Return Value

The status of the search task is returned in 'status' (see dt_continue(3) for descriptions). If the hitlist is short enough that time-slicing is not required, the value of 'status' will be DX_STATUS_DONE. Otherwise, the status will be DX_STATUS_IN_PROGRESS and dt_continue(3) will be required to finish the task.