Chemical Data Processing Library C++ API - Version 1.1.1
Classes | Public Types | Public Member Functions | List of all members
CDPL::Chem::SubstructureSearch Class Reference

SubstructureSearch. More...

#include <SubstructureSearch.hpp>

Public Types

typedef std::shared_ptr< SubstructureSearchSharedPointer
 
typedef boost::indirect_iterator< ABMappingList::iterator, AtomBondMappingMappingIterator
 A mutable random access iterator used to iterate over the stored atom/bond mapping objects. More...
 
typedef boost::indirect_iterator< ABMappingList::const_iterator, const AtomBondMappingConstMappingIterator
 A constant random access iterator used to iterate over the stored atom/bond mapping objects. More...
 
typedef std::function< const AtomMatchExprPtr &(const Atom &)> AtomMatchExpressionFunction
 
typedef std::function< const BondMatchExprPtr &(const Bond &)> BondMatchExpressionFunction
 
typedef std::function< const MolGraphMatchExprPtr &(const MolecularGraph &)> MolecularGraphMatchExpressionFunction
 

Public Member Functions

 SubstructureSearch ()
 Constructs and initializes a SubstructureSearch instance. More...
 
 SubstructureSearch (const MolecularGraph &query)
 Constructs and initializes a SubstructureSearch instance for the specified query structure. More...
 
 ~SubstructureSearch ()
 Destructor. More...
 
void setAtomMatchExpressionFunction (const AtomMatchExpressionFunction &func)
 
void setBondMatchExpressionFunction (const BondMatchExpressionFunction &func)
 
void setMolecularGraphMatchExpressionFunction (const MolecularGraphMatchExpressionFunction &func)
 
void setQuery (const MolecularGraph &query)
 Allows to specify a new query structure. More...
 
bool mappingExists (const MolecularGraph &target)
 Tells whether the query structure matches a substructure of the specified target molecular graph. More...
 
bool findMappings (const MolecularGraph &target)
 Searches for all possible atom/bond mappings of the query structure to substructures of the specified target molecular graph. More...
 
void stopSearch ()
 
std::size_t getNumMappings () const
 Returns the number of atom/bond mappings that were recorded in the last call to findMappings(). More...
 
AtomBondMappinggetMapping (std::size_t idx)
 Returns a non-const reference to the stored atom/bond mapping object at index idx. More...
 
const AtomBondMappinggetMapping (std::size_t idx) const
 Returns a const reference to the stored atom/bond mapping object at index idx. More...
 
MappingIterator getMappingsBegin ()
 Returns a mutable iterator pointing to the beginning of the stored atom/bond mapping objects. More...
 
ConstMappingIterator getMappingsBegin () const
 Returns a constant iterator pointing to the beginning of the stored atom/bond mapping objects. More...
 
MappingIterator getMappingsEnd ()
 Returns a mutable iterator pointing to the end of the stored atom/bond mapping objects. More...
 
ConstMappingIterator getMappingsEnd () const
 Returns a constant iterator pointing to the end of the stored atom/bond mapping objects. More...
 
MappingIterator begin ()
 Returns a mutable iterator pointing to the beginning of the stored atom/bond mapping objects. More...
 
ConstMappingIterator begin () const
 Returns a constant iterator pointing to the beginning of the stored atom/bond mapping objects. More...
 
MappingIterator end ()
 Returns a mutable iterator pointing to the end of the stored atom/bond mapping objects. More...
 
ConstMappingIterator end () const
 Returns a constant iterator pointing to the end of the stored atom/bond mapping objects. More...
 
void uniqueMappingsOnly (bool unique)
 Allows to specify whether or not to store only unique atom/bond mappings. More...
 
bool uniqueMappingsOnly () const
 Tells whether duplicate atom/bond mappings are discarded. More...
 
void setMaxNumMappings (std::size_t max_num_mappings)
 Allows to specify a limit on the number of stored atom/bond mappings. More...
 
std::size_t getMaxNumMappings () const
 Returns the specified limit on the number of stored atom/bond mappings. More...
 
void addAtomMappingConstraint (std::size_t query_atom_idx, std::size_t target_atom_idx)
 Adds a constraint on the allowed mappings between query and target structure atoms. More...
 
void clearAtomMappingConstraints ()
 Clears all previously defined query to target atom mapping constraints. More...
 
void addBondMappingConstraint (std::size_t query_bond_idx, std::size_t target_bond_idx)
 Adds a constraint on the allowed mappings between query and target structure bonds. More...
 
void clearBondMappingConstraints ()
 Clears all previously defined query to target bond mapping constraints. More...
 

Detailed Description

SubstructureSearch.

See also
[VFLIB2]

Member Typedef Documentation

◆ SharedPointer

◆ MappingIterator

typedef boost::indirect_iterator<ABMappingList::iterator, AtomBondMapping> CDPL::Chem::SubstructureSearch::MappingIterator

A mutable random access iterator used to iterate over the stored atom/bond mapping objects.

◆ ConstMappingIterator

typedef boost::indirect_iterator<ABMappingList::const_iterator, const AtomBondMapping> CDPL::Chem::SubstructureSearch::ConstMappingIterator

A constant random access iterator used to iterate over the stored atom/bond mapping objects.

◆ AtomMatchExpressionFunction

typedef std::function<const AtomMatchExprPtr&(const Atom&)> CDPL::Chem::SubstructureSearch::AtomMatchExpressionFunction

◆ BondMatchExpressionFunction

typedef std::function<const BondMatchExprPtr&(const Bond&)> CDPL::Chem::SubstructureSearch::BondMatchExpressionFunction

◆ MolecularGraphMatchExpressionFunction

typedef std::function<const MolGraphMatchExprPtr&(const MolecularGraph&)> CDPL::Chem::SubstructureSearch::MolecularGraphMatchExpressionFunction

Constructor & Destructor Documentation

◆ SubstructureSearch() [1/2]

CDPL::Chem::SubstructureSearch::SubstructureSearch ( )

Constructs and initializes a SubstructureSearch instance.

◆ SubstructureSearch() [2/2]

CDPL::Chem::SubstructureSearch::SubstructureSearch ( const MolecularGraph query)

Constructs and initializes a SubstructureSearch instance for the specified query structure.

Parameters
queryA molecular graph that represents the query structure.

◆ ~SubstructureSearch()

CDPL::Chem::SubstructureSearch::~SubstructureSearch ( )

Destructor.

Destroys the SubstructureSearch instance and frees all allocated resources.

Member Function Documentation

◆ setAtomMatchExpressionFunction()

void CDPL::Chem::SubstructureSearch::setAtomMatchExpressionFunction ( const AtomMatchExpressionFunction func)

◆ setBondMatchExpressionFunction()

void CDPL::Chem::SubstructureSearch::setBondMatchExpressionFunction ( const BondMatchExpressionFunction func)

◆ setMolecularGraphMatchExpressionFunction()

void CDPL::Chem::SubstructureSearch::setMolecularGraphMatchExpressionFunction ( const MolecularGraphMatchExpressionFunction func)

◆ setQuery()

void CDPL::Chem::SubstructureSearch::setQuery ( const MolecularGraph query)

Allows to specify a new query structure.

Parameters
queryA molecular graph that represents the query structure.

◆ mappingExists()

bool CDPL::Chem::SubstructureSearch::mappingExists ( const MolecularGraph target)

Tells whether the query structure matches a substructure of the specified target molecular graph.

The method does not store any atom/bond mappings between the query and target structure - it just tells if a complete mapping of the query is possible. If you need access to the atom/bond mappings, use findMappings() instead.

Parameters
targetThe molecular graph that has to be searched for a match of the query structure.
Returns
true if the query matches a substructure of the target molecular graph, and false otherwise.
Note
Any atom/bond mappings that were recorded in a previous call to findMappings() will be discarded.

◆ findMappings()

bool CDPL::Chem::SubstructureSearch::findMappings ( const MolecularGraph target)

Searches for all possible atom/bond mappings of the query structure to substructures of the specified target molecular graph.

The method will store all found subgraph mapping solutions up to the maximum number of recorded mappings specified by setMaxNumMappings(). If only unique mappings have to be stored (see uniqueMappingsOnly(bool unique)), any duplicates of previously found mappings will be discarded.

Parameters
targetThe molecular graph that has to be searched for matches of the query structure.
Returns
true if the query matches at least one substructure of the specified target molecular graph, and false otherwise.
Note
Any atom/bond mappings that were recorded in a previous call to findMappings() will be discarded.

◆ stopSearch()

void CDPL::Chem::SubstructureSearch::stopSearch ( )

◆ getNumMappings()

std::size_t CDPL::Chem::SubstructureSearch::getNumMappings ( ) const

Returns the number of atom/bond mappings that were recorded in the last call to findMappings().

Returns
The number of atom/bond mappings that were recorded in the last call to findMappings().

◆ getMapping() [1/2]

AtomBondMapping& CDPL::Chem::SubstructureSearch::getMapping ( std::size_t  idx)

Returns a non-const reference to the stored atom/bond mapping object at index idx.

Parameters
idxThe zero-based index of the atom/bond mapping object to return.
Returns
A non-const reference to the atom/bond mapping object at index idx.
Exceptions
Base::IndexErrorif no mappings are available or idx is not in the range [0, getNumMappings() - 1].

◆ getMapping() [2/2]

const AtomBondMapping& CDPL::Chem::SubstructureSearch::getMapping ( std::size_t  idx) const

Returns a const reference to the stored atom/bond mapping object at index idx.

Parameters
idxThe zero-based index of the atom/bond mapping object to return.
Returns
A const reference to the atom/bond mapping object at index idx.
Exceptions
Base::IndexErrorif no mappings are available or idx is not in the range [0, getNumMappings() - 1].

◆ getMappingsBegin() [1/2]

MappingIterator CDPL::Chem::SubstructureSearch::getMappingsBegin ( )

Returns a mutable iterator pointing to the beginning of the stored atom/bond mapping objects.

Returns
A mutable iterator pointing to the beginning of the stored atom/bond mapping objects.

◆ getMappingsBegin() [2/2]

ConstMappingIterator CDPL::Chem::SubstructureSearch::getMappingsBegin ( ) const

Returns a constant iterator pointing to the beginning of the stored atom/bond mapping objects.

Returns
A constant iterator pointing to the beginning of the stored atom/bond mapping objects.

◆ getMappingsEnd() [1/2]

MappingIterator CDPL::Chem::SubstructureSearch::getMappingsEnd ( )

Returns a mutable iterator pointing to the end of the stored atom/bond mapping objects.

Returns
A mutable iterator pointing to the end of the stored atom/bond mapping objects.

◆ getMappingsEnd() [2/2]

ConstMappingIterator CDPL::Chem::SubstructureSearch::getMappingsEnd ( ) const

Returns a constant iterator pointing to the end of the stored atom/bond mapping objects.

Returns
A constant iterator pointing to the end of the stored atom/bond mapping objects.

◆ begin() [1/2]

MappingIterator CDPL::Chem::SubstructureSearch::begin ( )

Returns a mutable iterator pointing to the beginning of the stored atom/bond mapping objects.

Returns
A mutable iterator pointing to the beginning of the stored atom/bond mapping objects.

◆ begin() [2/2]

ConstMappingIterator CDPL::Chem::SubstructureSearch::begin ( ) const

Returns a constant iterator pointing to the beginning of the stored atom/bond mapping objects.

Returns
A constant iterator pointing to the beginning of the stored atom/bond mapping objects.

◆ end() [1/2]

MappingIterator CDPL::Chem::SubstructureSearch::end ( )

Returns a mutable iterator pointing to the end of the stored atom/bond mapping objects.

Returns
A mutable iterator pointing to the end of the stored atom/bond mapping objects.

◆ end() [2/2]

ConstMappingIterator CDPL::Chem::SubstructureSearch::end ( ) const

Returns a constant iterator pointing to the end of the stored atom/bond mapping objects.

Returns
A constant iterator pointing to the end of the stored atom/bond mapping objects.

◆ uniqueMappingsOnly() [1/2]

void CDPL::Chem::SubstructureSearch::uniqueMappingsOnly ( bool  unique)

Allows to specify whether or not to store only unique atom/bond mappings.

A mapping of the query pattern to a substructure of the target molecular graph is considered to be unique if it differs from all previously found mappings by at least one atom or bond. If the unique argument is true, and a newly discovered mapping covers the same atoms and bonds of the target (including all permutations) as a mapping that was found earlier in the search process, it is considered as a duplicate and will be discarded.

Parameters
uniqueIf true, only unique mappings will be stored, and all found mappings otherwise.
Note
By default, duplicate mappings are not discarded.

◆ uniqueMappingsOnly() [2/2]

bool CDPL::Chem::SubstructureSearch::uniqueMappingsOnly ( ) const

Tells whether duplicate atom/bond mappings are discarded.

Returns
true if duplicate mappings are discarded, and false otherwise.
See also
uniqueMappingsOnly(bool unique)

◆ setMaxNumMappings()

void CDPL::Chem::SubstructureSearch::setMaxNumMappings ( std::size_t  max_num_mappings)

Allows to specify a limit on the number of stored atom/bond mappings.

In a call to findMappings() the substructure search will terminate as soon as the specified maximum number of stored atom/bond mappings has been reached. A previously set limit on the number of mappings can be disabled by providing zero for the value of max_num_mappings.

Parameters
max_num_mappingsThe maximum number of atom/bond mappings to store.
Note
By default, no limit is imposed on the number of stored mappings.

◆ getMaxNumMappings()

std::size_t CDPL::Chem::SubstructureSearch::getMaxNumMappings ( ) const

Returns the specified limit on the number of stored atom/bond mappings.

Returns
The specified maximum number of stored atom/bond mappings.
See also
setMaxNumMappings(), findMappings()

◆ addAtomMappingConstraint()

void CDPL::Chem::SubstructureSearch::addAtomMappingConstraint ( std::size_t  query_atom_idx,
std::size_t  target_atom_idx 
)

Adds a constraint on the allowed mappings between query and target structure atoms.

By default, an atom of the query structure is free to match any suitable target structure atom. When this method gets called for a particular query/target atom pair (specified by query_atom_idx and target_atom_idx), future substructure searches will find only those subgraph mapping solutions (if any) where the given query atom maps to the specified target structure atom. Multiple calls to addAtomMappingConstraint() for the same query atom have an additive effect and allow to restrict the valid query atom mappings not only to a single but also a larger set of target structure atoms.

Parameters
query_atom_idxThe index of the query structure atom.
target_atom_idxThe index of the target structure atom that has to be matched by the query atom.

◆ clearAtomMappingConstraints()

void CDPL::Chem::SubstructureSearch::clearAtomMappingConstraints ( )

Clears all previously defined query to target atom mapping constraints.

See also
addAtomMappingConstraint()

◆ addBondMappingConstraint()

void CDPL::Chem::SubstructureSearch::addBondMappingConstraint ( std::size_t  query_bond_idx,
std::size_t  target_bond_idx 
)

Adds a constraint on the allowed mappings between query and target structure bonds.

By default, a bond of the query structure is free to match any suitable target structure bond. When this method gets called for a particular query/target bond pair (specified by query_bond_idx and target_bond_idx), future substructure searches will find only those subgraph mapping solutions (if any) where the given query bond maps to the specified target structure bond. Multiple calls to addBondMappingConstraint() for the same query bond have an additive effect and allow to restrict the valid query bond mappings not only to a single but also a larger set of target structure bonds.

Parameters
query_bond_idxThe index of the query structure bond.
target_bond_idxThe index of the target structure bond that has to be matched by the query bond.

◆ clearBondMappingConstraints()

void CDPL::Chem::SubstructureSearch::clearBondMappingConstraints ( )

Clears all previously defined query to target bond mapping constraints.

See also
addBondMappingConstraint()

The documentation for this class was generated from the following file: