Interpret

Submodule with freestanding functions yielding Molecule or Graph instances from Cartesian coordinate data (and optionally bond order data).

Bond discretization

In the discretization of fractional bond orders to classic integer internal bond types (e.g. single, double, etc.), there are two options. You can choose to round bond orders to the nearest integer, but this is particularly error prone for particularly weakly-bound metal ligands (around 0.5) and aromatic bonds (around 1.5). For instance, two adjacent aromatic bonds that both show a fractional bond order around 1.5 may be randomly rounded up or down depending on the bond order generation method or its particular conformation. This can cause unexpected ranking inequivalency / equivalency artifacts. If you expect there to be conjugated systems or transition metals in your set of interpreted molecules, discretizing bond orders in this fashion is currently disadvised.

It can instead be preferable to discretize bond orders in a purely binary manner, i.e. bond orders are interpreted as a single bond if the fractional bond order is is more than or equal to 0.5. Double bond stereocenters (i.e. in organic molecules E/Z stereocenters) are still interpreted from coordinate information despite the main bond type discretized to a single bond.

class scine_molassembler.interpret.BondDiscretization

Specifies the algorithm used to discretize floating-point bond orders into discrete bond types.

Members:

Binary : All bond orders >= 0.5 are considered single bonds

RoundToNearest : Round bond orders to nearest integer

Binary = BondDiscretization.Binary
RoundToNearest = BondDiscretization.RoundToNearest
property name

handle) -> str

Type

(self

class scine_molassembler.interpret.ComponentMap

Represents a map from an atom collection to the component molecules

class ComponentIndexPair
property atom_index
property component
apply(*args, **kwargs)

Overloaded function.

  1. apply(self: scine_molassembler.interpret.ComponentMap, index: int) -> scine_molassembler.interpret.ComponentMap.ComponentIndexPair

    Returns an object like a named tuple of the component and new index after transformation by the map

    >>> m = ComponentMap([0, 1, 1, 0, 1])
>>> m.apply(0)
(component=0, index=0)

  2. apply(self: scine_molassembler.interpret.ComponentMap, atom_collection: Scine::Utils::AtomCollection) -> List[Scine::Utils::AtomCollection]

    Splits an atom collection just like an interpret split the positions into multiple molecules

    param atom_collection

    The atom collection to split

    rtype

    List of atom collections

invert(*args, **kwargs)

Overloaded function.

  1. invert(self: scine_molassembler.interpret.ComponentMap, pair: scine_molassembler.interpret.ComponentMap.ComponentIndexPair) -> int

    Invert a ComponentIndexPair to the original index

    >>> m = ComponentMap([0, 1, 1, 0, 1])
>>> pair = m.apply(0)
>>> m.invert(pair)
0
>>> assert all([m.invert(m.apply(a)) == a for a in range(len(m))])

  2. invert(self: scine_molassembler.interpret.ComponentMap, component: int, atom_index: int) -> int

Two-arg component and atom index inversion convenience function

  1. invert(self: scine_molassembler.interpret.ComponentMap, component_index_tuple: Tuple[int, int]) -> int

component and atom index tuple inversion convenience function

  1. invert(self: scine_molassembler.interpret.ComponentMap) -> List[List[int]]

    Inverts the component mapping.

    Allows direct determination of the original index of a component’s atom within the coordinate set used in interpretation.

    returns

    A nested list that contains the original indices for each component.

    >>> m = ComponentMap([0, 1, 1, 0, 1]) # 0->0, 1->1, 2->1, etc.
>>> m.invert()
[[0, 3], [1, 2, 4]]
class scine_molassembler.interpret.GraphsResult

Result type of a graph interpret call.

property component_map

Mapping of atom indices from the original positional information to which molecule it is now part.

property graphs

Individual graphs found in the 3D information.

Return type

List of Graph

class scine_molassembler.interpret.MoleculesResult

Result type of a molceule interpret call.

property component_map

Mapping of atom indices from the original positional information to which molecule it is now part.

property molecules

Individual molecules found in the 3D information.

Return type

List of Molecule

scine_molassembler.interpret.bad_haptic_ligand_bonds(atom_collection: Scine::Utils::AtomCollection, bond_collection: Scine::Utils::BondOrderCollection) → List[scine_molassembler.FalsePositive]

Suggest false positive haptic ligand bonds

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.

Returns

a list of FalsePositive objects

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.

scine_molassembler.interpret.graphs(atom_collection: Scine::Utils::AtomCollection, bond_orders: Scine::Utils::BondOrderCollection, discretization: scine_molassembler.interpret.BondDiscretization) → scine_molassembler.interpret.GraphsResult

Interpret graphs from element types, positional information and bond orders

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 graphs.

Parameters

  • atom_collection – Element types and positional information in Bohr units

  • bond_orders – Fractional bond orders

  • discretization – How bond fractional orders are to be discretized

Raises

ValueError – If the number of particles in the atom collection and bond order collections do not match

scine_molassembler.interpret.interpret(atom_collection: Scine::Utils::AtomCollection, discretization: scine_molassembler.interpret.BondDiscretization, stereopermutator_bond_order_threshold: Optional[float] = 1.4) → scine_molassembler.interpret.MoleculesResult

Interpret molecules from element types and positional information. Bond orders are calculated with UFF parameters.

Attempts to interpret (possibly multiple) Molecules from element types and positional information. Bond orders are calculated from atom-pairwise spatial distances using UFF parameters. 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

  • atom_collection – Element types and positional information in Bohr units

  • discretization – How bond fractional orders are to be discretized

  • stereopermutator_bond_order_threshold – If specified, limits the instantiation of BondStereopermutators onto edges whose fractional bond orders exceed the provided threshold. If None, BondStereopermutators are instantiated at all bonds.

scine_molassembler.interpret.molecules(atom_collection: Scine::Utils::AtomCollection, bond_orders: Scine::Utils::BondOrderCollection, discretization: scine_molassembler.interpret.BondDiscretization, stereopermutator_bond_order_threshold: Optional[float] = 1.4) → scine_molassembler.interpret.MoleculesResult

Interpret molecules from element types, positional information and bond orders

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 of BondStereopermutators in the Molecules can be limited to edges whose bond order exceeds a particular value.

Parameters

  • atom_collection – Element types and positional information in Bohr units

  • bond_orders – Fractional bond orders

  • discretization – How bond fractional orders are to be discretized

  • stereopermutator_bond_order_threshold – If specified, limits the instantiation of BondStereopermutators onto edges whose fractional bond orders exceed the provided threshold. If None, BondStereopermutators are instantiated at all bonds.

Raises

ValueError – If the number of particles in the atom collection and bond order collections do not match

>>> import scine_utilities as utils
>>> import numpy as np
>>> elements = [utils.ElementType.H] * 4
>>> positions = np.array([[0.0, 0.0, 0.0], [0.0, 0.71, 0.0], [2.0, 2.0, 2.0], [2.0, 2.71, 2.0]])
>>> atoms = utils.AtomCollection(elements, positions)
>>> bond_orders = utils.BondOrderCollection(4)
>>> bond_orders.set_order(0, 1, 1.0)
>>> bond_orders.set_order(2, 3, 1.0)
>>> discretization = BondDiscretization.RoundToNearest
>>> result = interpret(atoms, bond_orders, discretization)
>>> assert len(result.molecules) == 2
>>> hydrogen = Molecule()
>>> assert all([m == hydrogen for m in result.molecules])
>>> assert result.component_map == [0, 0, 1, 1]
scine_molassembler.interpret.remove_false_positives(atoms: Scine::Utils::AtomCollection, bonds: Scine::Utils::BondOrderCollection) → Scine::Utils::BondOrderCollection

Iteratively removes bonds reported by false positive detection functions

scine_molassembler.interpret.uncertain_bonds(atom_collection: Scine::Utils::AtomCollection, bond_collection: Scine::Utils::BondOrderCollection) → List[scine_molassembler.FalsePositive]

Lists bonds with uncertain shape classifications at both ends

Returns

a list of FalsePositive objects

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 probability