Molecule

Molecule#

Molecule wraps an RDKit Mol object together with its extracted interaction profiles.

Surface and pharmacophore data are stored in Surface and Pharmacophore containers (mol.surface, mol.pharmacophore). Legacy flat attributes (surf_pos, surf_esp, pharm_types, etc.) remain for backwards compatibility. Use get_pharmacophore() with return_atom_ids / priority_atoms for priority pharmacophore labeling.

Helper functions#

shepherd_score.container._core.update_mol_coordinates(mol, coordinates)[source]#

Updates the coordinates of a 3D RDKit mol object with a new set of coordinates

Parameters:

  • mol (Chem.Mol) – RDKit mol object with 3D coordinates to be replaced

  • coordinates (Union[List, np.ndarray]) – List/array of new [x,y,z] coordinates

Returns:

mol_new – deep-copied RDKit mol object with updated 3D coordinates

Return type:

Chem.Mol

Class reference#

class shepherd_score.container._core.Molecule(mol, num_surf_points=None, density=None, probe_radius=None, surface_points=None, partial_charges=None, electrostatics=None, pharm_multi_vector=None, pharm_types=None, pharm_ancs=None, pharm_vecs=None)[source]#

Bases: object

Molecule contains ways to hold/generate molecule geometries

Parameters:
__init__(mol, num_surf_points=None, density=None, probe_radius=None, surface_points=None, partial_charges=None, electrostatics=None, pharm_multi_vector=None, pharm_types=None, pharm_ancs=None, pharm_vecs=None)[source]#

Molecule constructor to extract interaction profiles.

If partial_charges are not provided, they will be generated using MMFF94 which may result in subpar performance.

Parameters:

  • mol (rdkit.Chem.rdchem.Mol)

  • num_surf_points (Optional[int]) – Number of surface points to sample. If None, the surface point cloud is not generated. More efficient if only doing volumentric.

  • density (Optional[float]) – Density of points to sample on molecular surface. If None, the surface point cloud is not generated. More efficient if only doing volumentric. If both num_surf_points and density are not None, num_surf_points supercedes density.

  • surface_points (Optional[np.ndarray]) – Surface points if they were previously generated. Shape: (M,3).

  • probe_radius (Optional[float]) – The radius of a probe atom to act as a “solvent accessible surface”. Default is 1.2 if None is passed.

  • partial_charges (Optional[np.ndarray]) – Partial charges for each atom. Shape: (N,). If None is passed and ESP surface is generated, it will default to MMFF94 partial charges.

  • electrostatics (Optional[np.ndarray]) – Electrostatic potential if they were previously generated. Shape: (M,).

  • pharm_multi_vector (Optional[bool]) – If None, don’t generate pharmacophore, else generate pharmacophore with/without (True/False) multi-vectors.

  • pharm_types (Optional[np.ndarray]) – Types of pharmacophore. Shape: (P,).

  • pharm_ancs (Optional[np.ndarray]) – Anchor positions of pharmacophore. Shape: (P,3).

  • pharm_vecs (Optional[np.ndarray]) – Unit vectors relative to anchor positions of pharmacophore. Shape: (P,3).

property surface: Surface#

The Surface holding surface positions, ESP, and probe radius.

property surf_pos: ndarray | None#
property surf_esp: ndarray | None#
property probe_radius: float#
property pharmacophore: Pharmacophore | None#

The Pharmacophore container, or None if not generated.

property pharm_types: ndarray | None#
property pharm_ancs: ndarray | None#
property pharm_vecs: ndarray | None#
get_partial_charges()[source]#

Get the partial charges on each atom using MMFF.

Return type:

ndarray

get_positions(no_H=True)[source]#

Get atom coordinates with or without hydrogens.

Parameters:

no_H (bool, optional) – If True (default) return the cached heavy-atom coordinates (atom_pos). If False return all-atom coordinates from the conformer (including H).

Returns:

Atom coordinates. Shape: (N, 3).

Return type:

np.ndarray

get_charges(no_H=True)[source]#

Get partial charges with or without hydrogens.

This slices the already-computed partial_charges; it does not recompute them (see get_partial_charges() for MMFF computation).

Parameters:

no_H (bool, optional) – If True (default) return charges for heavy atoms only. If False return charges for all atoms (including H).

Returns:

Partial charges. Shape: (N,).

Return type:

np.ndarray

get_pc(use_density=False, atom_indices=None, radial_buffer=0.0)[source]#

Gets the point cloud positions.

Parameters:

  • use_density (bool, optional) – Whether to sample at a fixed point density instead of a fixed count. Default False.

  • atom_indices (Optional[Iterable[int]]) – If given, restricts surface generation to only these atom indices (original-mol atom-index space, same as partial_charges). None (default) uses all atoms, preserving prior behavior.

  • radial_buffer (float, optional) – Flat padding (in Angstroms) added to every atom’s vdW radius before surface generation. Default 0.0 (no change).

Return type:

Tuple[ndarray, ndarray, ndarray]

get_electrostatic_potential(atom_indices=None, surf_pos=None)[source]#

Get the electrostatic potential at each surface point.

Parameters:

  • atom_indices (Optional[Iterable[int]]) – If given, restricts the atoms (and their charges) contributing to the potential to only these indices (original-mol atom-index space, same as partial_charges). None (default) uses all atoms, preserving prior behavior.

  • surf_pos (Optional[np.ndarray]) – Surface points to evaluate the potential at. Defaults to self.surf_pos; pass an explicit array when evaluating against a freshly regenerated surface not yet assigned to self.

Return type:

ndarray

center_to(xyz_means)[source]#

If you want to center the molecule with respect to a certain coordinate frame.

Parameters:

xyz_means (ndarray)

Return type:

None

get_pharmacophore(multi_vector=True, exclude=[], check_access=False, scale=1, return_atom_ids=False, priority_atoms=None, min_ring_priority_atoms=3)[source]#

Get the pharmacophore of the molecule.

Stores the full Pharmacophore container on self (accessible via pharmacophore). The pharm_types/pharm_ancs/pharm_vecs properties delegate to it, so existing usage is unchanged.

Parameters:

  • multi_vector (bool, optional) – Whether to represent pharmacophore with multiple vectors. Default True.

  • exclude (list, optional) – Hydrogen indices to not include as a HBD. Default [].

  • check_access (bool, optional) – Check if HBD/HBA are accessible to the molecular surface. Default False.

  • scale (float, optional) – Length of a pharmacophore vector in Angstroms. Default 1.

  • return_atom_ids (bool, optional) – Retain per-pharmacophore atom-id sets on self.pharmacophore.atom_ids, enabling self.pharmacophore.priority_labels(...). Default False.

  • priority_atoms (iterable of int, optional) – When provided, priority labels are computed and stored on self.pharmacophore.labels. Default None.

  • min_ring_priority_atoms (int, optional) – Only used when priority_atoms is provided. See get_pharmacophore(). Default 3.

select_atoms(atom_indices, surface_atom_indices=None, expand_pharm_consistent=True, min_ring_priority_atoms=1, restrict_esp=True, radial_buffer=0.0, include_h=False)[source]#

Return a new Molecule whose surface, ESP, and pharmacophore data are restricted to a chosen atom subset.

Parameters:

  • atom_indices (Iterable[int]) – Seed atom indices (original-mol atom-index space, same as partial_charges and Pharmacophore.atom_ids) that drive the pharmacophore subselection. Also used for the surface/ESP restriction when surface_atom_indices is None.

  • surface_atom_indices (Optional[Iterable[int]]) – If given, used in place of atom_indices to restrict the surface/ESP – decoupling which atoms define the retained pharmacophores from which atoms the surface/ESP are regenerated over. Expanded via expand_pharm_consistent the same way atom_indices is independently.

  • expand_pharm_consistent (bool, optional) – Whether to expand atom_indices (and, independently, surface_atom_indices when given) to the pharmacophore-consistent superset via expand_atom_selection() before restricting the pharmacophore / surface / ESP. Default True.

  • min_ring_priority_atoms (int, optional) – Forwarded to the underlying Pharmacophore expansion/filtering calls. Default 1 (see expand_atom_selection()).

  • restrict_esp (bool, optional) – If True (default), the electrostatic potential is recomputed using only the selected atoms’ charges. If False, ESP is still recomputed at the restricted surface but using all atoms’ charges.

  • radial_buffer (float, optional) – Flat padding (in Angstroms) added to every retained atom’s vdW radius before regenerating the surface. Default 0.0 (no change).

  • include_h (bool, optional) – If True, the directly-bonded hydrogen neighbors of every atom in the surface/ESP atom set are added before regenerating the surface/ESP. Default False.

Returns:

A new Molecule instance; self is not modified.

Return type:

Molecule