CDPL::Chem::SubstructureSearch Class Reference

Searches for substructures of a target molecular graph that match the topology of a given query molecular graph. More...

#include <SubstructureSearch.hpp>

Public Types
typedef std::shared_ptr< SubstructureSearch >	SharedPointer
	A reference-counted smart pointer [SHPTR] for dynamically allocated SubstructureSearch instances. More...
typedef boost::indirect_iterator< ABMappingList::iterator, AtomBondMapping >	MappingIterator
	A mutable random access iterator used to iterate over the stored Chem::AtomBondMapping objects. More...
typedef boost::indirect_iterator< ABMappingList::const_iterator, const AtomBondMapping >	ConstMappingIterator
	A constant random access iterator used to iterate over the stored const Chem::AtomBondMapping objects. More...
typedef std::function< const AtomMatchExprPtr &(const Atom &)>	AtomMatchExpressionFunction
	Type of the functor used to retrieve the Chem::MatchExpression implementation instance for a query atom. More...
typedef std::function< const BondMatchExprPtr &(const Bond &)>	BondMatchExpressionFunction
	Type of the functor used to retrieve the Chem::MatchExpression implementation instance for a query bond. More...
typedef std::function< const MolGraphMatchExprPtr &(const MolecularGraph &)>	MolecularGraphMatchExpressionFunction
	Type of the functor used to retrieve the Chem::MatchExpression implementation instance for the query molecular graph. More...

Public Member Functions
	SubstructureSearch ()
	Constructs and initializes the SubstructureSearch instance. More...
	SubstructureSearch (const MolecularGraph &query)
	Constructs and initializes the SubstructureSearch instance for the query molecular graph query. More...
	SubstructureSearch (const SubstructureSearch &)=delete
	~SubstructureSearch ()
	Destructor. More...
SubstructureSearch &	operator= (const SubstructureSearch &)=delete
void	setAtomMatchExpressionFunction (const AtomMatchExpressionFunction &func)
	Installs a function that resolves the Chem::MatchExpression implementation instance for a query atom. More...
void	setBondMatchExpressionFunction (const BondMatchExpressionFunction &func)
	Installs a function that resolves the Chem::MatchExpression implementation instance for a query bond. More...
void	setMolecularGraphMatchExpressionFunction (const MolecularGraphMatchExpressionFunction &func)
	Installs a function that resolves the Chem::MatchExpression implementation instance for the query molecular graph. More...
void	setQuery (const MolecularGraph &query)
	Sets query as the new query molecular graph. More...
bool	mappingExists (const MolecularGraph &target)
	Tells whether the query molecular graph matches a substructure of the target molecular graph target. More...
bool	findMappings (const MolecularGraph &target)
	Searches for all possible atom/bond mappings of the query molecular graph to substructures of the target molecular graph target. More...
void	stopSearch ()
	Aborts the currently running substructure search process. More...
std::size_t	getNumMappings () const
	Returns the number of atom/bond mappings that were recorded in the last call to findMappings(). More...
AtomBondMapping &	getMapping (std::size_t idx)
	Returns a non-const reference to the stored atom/bond mapping object at index idx. More...
const AtomBondMapping &	getMapping (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 Chem::AtomBondMapping objects. More...
ConstMappingIterator	getMappingsBegin () const
	Returns a constant iterator pointing to the beginning of the stored const Chem::AtomBondMapping objects. More...
MappingIterator	getMappingsEnd ()
	Returns a mutable iterator pointing to the end of the stored Chem::AtomBondMapping objects. More...
ConstMappingIterator	getMappingsEnd () const
	Returns a constant iterator pointing to the end of the stored const Chem::AtomBondMapping objects. More...
MappingIterator	begin ()
	Returns a mutable iterator pointing to the beginning of the stored Chem::AtomBondMapping objects. More...
ConstMappingIterator	begin () const
	Returns a constant iterator pointing to the beginning of the stored const Chem::AtomBondMapping objects. More...
MappingIterator	end ()
	Returns a mutable iterator pointing to the end of the stored Chem::AtomBondMapping objects. More...
ConstMappingIterator	end () const
	Returns a constant iterator pointing to the end of the stored const Chem::AtomBondMapping 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 molecular graph atoms. More...
void	clearAtomMappingConstraints ()
	Clears all previously defined query to target molecular graph 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 molecular graph bonds. More...
void	clearBondMappingConstraints ()
	Clears all previously defined query to target molecular graph bond mapping constraints. More...

Detailed Description

Searches for substructures of a target molecular graph that match the topology of a given query molecular graph.

Successive calls to setQuery() and findMappings() produce all possible atom/bond mapping solutions. If just the information whether or not a mapping exists is of interest then the more efficient method mappingExists() can be used. Found mappings are recorded as Chem::AtomBondMapping objects that can be accessed via index through the method getMapping() or iteration using the iterator pair returned by the methods begin() and end(), respectively. User-defined per-atom, per-bond and per-molecular graph Chem::MatchExpression implementation instance accessor functions can be installed to extend equivalence tests beyond pure topology. The default functions retrieve the expressions saved as corresponding atom, bond and molecular graph property values (see Chem::AtomProperty::MATCH_EXPRESSION, Chem::BondProperty::MATCH_EXPRESSION and Chem::MolecularGraphProperty::MATCH_EXPRESSION). Result accumulation can be bounded by setMaxNumMappings() and uniqueMappingsOnly(). stopSearch() allows an immediate abort of the search process. Furthermore, query ↔ target atom and bond mappings can be restricted to user-defined subsets by the methods addAtomMappingConstraint() and addBondMappingConstraint(), respectively.

See also

[VFLIB2] for details on the underlying algorithm.

Member Typedef Documentation

SharedPointer

typedef std::shared_ptr<SubstructureSearch> CDPL::Chem::SubstructureSearch::SharedPointer

A reference-counted smart pointer [SHPTR] for dynamically allocated SubstructureSearch instances.

MappingIterator

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

A mutable random access iterator used to iterate over the stored Chem::AtomBondMapping 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 const Chem::AtomBondMapping objects.

AtomMatchExpressionFunction

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

Type of the functor used to retrieve the Chem::MatchExpression implementation instance for a query atom.

BondMatchExpressionFunction

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

Type of the functor used to retrieve the Chem::MatchExpression implementation instance for a query bond.

MolecularGraphMatchExpressionFunction

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

Type of the functor used to retrieve the Chem::MatchExpression implementation instance for the query molecular graph.

Constructor & Destructor Documentation

SubstructureSearch() [1/3]

CDPL::Chem::SubstructureSearch::SubstructureSearch

(

)

Constructs and initializes the SubstructureSearch instance.

SubstructureSearch() [2/3]

CDPL::Chem::SubstructureSearch::SubstructureSearch

(

const MolecularGraph &

query

)

Constructs and initializes the SubstructureSearch instance for the query molecular graph query.

Parameters

query

A molecular graph that represents the query structure.

SubstructureSearch() [3/3]

CDPL::Chem::SubstructureSearch::SubstructureSearch ( const SubstructureSearch &  )

delete

~SubstructureSearch()

CDPL::Chem::SubstructureSearch::~SubstructureSearch

(

)

Destructor.

Destroys the SubstructureSearch instance and frees all allocated resources.

Member Function Documentation

operator=()

SubstructureSearch& CDPL::Chem::SubstructureSearch::operator= ( const SubstructureSearch &  )

delete

setAtomMatchExpressionFunction()

void CDPL::Chem::SubstructureSearch::setAtomMatchExpressionFunction

(

const AtomMatchExpressionFunction &

func

)

Installs a function that resolves the Chem::MatchExpression implementation instance for a query atom.

Parameters

func	The accessor function to use.

setBondMatchExpressionFunction()

void CDPL::Chem::SubstructureSearch::setBondMatchExpressionFunction

(

const BondMatchExpressionFunction &

func

)

Installs a function that resolves the Chem::MatchExpression implementation instance for a query bond.

Parameters

func	The accessor function to use.

setMolecularGraphMatchExpressionFunction()

void CDPL::Chem::SubstructureSearch::setMolecularGraphMatchExpressionFunction

(

const MolecularGraphMatchExpressionFunction &

func

)

Installs a function that resolves the Chem::MatchExpression implementation instance for the query molecular graph.

Parameters

func	The accessor function to use.

setQuery()

void CDPL::Chem::SubstructureSearch::setQuery

(

const MolecularGraph &

query

)

Sets query as the new query molecular graph.

Parameters

query

A molecular graph that represents the new query.

mappingExists()

bool CDPL::Chem::SubstructureSearch::mappingExists

(

const MolecularGraph &

target

)

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

The method does not store any atom/bond mappings between the query and target molecular graph — 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

target

The target molecular graph that has to be searched for a match of the query.

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 molecular graph to substructures of the target molecular graph target.

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

target

The target molecular graph that has to be searched for matches of the query.

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

(

)

Aborts the currently running substructure search process.

Intended to be invoked from a callback (typically a match expression evaluator) running on the same thread as findMappings(). Once flagged, findMappings() returns at the next loop boundary.

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

idx	The zero-based index of the atom/bond mapping object to return.

Returns

A non-const reference to the Chem::AtomBondMapping object at index idx.

Exceptions

Base::IndexError

if idx is not in the range [0, getNumMappings()).

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

idx	The zero-based index of the atom/bond mapping object to return.

Returns

A const reference to the Chem::AtomBondMapping object at index idx.

Exceptions

Base::IndexError

if idx is not in the range [0, getNumMappings()).

getMappingsBegin() [1/2]

MappingIterator CDPL::Chem::SubstructureSearch::getMappingsBegin

(

)

Returns a mutable iterator pointing to the beginning of the stored Chem::AtomBondMapping objects.

Returns

A mutable iterator pointing to the beginning of the stored Chem::AtomBondMapping objects.

getMappingsBegin() [2/2]

ConstMappingIterator CDPL::Chem::SubstructureSearch::getMappingsBegin

(

)

const

Returns a constant iterator pointing to the beginning of the stored const Chem::AtomBondMapping objects.

Returns

A constant iterator pointing to the beginning of the stored const Chem::AtomBondMapping objects.

getMappingsEnd() [1/2]

MappingIterator CDPL::Chem::SubstructureSearch::getMappingsEnd

(

)

Returns a mutable iterator pointing to the end of the stored Chem::AtomBondMapping objects.

Returns

A mutable iterator pointing to the end of the stored Chem::AtomBondMapping objects.

getMappingsEnd() [2/2]

ConstMappingIterator CDPL::Chem::SubstructureSearch::getMappingsEnd

(

)

const

Returns a constant iterator pointing to the end of the stored const Chem::AtomBondMapping objects.

Returns

A constant iterator pointing to the end of the stored const Chem::AtomBondMapping objects.

begin() [1/2]

MappingIterator CDPL::Chem::SubstructureSearch::begin

(

)

Returns a mutable iterator pointing to the beginning of the stored Chem::AtomBondMapping objects.

Returns

A mutable iterator pointing to the beginning of the stored Chem::AtomBondMapping objects.

begin() [2/2]

ConstMappingIterator CDPL::Chem::SubstructureSearch::begin

(

)

const

Returns a constant iterator pointing to the beginning of the stored const Chem::AtomBondMapping objects.

Returns

A constant iterator pointing to the beginning of the stored const Chem::AtomBondMapping objects.

end() [1/2]

MappingIterator CDPL::Chem::SubstructureSearch::end

(

)

Returns a mutable iterator pointing to the end of the stored Chem::AtomBondMapping objects.

Returns

A mutable iterator pointing to the end of the stored Chem::AtomBondMapping objects.

end() [2/2]

ConstMappingIterator CDPL::Chem::SubstructureSearch::end

(

)

const

Returns a constant iterator pointing to the end of the stored const Chem::AtomBondMapping objects.

Returns

A constant iterator pointing to the end of the stored const Chem::AtomBondMapping 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 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

unique

If 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_mappings

The 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 molecular graph atoms.

By default, an atom of the query molecular graph is free to match any suitable target 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 molecular graph 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 molecular graph atoms.

Parameters

query_atom_idx	The index of the query molecular graph atom.
target_atom_idx	The index of the target molecular graph atom that has to be matched by the query atom.

clearAtomMappingConstraints()

void CDPL::Chem::SubstructureSearch::clearAtomMappingConstraints

(

)

Clears all previously defined query to target molecular graph 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 molecular graph bonds.

By default, a bond of the query molecular graph is free to match any suitable target 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 molecular graph 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 molecular graph bonds.

Parameters

query_bond_idx	The index of the query molecular graph bond.
target_bond_idx	The index of the target molecular graph bond that has to be matched by the query bond.

clearBondMappingConstraints()

void CDPL::Chem::SubstructureSearch::clearBondMappingConstraints

(

)

Clears all previously defined query to target molecular graph bond mapping constraints.

See also

addBondMappingConstraint()

---

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

• SubstructureSearch.hpp