Molassembler  3.0.0
Molecule graph and conformer library
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Scine::Molassembler::Interpret Namespace Reference

Given Cartesian coordinates, construct graphs or molecules. More...

Data Structures

struct  ComponentMap
 Type used to represent a map from an atom collection index to an interpreted object. More...
 
struct  MoleculesResult
 Result type of an interpret call. More...
 
struct  GraphsResult
 Result type of a graph interpret call. More...
 
struct  FalsePositive
 Fn result datatype. More...
 

Enumerations

enum  BondDiscretizationOption { BondDiscretizationOption::Binary, BondDiscretizationOption::RoundToNearest }
 How floating-point bond orders are discretized into bond types. More...
 

Functions

MoleculesResult molecules (const Utils::ElementTypeCollection &elements, const AngstromPositions &angstromWrapper, const Utils::BondOrderCollection &bondOrders, BondDiscretizationOption discretization=BondDiscretizationOption::Binary, const boost::optional< double > &stereopermutatorThreshold=1.4)
 The function that actually does all the work with the library-internal wrapper. More...
 
MoleculesResult molecules (const Utils::ElementTypeCollection &elements, const AngstromPositions &angstromWrapper, BondDiscretizationOption discretization=BondDiscretizationOption::Binary, const boost::optional< double > &stereopermutatorThreshold=1.4)
 Interpret a molecule from positional information only. Calculates bond orders using Utils' BondDetector class. More...
 
MoleculesResult molecules (const Utils::AtomCollection &atomCollection, const Utils::BondOrderCollection &bondOrders, BondDiscretizationOption discretization=BondDiscretizationOption::Binary, const boost::optional< double > &stereopermutatorThreshold=1.4)
 Interpret molecules from element types, positional information and a bond order collection. More...
 
MoleculesResult molecules (const Utils::AtomCollection &atoms, const Utils::BondOrderCollection &periodicBonds, const std::unordered_set< unsigned > &uninterestingAtoms, const std::unordered_map< unsigned, unsigned > &ghostAtomMap, BondDiscretizationOption discretization=BondDiscretizationOption::Binary, const boost::optional< double > &stereopermutatorThreshold=1.4)
 Interpret molecules of a periodic system. More...
 
MoleculesResult molecules (const Utils::AtomCollection &atomCollection, BondDiscretizationOption discretization=BondDiscretizationOption::Binary, const boost::optional< double > &stereopermutatorThreshold=1.4)
 Interpret molecules from Cartesian coordinates. More...
 
GraphsResult graphs (const Utils::ElementTypeCollection &elements, const AngstromPositions &angstromWrapper, const Utils::BondOrderCollection &bondOrders, BondDiscretizationOption discretization=BondDiscretizationOption::Binary)
 The function that actually does all the work with the library-internal wrapper. More...
 
GraphsResult graphs (const Utils::AtomCollection &atomCollection, const Utils::BondOrderCollection &bondOrders, BondDiscretizationOption discretization=BondDiscretizationOption::Binary)
 Interpret graphs from element types, positional information and a bond order collection. More...
 
std::vector< FalsePositiveuncertainBonds (const Utils::AtomCollection &atomCollection, const Utils::BondOrderCollection &bondOrders)
 Suggests false positives from a binary interpretation of bond orders. More...
 
std::vector< FalsePositivebadHapticLigandBonds (const Utils::AtomCollection &atomCollection, const Utils::BondOrderCollection &bondOrders)
 Suggests false positive haptic ligand bonds from a binary interpretation of bond orders. More...
 
Utils::BondOrderCollection removeFalsePositives (const Utils::AtomCollection &atoms, Utils::BondOrderCollection bonds)
 Iteratively applies false positive detection schemes. More...
 

Detailed Description

Given Cartesian coordinates, construct graphs or molecules.

Enumeration Type Documentation

How floating-point bond orders are discretized into bond types.

Enumerator
Binary 

All bond orders >= 0.5 are considered single bonds.

RoundToNearest 

Bond orders are rounded to the nearest integer.

Function Documentation

std::vector<FalsePositive> Scine::Molassembler::Interpret::badHapticLigandBonds ( const Utils::AtomCollection &  atomCollection,
const Utils::BondOrderCollection &  bondOrders 
)

Suggests false positive haptic ligand bonds from a binary interpretation of bond orders.

Generates a plane of best fit for each haptic ligand in the interpreted graphs. If the angle of the normal of this plane to the axis defined by the central atom and the site centroid is more than 30 degrees, tries to name a single bond whose removal improves the interpretation.

Note
Suggested bonds can disconnect haptic sites. When making changes to a bond order matrix based on suggestions from this function, apply them one at a time based on the highest probability received. Additionally, if multiple bonds must be removed to make a haptic ligand geometrically reasonable, you will need to iteratively call this function and alter suggested bond orders.
GraphsResult Scine::Molassembler::Interpret::graphs ( const Utils::ElementTypeCollection &  elements,
const AngstromPositions &  angstromWrapper,
const Utils::BondOrderCollection &  bondOrders,
BondDiscretizationOption  discretization = BondDiscretizationOption::Binary 
)

The function that actually does all the work with the library-internal wrapper.

Complexity \(\Theta(M)\) graph instantiations for each connected component found of at least linear complexity each

Parameters
elementsElement type collection
angstromWrapperPositional information in Angstrom units
bondOrdersBond orders
discretizationHow to discretize fractional bond orders
Exceptions
invalid_argumentIf the number of particles in the element collection, angstrom wrapper or bond order collection do not match.
Returns
A list of found graphs and an index mapping to each graph
GraphsResult Scine::Molassembler::Interpret::graphs ( const Utils::AtomCollection &  atomCollection,
const Utils::BondOrderCollection &  bondOrders,
BondDiscretizationOption  discretization = BondDiscretizationOption::Binary 
)

Interpret graphs from element types, positional information and a bond order collection.

Attempts to interpret (possibly multiple) graphs from element types, positional information and a bond order collection. Bond orders are discretized into bond types. Connected components within the space are identified and individually instantiated into Molecules.

Parameters
atomCollectionElement types and positional information in Bohr units.
bondOrdersFractional bond orders
discretizationDecide how bond orders are discretized into bond types
Exceptions
invalid_argumentIf the number of particles in the atom collection and bond order collection do not match.
Note
Assumes that the provided atom collection's positions are in Bohr units.
MoleculesResult Scine::Molassembler::Interpret::molecules ( const Utils::ElementTypeCollection &  elements,
const AngstromPositions &  angstromWrapper,
const Utils::BondOrderCollection &  bondOrders,
BondDiscretizationOption  discretization = BondDiscretizationOption::Binary,
const boost::optional< double > &  stereopermutatorThreshold = 1.4 
)

The function that actually does all the work with the library-internal wrapper.

Complexity \(\Theta(M)\) molecule instantiations for each connected component found of at least linear complexity each

Parameters
elementsElement type collection
angstromWrapperPositional information in Angstrom units
bondOrdersBond orders
discretizationHow to discretize fractional bond orders
stereopermutatorThresholdFrom which fractional bond order on to try the interpretation of bond stereopermutator. If set as boost::none, no bond stereopermutators are interpreted.
Exceptions
invalid_argumentIf the number of particles in the element collection, angstrom wrapper or bond order collection do not match.
Returns
A list of found molecules and an index mapping to each molecule
MoleculesResult Scine::Molassembler::Interpret::molecules ( const Utils::ElementTypeCollection &  elements,
const AngstromPositions &  angstromWrapper,
BondDiscretizationOption  discretization = BondDiscretizationOption::Binary,
const boost::optional< double > &  stereopermutatorThreshold = 1.4 
)

Interpret a molecule from positional information only. Calculates bond orders using Utils' BondDetector class.

Parameters
elementsElement type collection
angstromWrapperPositional information in Angstrom units
discretizationHow to discretize fractional bond orders
stereopermutatorThresholdFrom which fractional bond order on to try the interpretation of bond stereopermutator. If set as boost::none, no bond stereopermutators are interpreted.
Exceptions
invalid_argumentIf the number of particles in the element collection and angstrom wrapper do not match.
Returns
A list of found molecules and an index mapping to each molecule
MoleculesResult Scine::Molassembler::Interpret::molecules ( const Utils::AtomCollection &  atomCollection,
const Utils::BondOrderCollection &  bondOrders,
BondDiscretizationOption  discretization = BondDiscretizationOption::Binary,
const boost::optional< double > &  stereopermutatorThreshold = 1.4 
)

Interpret molecules from element types, positional information and a bond order collection.

Attempts to interpret (possibly multiple) Molecules from element types, positional information and a bond order collection. Bond orders are discretized into bond types. Connected components within the space are identified and individually instantiated into Molecules. The instantiation behavior of BondStereopermutators in the Molecules can be limited to edges whose bond order exceeds a particular value.

Parameters
atomCollectionElement types and positional information in Bohr units.
bondOrdersFractional bond orders
discretizationDecide how bond orders are discretized into bond types
stereopermutatorThresholdIf specified, limits the instantiation of BondStereopermutators onto edges whose fractional bond orders exceed the provided threshold. If this is not desired, specify boost::none.
Exceptions
invalid_argumentIf the number of particles in the atom collection and bond order collection do not match.
Note
Assumes that the provided atom collection's positions are in Bohr units.
MoleculesResult Scine::Molassembler::Interpret::molecules ( const Utils::AtomCollection &  atoms,
const Utils::BondOrderCollection &  periodicBonds,
const std::unordered_set< unsigned > &  uninterestingAtoms,
const std::unordered_map< unsigned, unsigned > &  ghostAtomMap,
BondDiscretizationOption  discretization = BondDiscretizationOption::Binary,
const boost::optional< double > &  stereopermutatorThreshold = 1.4 
)

Interpret molecules of a periodic system.

Interpret molecules into a simplified representation of structures with periodic boundary conditions.

Parameters
atomsAtom collection with ghost atoms
periodicBondsBond orders including extra bonds to ghost atoms
uninterestingAtomsList of atoms for which to skip shape classification and stereopermutator instantiation.
ghostAtomMapMap from ghost atom indices to their base atom
discretizationDecide how bond orders are discretized into bond types
stereopermutatorThresholdIf specified, limits the instantiation of BondStereopermutators onto edges whose fractional bond orders exceed the provided threshold. If this is not desired, specify boost::none.
Precondition
Ghost atom indices must be a separate group of higher indices than both interesting and uninteresting atoms.
Exceptions
std::invalid_argumentIf the number of particles in the atom collection and bond order collection do not match.
Note
Assumes that the provided atom collection's positions are in Bohr units
Any molecules interpreted with uninteresting atoms cannot be passed to conformer generation routines.
Warning
Ranking across periodic boundaries is incorrect.
MoleculesResult Scine::Molassembler::Interpret::molecules ( const Utils::AtomCollection &  atomCollection,
BondDiscretizationOption  discretization = BondDiscretizationOption::Binary,
const boost::optional< double > &  stereopermutatorThreshold = 1.4 
)

Interpret molecules from Cartesian coordinates.

Attempts to interpret (possibly multiple) Molecules from element types and positional information. Bond orders are calculated from atom-pairwise spatial distances by van-der-Waals radii. The bond orders are then discretized into bond types. Connected components within the space are identified and individually instantiated into Molecules. The instantiation behavior of BondStereopermutators in the Molecules can be limited to edges whose bond order exceeds a particular value.

Parameters
atomCollectionElement types and positional information in Bohr units.
discretizationDecide how bond orders are discretized into bond types
stereopermutatorThresholdIf specified, limits the instantiation of BondStereopermutators onto edges whose fractional bond orders exceed the provided threshold
Note
Assumes that the provided atom collection's positions are in Bohr units.
Utils::BondOrderCollection Scine::Molassembler::Interpret::removeFalsePositives ( const Utils::AtomCollection &  atoms,
Utils::BondOrderCollection  bonds 
)

Iteratively applies false positive detection schemes.

Warning
Pretty darn conservative implementation, removes only a single bond from each false positive detection function call each iteration.
std::vector<FalsePositive> Scine::Molassembler::Interpret::uncertainBonds ( const Utils::AtomCollection &  atomCollection,
const Utils::BondOrderCollection &  bondOrders 
)

Suggests false positives from a binary interpretation of bond orders.

Collects instances where shape classification is uncertain. If two connected atoms are both uncertain (>= 50% probability that the point cloud could be part of a random sample), lists the bond as a possible false postive.

Warning
Do not alter both bonds if there is a bond pair that have overlapping indices. If suggested bonds overlap, remove only that bond with the higher probabiltiy.