OEMCSSearch¶

class OEMCSSearch

This class represents OEMCSSearch.

This OEMCSSearch class identifies a set of maximum substructures common to two molecules.

Constructors¶

OEMCSSearch(unsigned int type=OEMCSType::Default)

Default constructor.

OEMCSSearch(const OEMCSSearch &rhs)

Copy constructor.

OEMCSSearch(const char *smarts, unsigned int type=OEMCSType::Default)

Constructs an OEMCSSearch object using a ‘smarts’ pattern. The SMARTS pattern is parsed into a query molecule (OEQMolBase). The valid types of the OEMCSSearch are defined in the OEMCSType namespace.

OEMCSSearch(const OEQMolBase &qmol, bool perception=true,
            unsigned int type=OEMCSType::Default)

Constructs an OEMCSSearch object using a query molecule (OEQMolBase).

qmol: The query molecule of the MCS search.
type: The type of the OEMCSSearch from the OEMCSType namespace.
perception: If true, then ring perception is performed on the query molecule.

OEMCSSearch(const OEMolBase &, unsigned int atomexpr, unsigned int bondexpr,
            unsigned int type=OEMCSType::Default)

Constructs an OEMCSSearch 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 common subgraph search.

operator=¶

OEMCSSearch &operator=(const OEMCSSearch &rhs)

Assignment operator that copies the data of the ‘rhs’ OEMCSSearch object into the right-hand side OEMCSSearch object.

operator bool¶

operator bool() const

Test for successful initialization of an OEMCSSearch object. If initialization was attempted with an invalid SMARTS pattern or query molecule (OEQMolBase) then this method will return false. If initialization was completed successfully this method will return true. An OEMCSSearch object is considered to be uninitialized when constructed with the default constructor.

AddConstraint¶

bool AddConstraint(const OEMatchPair<OEBondBase> &)
bool AddConstraint(const OEMatchPair<OEAtomBase> &)

The search space of a maximum common subgraph determination can be restricted by constraining pairs of nodes or edges (atoms or bonds) to be mapped onto one another in all subgraph solutions. All subgraph solutions will contain all constraints specified by this method.

Both OEMCSSearch.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 OEMCSSearch object then OEMCSSearch.AddConstraint will return false.

Multiple calls to OEMCSSearch.AddConstraint using the same pattern atom or bond will return false as it is impossible to satisfy multiple simultaneous constraints for a single pattern atom or bond, hence the exclusivity.

ClearConstraints¶

void ClearConstraints()

Clears all prior match constraints set with the OEMCSSearch.AddConstraint methods.

GetMaxMatches¶

unsigned int GetMaxMatches() const

Returns the maximum number of common subgraphs that the OEMCSSearch will identify before terminating the search. A value of zero indicates that no arbitrary limit has been set on the total number of subgraphs to be identified. By default, the maximum number of matches is set to 1024 This value can be set using the OEMCSSearch.SetMaxMatches method.

GetMinAtoms¶

unsigned int GetMinAtoms() const

Returns the minimum number of atoms of a subgraph that can be returned as a maximum common subgraph. This value can be set using the OEMCSSearch.SetMinAtoms method.

GetPattern¶

const OEQMolBase &GetPattern() const

Returns a read-only reference to the query molecule (OEQMolBase) of OEMCSSearch. Const OEQMolBase methods can be used on the returned OEQMolBase reference. If the OEMCSSearch object has not been initialized, a reference to an empty molecule will be returned.

Init¶

bool Init(const char *smarts)

(Re)initializes an OEMCSSearch object using a ‘smarts’ pattern. The SMARTS pattern is parsed to create a query molecule available for maximum common subgraph matching. The method will return true if initialization completes successfully, and false upon failure.

Note

Prior state information is cleared before initialization, and is lost even if the method fails to initialize properly.

bool Init(const OEQMolBase &qmol, bool perception=true)

(Re)initializes an OEMCSSearch object using a query molecule (OEQMolBase) reference. The method will return true if initialization completes successfully, and false upon failure.

qmol: The query molecule of the MCS search.
perception: If true, then ring perception is performed on the query molecule.

Note

Prior state information is cleared before initialization, and is lost even if the method fails to initialize properly.

bool Init(const OEMolBase &mol, unsigned int atomexpr, unsigned int bondexpr)

(Re)initializes an OEMCSSearch object using a molecule and expression options that are used to convert the given molecule into a OEQMolBase query object.

mol: The query molecule of the maximum common substructure search.
atomexpr: This value has to be any combination of atom expressions of the OEExprOpts namespace.
bondexpr: This value has to be any combination of bond expressions of the OEExprOpts namespace.

Expression options are used to convert the atom and bond data into expression trees which are used during the common subgraph search. The method will return true if initialization completes successfully, and false upon failure.

Note

Prior state information is cleared before initialization, and is lost even if the method fails to initialize properly.

Match¶

OESystem::OEIterBase<OEMatchBase> *Match(const OEMolBase &,
                                         bool uniquematch=false) const

Performs search in order to identify maximum common subgraphs shared between the passed OEMolBase and the query molecule which the OEMCSSearch 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.

If the ‘uniquematch’ argument passed to the methods is true then only the unique matches will be returned in the iterator over the matches. By definition, a match or subgraph is considered unique if it differs from all other subgraphs found previously by at least one atom or bond. Additionally, it is also considered unique if the query subgraph is mapped to a different part of the target (See example in the Maximum Common Substructure Search section)

SetMCSFunc¶

bool SetMCSFunc(const OEChem::OEMCSFunc &)

Stores a copy of the passed OEMCSFunc functor in the OEMCSSearch object. The functor is then used to evaluate and order subgraphs found during a maximum common subgraph search.

SetMaxMatches¶

bool SetMaxMatches(unsigned int)

Sets the maximum number of maximum common subgraph matches that will be returned by the OEMCSSearch.Match method.

Note

The search for maximum common substructures will not terminate immediately upon reaching this limit. The maximum common subgraph cannot be known unless the MCS is composed of all atoms and bonds of at least one of the graphs being compared. The limit of subgraphs to be returned may be reached with a smaller subgraph than the maximum. In such a case the search continues for larger subgraphs until the search is exhausted. OEMCSSearch.Match will return the first \(N\) maximum common subgraphs where \(N\) is less than or equal to the maximum match limit.

The default limit set upon construction of an OEMCSSearch object is 1024 matches. This value can be retrieved using the OEMCSSearch.GetMaxMatches method.

SetMinAtoms¶

bool SetMinAtoms(unsigned int)

Sets the minimum number of atoms required of a subgraph match to be returned a solution by a MCS search. A single atom can be a perfectly valid maximum common subgraph, however, for many applications such a small subgraph may not be considered useful. Setting the minimum number of atoms to an appropriate size prevents unproductive subgraph matches from being returned by the OEMCSSearch.Match method. The default value for the minimum number of atoms in a subgraph match is set to 1 upon construction of an OEMCSSearch object. This value can be retrieved using the OEMCSSearch.GetMinAtoms method.