This class represents OESubSearch.
The OESubSearch class performs substructure searches, also known as subgraph isomorphism determination, on molecular graphs. In a molecular graph, atoms are considered nodes and bonds are edges. The OESubSearch class is capable of performing both colored and uncolored graph comparison. The ‘color’ properties of a query graph are stored as expression trees associated with atoms and bonds of a query molecule.
It is a good practice to call the OEPrepareSearch function before calling any of the following methods:
If there is any atom or bond property that is not perceived but it is necessary to successfully execute the substructure search, then the above methods throw a warning. These warnings can be suppressed by calling the OEPrepareSearch function.
OESubSearch(const OESubSearch &rhs)
OESubSearch(const OEQMolBase &)
Constructs an OESubSearch object using a query molecule (OEQMolBase) Query molecules must have atom and bond expressions (see OEQMolBase.BuildExpressions) built for the entire molecule before being passed to this constructor. Failure to do so will result in the OESubSearch object being constructed as uninitialized.
OESubSearch(const OEMolBase &mol, unsigned int aexpr, unsigned int bexpr)
Constructs an OESubSearch object using a molecule and expression options. The atom and bond expression options passed as the second and third arguments to the method are defined in the OEExprOpts namespace. The expression options are used to convert the atom and bond data into expression trees which are used during the subgraph search.
OESubSearch(const char *smarts, bool allowReorderAtoms=true)
Constructs an OESubSearch object using a SMARTS pattern that is passed as the first argument to the constructor. The second argument of the method determines the traversal order used in subgraph isomorphism detection. This argument is currently not used, therefore the traversal order always reflects the atom and bond ordering of the passed SMARTS pattern.
OESubSearch &operator=(const OESubSearch &rhs)
operator bool() const
Tests whether initialization of an OESubSearch object is successful . If initialization was attempted with an invalid SMARTS pattern or query molecule then this method will return false. If initialization was completed successfully this method will return true. An OESubSearch object is considered to be uninitialized when constructed with the default constructor.
bool AddConstraint(const OEMatchPair<OEAtomBase> &) bool AddConstraint(const OEMatchPair<OEBondBase> &)
The search space of a subgraph isomorphism determination can be restricted by constraining pairs of nodes or edges (atoms or bonds) to be mapped onto one another in all valid subgraph solutions. Failure to satisfy atom or bond pairwise constraints will prevent any subgraph solutions from being identified by any of the match methods in OESubSearch. Both OESubSearch.AddConstraint methods return true if a constraint is added successfully. If the pattern atom or bond in the OEMatchPair does not exist as part of the query molecule created in the initialization of the OESubSearch object then OESubSearch.AddConstraint will return false. Multiple calls OESubSearch.AddConstraint using the same pattern atom or bond will cause previously stored constraints to be overwritten as constraints are mutually exclusive. It is impossible to satisfy multiple simultaneous constraints for a single pattern atom or bond, hence the exclusivity.
bool AtomMatch(const OEAtomBase *) const
Searches for a single valid subgraph isomorphism starting with the passed target atom mapped to the first pattern atom with which the OESubSearch was initialized. If a valid subgraph is identified the method will return true. This method is the effective combination of sequential calls to OESubSearch.AddConstraint followed by OESubSearch.SingleMatch.
Eliminates all prior match constraints set with the OESubSearch.AddConstraint method.
unsigned int GetMaxMatches() const
Returns the maximum number of subgraph isomorphism solutions that the OESubSearch object will identify before terminating the search. A value of zero indicates that no arbitrary limit has been set on the total number of subgraph isomorphism solutions to be identified. By default, the maximum number of matches is set to 1024.
const OEQMolBase &GetPattern() const
Returns the read-only reference to the query molecule contained in an OESubSearch object. Const OEQMolBase methods can be used to interrogate the returned OEQMolBase reference. If the OESubSearch object has not been initialized, a reference to an empty molecule will be returned.
bool Init(const OEQMolBase &)
(Re)initializes an OESubSearch object with a query molecule (OEQMolBase) reference. The method will return true if initialization completes successfully, and false upon failure. Prior state information is cleared before initialization, and is lost even if the method fails to initialize properly.
bool Init(const char *smarts, bool allowReorderAtoms=false)
(Re)initializes an OESubSearch object with a SMARTS pattern, which is parsed to create a query molecule available for substructure search. The method will return true if initialization completes successfully, and false upon failure. Prior state information is cleared before initialization, and is lost even if the method fails to initialize properly. The second argument of the method determines the traversal order used in subgraph isomorphism detection. This argument is currently not used, therefore the traversal order always reflects the atom and bond ordering of the passed SMARTS pattern.
bool Init(const OEMolBase &mol, unsigned int atomexpr, unsigned int bondexpr)
Expression options are used to convert the atom and bond data into expression trees which are used during the substructure search to map atoms and bonds. The method will return true if initialization completes successfully, and false upon failure.
Prior state information is cleared before initialization, and is lost even if the method fails to initialize properly.
OESystem::OEIterBase<OEMatchBase> *Match(const OEMolBase &, bool uniquematch=false) const
Performs search in order to identify subgraphs of OEMolBase which are isomorphic to the graph with which an OESubSearch object was initialized. It returns an iterator pointer (OEIterBase) over graph matches (OEMatchBase), and should be assigned to an OEIter < OEMatchBase > in order to prevent memory leaks.
By default all possible subgraphs up to and including the maximum number of matches are returned by these methods. If the ‘uniquematch’ argument passed to the methods is true then only the unique matches will be included in the iterator over the matches. A match or subgraph is considered unique if it differs from all other subgraphs found previously by at least one atom. Two subgraph matches which cover the same atoms, albeit in different orders, will be called duplicates and the subgraph found later in the search will be discarded.
bool SetMaxMatches(unsigned int m)
Sets the maximum number of subgraphs to be determined by the OESubSearch.Match method. Once the maximum number of subgraphs have been found the search for additional subgraphs is terminated. By default, maximum number of matches is set to 1024. The constraint on the maximum number of matches can be removed by calling this method with a value of zero.
bool SingleMatch(const OEMolBase &) const
Returns true, if a single subgraph isomorphism is detected in the molecule passed as the function argument. If no subgraph isomorphism is detected the method will return false.