RDKit::SubstructLibrary Class Reference

Substructure Search a library of molecules. More...

`#include <SubstructLibrary.h>`

## Public Member Functions

| SubstructLibrary ()
| SubstructLibrary (boost::shared_ptr< MolHolderBase > molecules)
| SubstructLibrary (boost::shared_ptr< MolHolderBase > molecules, boost::shared_ptr< FPHolderBase > fingerprints)
| SubstructLibrary (const std::string &pickle)
boost::shared_ptr< MolHolderBase > & | getMolHolder ()
| Get the underlying molecule holder implementation. More...
const boost::shared_ptr< MolHolderBase > & | getMolHolder () const
boost::shared_ptr< FPHolderBase > & | getFpHolder ()
| Get the underlying molecule holder implementation. More...
const boost::shared_ptr< FPHolderBase > & | getFpHolder () const
| Get the underlying molecule holder implementation. More...
const MolHolderBase & | getMolecules () const
FPHolderBase & | getFingerprints ()
| Get the underlying fingerprint implementation. More...
const FPHolderBase & | getFingerprints () const
unsigned int | addMol (const ROMol &mol)
| Add a molecule to the library. More...
std::vector< unsigned int > | getMatches (const ROMol &query, bool recursionPossible=true, bool useChirality=true, bool useQueryQueryMatches=false, int numThreads=-1, int maxResults=-1)
| Get the matching indices for the query. More...
std::vector< unsigned int > | getMatches (const ROMol &query, unsigned int startIdx, unsigned int endIdx, bool recursionPossible=true, bool useChirality=true, bool useQueryQueryMatches=false, int numThreads=-1, int maxResults=-1)
| Get the matching indices for the query between the given indices. More...
unsigned int | countMatches (const ROMol &query, bool recursionPossible=true, bool useChirality=true, bool useQueryQueryMatches=false, int numThreads=-1)
| Return the number of matches for the query. More...
unsigned int | countMatches (const ROMol &query, unsigned int startIdx, unsigned int endIdx, bool recursionPossible=true, bool useChirality=true, bool useQueryQueryMatches=false, int numThreads=-1)
| Return the number of matches for the query between the given indices. More...
bool | hasMatch (const ROMol &query, bool recursionPossible=true, bool useChirality=true, bool useQueryQueryMatches=false, int numThreads=-1)
| Returns true if any match exists for the query. More...
bool | hasMatch (const ROMol &query, unsigned int startIdx, unsigned int endIdx, bool recursionPossible=true, bool useChirality=true, bool useQueryQueryMatches=false, int numThreads=-1)
boost::shared_ptr< ROMol > | getMol (unsigned int idx) const
| Returns the molecule at the given index. More...
boost::shared_ptr< ROMol > | operator[] (unsigned int idx)
| Returns the molecule at the given index. More...
unsigned int | size () const
| return the number of molecules in the library More...
void | resetHolders ()
| access required for serialization More...
void | toStream (std::ostream &ss) const
| serializes (pickles) to a stream More...
std::string | Serialize () const
| returns a string with a serialized (pickled) representation More...
void | initFromStream (std::istream &ss)
| initializes from a stream pickle More...
void | initFromString (const std::string &text)
| initializes from a string pickle More...

## Detailed Description

Substructure Search a library of molecules.

This class allows for multithreaded substructure searches os large datasets.

The implementations can use fingerprints to speed up searches and have molecules cached as binary forms to reduce memory usage.

basic usage:

SubstructLibrary lib;
lib.addMol(mol);
std::vector<unsigned int> results = lib.getMatches(query);
for(std::vector<unsigned int>::const_iterator matchIndex=results.begin();
matchIndex != results.end();
++matchIndex) {
boost::shared_ptr<ROMol> match = lib.getMol(*matchIndex);
}

Using different mol holders and pattern fingerprints.

boost::shared_ptr<CachedTrustedSmilesMolHolder> molHolder = \
boost::make_shared<CachedTrustedSmilesMolHolder>();
boost::shared_ptr<PatternHolder> patternHolder = \
boost::make_shared<PatternHolder>();
SubstructLibrary lib(molHolder, patternHolder);
lib.addMol(mol);

Cached molecule holders create molecules on demand. There are currently three styles of cached molecules.

CachedMolHolder: stores molecules in the rdkit binary format. CachedSmilesMolHolder: stores molecules in smiles format. CachedTrustedSmilesMolHolder: stores molecules in smiles format.

The CachedTrustedSmilesMolHolder is made to add molecules from a trusted source. This makes the basic assumption that RDKit was used to sanitize and canonicalize the smiles string. In practice this is considerably faster than using arbitrary smiles strings since certain assumptions can be made.

When loading from external data, as opposed to using the "addMol" API, care must be taken to ensure that the pattern fingerprints and smiles are synchronized.

Each pattern holder has an API point for making its fingerprint. This is useful to ensure that the pattern stored in the database will be compatible with the patterns made when analyzing queries.

boost::shared_ptr<CachedTrustedSmilesMolHolder> molHolder = \
boost::make_shared<CachedTrustedSmilesMolHolder>();
boost::shared_ptr<PatternHolder> patternHolder = \
boost::make_shared<PatternHolder>();
// the PatternHolder instance is able to make fingerprints.
// These, of course, can be read from a file. For demonstration
// purposes we construct them here.
const std::string trustedSmiles = "c1ccccc1";
ROMol *m = SmilesToMol(trustedSmiles);
const ExplicitBitVect *bitVector = patternHolder->makeFingerprint(*m);
// The trusted smiles and bitVector can be read from any source.
// This is the fastest way to load a substruct library.
molHolder->addSmiles( trustedSmiles );
patternHolder->addFingerprint( *bitVector );
SubstructLibrary lib(molHolder, patternHolder);
delete m;
delete bitVector;

Definition at line 360 of file SubstructLibrary.h.

## Constructor & Destructor Documentation

## SubstructLibrary() [1/4]

RDKit::SubstructLibrary::SubstructLibrary | ( |  | ) |

inline

Definition at line 367 of file SubstructLibrary.h.

## SubstructLibrary() [2/4]

RDKit::SubstructLibrary::SubstructLibrary | ( | boost::shared_ptr< MolHolderBase > | molecules | ) |

inline

Definition at line 373 of file SubstructLibrary.h.

## SubstructLibrary() [3/4]

RDKit::SubstructLibrary::SubstructLibrary | ( | boost::shared_ptr< MolHolderBase > | molecules,
|  | boost::shared_ptr< FPHolderBase > | fingerprints
| ) |  |

inline

Definition at line 376 of file SubstructLibrary.h.

## SubstructLibrary() [4/4]

RDKit::SubstructLibrary::SubstructLibrary | ( | const std::string & | pickle | ) |

inline

Definition at line 383 of file SubstructLibrary.h.

References RDKit::EnumerationStrategyPickler::pickle().

## Member Function Documentation

## addMol()

unsigned int RDKit::SubstructLibrary::addMol | ( | const ROMol & | mol | ) |

Add a molecule to the library.

Parameters

  mol | Molecule to add

returns index for the molecule in the library

## countMatches() [1/2]

unsigned int RDKit::SubstructLibrary::countMatches | ( | const ROMol & | query,
|  | bool | recursionPossible = `true`,
|  | bool | useChirality = `true`,
|  | bool | useQueryQueryMatches = `false`,
|  | int | numThreads = `-1`
| ) |  |

Return the number of matches for the query.

Parameters

  query | Query to match against molecules
  recursionPossible | flags whether or not recursive matches are allowed [ default true ]
  useChirality | use atomic CIP codes as part of the comparison [ default true ]
  useQueryQueryMatches | if set, the contents of atom and bond queries [ default false ] will be used as part of the matching
  numThreads | If -1 use all available processors [default -1]

## countMatches() [2/2]

unsigned int RDKit::SubstructLibrary::countMatches | ( | const ROMol & | query,
|  | unsigned int | startIdx,
|  | unsigned int | endIdx,
|  | bool | recursionPossible = `true`,
|  | bool | useChirality = `true`,
|  | bool | useQueryQueryMatches = `false`,
|  | int | numThreads = `-1`
| ) |  |

Return the number of matches for the query between the given indices.

Parameters

  query | Query to match against molecules
  startIdx | Start index of the search
  endIdx | Ending idx (non-inclusive) of the search.
  recursionPossible | flags whether or not recursive matches are allowed [ default true ]
  useChirality | use atomic CIP codes as part of the comparison [ default true ]
  useQueryQueryMatches | if set, the contents of atom and bond queries [ default false ] will be used as part of the matching
  numThreads | If -1 use all available processors [default -1]

## getFingerprints() [1/2]

FPHolderBase& RDKit::SubstructLibrary::getFingerprints | ( |  | ) |

inline

Get the underlying fingerprint implementation.

Throws a value error if no fingerprints have been set

Definition at line 413 of file SubstructLibrary.h.

## getFingerprints() [2/2]

const FPHolderBase& RDKit::SubstructLibrary::getFingerprints | ( |  | ) | const

inline

Definition at line 419 of file SubstructLibrary.h.

## getFpHolder() [1/2]

boost::shared_ptr<FPHolderBase>& RDKit::SubstructLibrary::getFpHolder | ( |  | ) |

inline

Get the underlying molecule holder implementation.

Definition at line 399 of file SubstructLibrary.h.

## getFpHolder() [2/2]

const boost::shared_ptr<FPHolderBase>& RDKit::SubstructLibrary::getFpHolder | ( |  | ) | const

inline

Get the underlying molecule holder implementation.

Definition at line 402 of file SubstructLibrary.h.

## getMatches() [1/2]

std::vector<unsigned int> RDKit::SubstructLibrary::getMatches | ( | const ROMol & | query,
|  | bool | recursionPossible = `true`,
|  | bool | useChirality = `true`,
|  | bool | useQueryQueryMatches = `false`,
|  | int | numThreads = `-1`,
|  | int | maxResults = `-1`
| ) |  |

Get the matching indices for the query.

Parameters

  query | Query to match against molecules
  recursionPossible | flags whether or not recursive matches are allowed [ default true ]
  useChirality | use atomic CIP codes as part of the comparison [ default true ]
  useQueryQueryMatches | if set, the contents of atom and bond queries [ default false ] will be used as part of the matching
  numThreads | If -1 use all available processors [default -1]
  maxResults | Maximum results to return, -1 means return all [default -1]

## getMatches() [2/2]

std::vector<unsigned int> RDKit::SubstructLibrary::getMatches | ( | const ROMol & | query,
|  | unsigned int | startIdx,
|  | unsigned int | endIdx,
|  | bool | recursionPossible = `true`,
|  | bool | useChirality = `true`,
|  | bool | useQueryQueryMatches = `false`,
|  | int | numThreads = `-1`,
|  | int | maxResults = `-1`
| ) |  |

Get the matching indices for the query between the given indices.

Parameters

  query | Query to match against molecules
  startIdx | Start index of the search
  endIdx | Ending idx (non-inclusive) of the search.
  recursionPossible | flags whether or not recursive matches are allowed [ default true ]
  useChirality | use atomic CIP codes as part of the comparison [ default true ]
  useQueryQueryMatches | if set, the contents of atom and bond queries [ default false ] will be used as part of the matching
  numThreads | If -1 use all available processors [default -1]
  maxResults | Maximum results to return, -1 means return all [default -1]

## getMol()

boost::shared_ptr<ROMol> RDKit::SubstructLibrary::getMol | ( | unsigned int | idx | ) | const

inline

Returns the molecule at the given index.

Parameters

  idx | Index of the molecule in the library

Definition at line 549 of file SubstructLibrary.h.

References RDKit::MolHolderBase::getMol(), and PRECONDITION.

## getMolecules()

const MolHolderBase& RDKit::SubstructLibrary::getMolecules | ( |  | ) | const

inline

Definition at line 406 of file SubstructLibrary.h.

References PRECONDITION.

## getMolHolder() [1/2]

boost::shared_ptr<MolHolderBase>& RDKit::SubstructLibrary::getMolHolder | ( |  | ) |

inline

Get the underlying molecule holder implementation.

Definition at line 392 of file SubstructLibrary.h.

## getMolHolder() [2/2]

const boost::shared_ptr<MolHolderBase>& RDKit::SubstructLibrary::getMolHolder | ( |  | ) | const

inline

Definition at line 394 of file SubstructLibrary.h.

## hasMatch() [1/2]

bool RDKit::SubstructLibrary::hasMatch | ( | const ROMol & | query,
|  | bool | recursionPossible = `true`,
|  | bool | useChirality = `true`,
|  | bool | useQueryQueryMatches = `false`,
|  | int | numThreads = `-1`
| ) |  |

Returns true if any match exists for the query.

Parameters

  query | Query to match against molecules
  recursionPossible | flags whether or not recursive matches are allowed [ default true ]
  useChirality | use atomic CIP codes as part of the comparison [ default true ]
  useQueryQueryMatches | if set, the contents of atom and bond queries [ default false ] will be used as part of the matching
  numThreads | If -1 use all available processors [default -1]

## hasMatch() [2/2]

bool RDKit::SubstructLibrary::hasMatch | ( | const ROMol & | query,
|  | unsigned int | startIdx,
|  | unsigned int | endIdx,
|  | bool | recursionPossible = `true`,
|  | bool | useChirality = `true`,
|  | bool | useQueryQueryMatches = `false`,
|  | int | numThreads = `-1`
| ) |  |

Returns true if any match exists for the query between the specified indices

Parameters

  query | Query to match against molecules
  startIdx | Start index of the search
  endIdx | Ending idx (inclusive) of the search.
  recursionPossible | flags whether or not recursive matches are allowed [ default true ]
  useChirality | use atomic CIP codes as part of the comparison [ default true ]
  useQueryQueryMatches | if set, the contents of atom and bond queries [ default false ] will be used as part of the matching
  numThreads | If -1 use all available processors [default -1]

## initFromStream()

void RDKit::SubstructLibrary::initFromStream | ( | std::istream & | ss | ) |

initializes from a stream pickle

## initFromString()

void RDKit::SubstructLibrary::initFromString | ( | const std::string & | text | ) |

initializes from a string pickle

## operator[]()

boost::shared_ptr<ROMol> RDKit::SubstructLibrary::operator[] | ( | unsigned int | idx | ) |

inline

Returns the molecule at the given index.

Parameters

  idx | Index of the molecule in the library

Definition at line 559 of file SubstructLibrary.h.

References RDKit::MolHolderBase::getMol(), and PRECONDITION.

## resetHolders()

void RDKit::SubstructLibrary::resetHolders | ( |  | ) |

inline

access required for serialization

Definition at line 572 of file SubstructLibrary.h.

## Serialize()

std::string RDKit::SubstructLibrary::Serialize | ( |  | ) | const

returns a string with a serialized (pickled) representation

## size()

unsigned int RDKit::SubstructLibrary::size | ( |  | ) | const

inline

return the number of molecules in the library

Definition at line 566 of file SubstructLibrary.h.

References PRECONDITION.

## toStream()

void RDKit::SubstructLibrary::toStream | ( | std::ostream & | ss | ) | const

serializes (pickles) to a stream

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

- SubstructLibrary.h

RDKit::SmilesToMol
RDKIT_SMILESPARSE_EXPORT RWMol * SmilesToMol(const std::string &smi, const SmilesParserParams &params)
RDKit::SubstructLibrary::SubstructLibrary
SubstructLibrary()
Definition: SubstructLibrary.h:367
ExplicitBitVect
a class for bit vectors that are densely occupied
Definition: ExplicitBitVect.h:29