Visualization

Visualization#

Tools for visualizing molecules and their interaction profiles.

draw(), draw_pharm(), draw_surface(), and draw_molecule() accept Surface and Pharmacophore containers directly; flat pharm_* / surf_* arrays remain supported.

Visualize pharmacophores and exit vectors with py3dmol.

shepherd_score.visualize.draw_mol(mol, removeHs=False, opacity=1.0, color_scheme=None, custom_carbon_color=None, highlight_atoms=None, dummy_atom_pos=None, add_SAS=False, width=800, height=400, view=None)[source]#

Draw a molecule (RDKit mol or XYZ string) into a py3Dmol view.

Parameters:

  • mol (Chem.Mol | str) – RDKit molecule or XYZ-format string (need not be a valid structure).

  • removeHs (bool) – Whether to strip hydrogens before drawing.

  • opacity (float) – Stick opacity for the molecule.

  • color_scheme (str, optional) – py3Dmol color scheme (e.g. 'whiteCarbon').

  • custom_carbon_color (str, optional) – Hex color or preset name for carbon atoms.

  • highlight_atoms (list of int, optional) – Atom serial indices to highlight in purple.

  • dummy_atom_pos (array-like (N, 3), optional) – Positions of dummy atoms to render as lavender spheres.

  • add_SAS (bool) – Whether to add a solvent-accessible surface.

  • width (int) – View dimensions when creating a new view.

  • height (int) – View dimensions when creating a new view.

  • view (py3Dmol.view, optional) – Existing view; if None, a new view is created and zoomed.

shepherd_score.visualize.draw_pharm(pharmacophore=None, feats=None, pharm_types=None, pharm_ancs=None, pharm_vecs=None, ev_pos=None, ev_vecs=None, opacity_features=0.9, width=800, height=400, view=None)[source]#

Draw pharmacophore features into a py3Dmol view.

Accepts a Pharmacophore container, a legacy feats dict from get_pharmacophores_dict(), or separate pharm_types / pharm_ancs / pharm_vecs arrays.

Parameters:

  • pharmacophore (Pharmacophore, optional) – Pharmacophore profile container.

  • feats (dict, optional) – Feature-family dict with 'P' positions and 'V' vectors per type.

  • pharm_types (np.ndarray, optional) – Flat pharmacophore arrays (used when feats is empty and no Pharmacophore is given).

  • pharm_ancs (np.ndarray, optional) – Flat pharmacophore arrays (used when feats is empty and no Pharmacophore is given).

  • pharm_vecs (np.ndarray, optional) – Flat pharmacophore arrays (used when feats is empty and no Pharmacophore is given).

  • ev_pos (array-like, optional) – Exit-vector anchor positions and unit vectors.

  • ev_vecs (array-like, optional) – Exit-vector anchor positions and unit vectors.

  • opacity_features (float) – Opacity of pharmacophore spheres and arrows.

  • width (int) – View dimensions when creating a new view.

  • height (int) – View dimensions when creating a new view.

  • view (py3Dmol.view, optional) – Existing view; if None, a new view is created and zoomed.

shepherd_score.visualize.draw_surface(surface=None, point_cloud=None, esp=None, opacity=0.5, radius=0.1, width=800, height=400, view=None)[source]#

Draw a molecular surface point cloud into a py3Dmol view.

Accepts a Surface container or separate point_cloud / esp arrays.

Parameters:

  • surface (Surface, optional) – Surface profile with positions and optional esp.

  • point_cloud (array-like (N, 3), optional) – Surface point positions (overrides surface.positions when given).

  • esp (np.ndarray (N,), optional) – Electrostatic potential per point (overrides surface.esp when given).

  • opacity (float) – Sphere opacity for surface points.

  • radius (float) – Sphere radius for surface points.

  • width (int) – View dimensions when creating a new view.

  • height (int) – View dimensions when creating a new view.

  • view (py3Dmol.view, optional) – Existing view; if None, a new view is created and zoomed.

shepherd_score.visualize.draw(mol, pharmacophore=None, surface=None, feats={}, pharm_types=None, pharm_ancs=None, pharm_vecs=None, point_cloud=None, esp=None, dummy_atom_pos=None, ev_pos=None, ev_vecs=None, add_SAS=False, view=None, removeHs=False, opacity=1.0, opacity_features=0.9, color_scheme=None, custom_carbon_color=None, highlight_atoms=None, width=800, height=400)[source]#

Draw molecule with pharmacophore features and surface point cloud.

Convenience wrapper around draw_mol(), draw_pharm(), and draw_surface().

Parameters:

  • mol (Chem.Mol | str) – RDKit molecule or XYZ-format string.

  • pharmacophore (Pharmacophore, optional) – Pharmacophore profile container. Takes precedence over feats and flat pharm_* arrays when given.

  • surface (Surface, optional) – Surface profile container. point_cloud / esp override container fields when explicitly provided.

  • feats (dict, optional) – Legacy pharmacophore dict from get_pharmacophores_dict().

  • pharm_types (np.ndarray, optional) – Flat pharmacophore arrays.

  • pharm_ancs (np.ndarray, optional) – Flat pharmacophore arrays.

  • pharm_vecs (np.ndarray, optional) – Flat pharmacophore arrays.

  • point_cloud (array-like (N, 3), optional) – Surface point positions.

  • esp (np.ndarray (N,), optional) – Electrostatic potential per surface point.

  • view (py3Dmol.view, optional) – Existing view; if None, a new view is created.

  • color_scheme (str | None)

  • custom_carbon_color (str | None)

  • highlight_atoms (List[int] | None)

shepherd_score.visualize.draw_sample(generated_sample, ref_mol=None, only_atoms=False, model_type='all', opacity=0.6, view=None, color_scheme=None, custom_carbon_color=None, width=800, height=400)[source]#

Draw generated ShEPhERD sample with pharmacophore features and point cloud.

Draws on surface accessible surface and electrostatics, optionally overlaid on the reference molecule.

Parameters:

  • generated_sample (dict) –

    The generated sample dictionary. Note that it does NOT use x2 and assumes shape positions are in x3. Expected format:

    {'x1': {'atoms': np.ndarray, 'positions': np.ndarray},
 'x2': {'positions': np.ndarray},
 'x3': {'charges': np.ndarray, 'positions': np.ndarray},
 'x4': {'types': np.ndarray, 'positions': np.ndarray,
        'directions': np.ndarray}}

  • ref_mol (Chem.Mol, optional) – The reference molecule with a conformer. Default is None.

  • only_atoms (bool, optional) – Whether to only draw the atoms and ignore the interaction profiles. Default is False.

  • model_type (str, optional) – One of ‘all’, ‘x2’, ‘x3’, ‘x4’. Default is ‘all’.

  • opacity (float, optional) – The opacity of the reference molecule. Default is 0.6.

  • view (py3Dmol.view, optional) – The view to draw the molecule to. If None, a new view will be created.

  • color_scheme (str, optional) – Provide a py3Dmol color scheme string (e.g., ‘whiteCarbon’).

  • custom_carbon_color (str, optional) – Provide hex color of the carbon atoms. Programmed are ‘dark slate grey’ and ‘light steel blue’.

  • width (int, optional) – The width of the view. Default is 800.

  • height (int, optional) – The height of the view. Default is 400.

shepherd_score.visualize.draw_molecule(molecule, dummy_atom_pos=None, add_SAS=False, view=None, removeHs=False, color_scheme=None, custom_carbon_color=None, opacity=1.0, opacity_features=1.0, no_surface_points=False, highlight_atoms=None, width=800, height=400)[source]#
Parameters:

  • molecule (Molecule)

  • color_scheme (Optional[str])

  • custom_carbon_color (Optional[str])

  • opacity (float)

  • opacity_features (float)

  • no_surface_points (bool)

  • highlight_atoms (Optional[List[int]])

shepherd_score.visualize.draw_pharmacophores(mol, view=None, width=800, height=400, opacity=1.0, opacity_features=1.0)[source]#

Generate the pharmacophores and visualize them.

shepherd_score.visualize.draw_atom_sample(generated_sample, ref_mol=None, feats={}, pharm_types=None, pharm_ancs=None, pharm_vecs=None, point_cloud=None, esp=None, opacity=0.6, view=None, color_scheme=None, custom_carbon_color=None, width=800, height=400)[source]#

Draw generated ShEPhERD sample with pharmacophore features and point cloud.

Draws on surface accessible surface and electrostatics, optionally overlaid on the reference molecule.

Parameters:

  • generated_sample (list) – Expects [atoms, positions] where atoms is a list of atomic numbers and positions is a list of 3D coordinates.

  • ref_mol (Chem.Mol, optional) – The reference molecule with a conformer. Default is None.

  • opacity (float, optional) – The opacity of the reference molecule. Default is 0.6.

  • view (py3Dmol.view, optional) – The view to draw the molecule to. If None, a new view will be created.

  • color_scheme (str, optional) – Provide a py3Dmol color scheme string (e.g., ‘whiteCarbon’).

  • custom_carbon_color (str, optional) – Provide hex color of the carbon atoms. Programmed are ‘dark slate grey’ and ‘light steel blue’.

  • width (int, optional) – The width of the view. Default is 800.

  • height (int, optional) – The height of the view. Default is 400.

  • feats (dict)

  • pharm_types (ndarray | None)

  • pharm_ancs (ndarray | None)

  • pharm_vecs (ndarray | None)

shepherd_score.visualize.chimera_from_mol(mol, mol_id, surf_pos=None, surf_esp=None, ev_pos=None, ev_vecs=None, save_dir='./', outputs=None, pharm_transparency=0.5, esp_norm_factor=2.0, esp_transparency_charged=0.9, esp_neutral_color_threshold=0.3, esp_transparency_neutral=0.9, surf_point_size=0.05, verbose=True)[source]#

Write ChimeraX files from an RDKit mol (and optional surface / exit-vector data).

Parameters:

  • outputs (sequence of {'x1','x2','x3','x4'}, optional) – Representations to write. Default writes all that are available.

  • mol (rdkit.Chem.Mol)

  • mol_id (str | int)

  • save_dir (str)

  • pharm_transparency (float)

  • esp_norm_factor (float)

  • esp_transparency_charged (float)

  • esp_neutral_color_threshold (float)

  • esp_transparency_neutral (float)

  • surf_point_size (float)

  • verbose (bool)

Return type:

None

shepherd_score.visualize.chimera_from_sample(generated_sample, mol_id, save_dir, model_type='all', outputs=None, pharm_transparency=0.5, esp_norm_factor=2.0, esp_transparency_charged=0.9, esp_neutral_color_threshold=0.3, esp_transparency_neutral=0.9, surf_point_size=0.05, verbose=True)[source]#

Write ChimeraX files from a generated ShEPhERD sample dict.

Parameters:

  • outputs (sequence of {'x1','x2','x3','x4'}, optional) – Representations to write. Default writes all that are available.

  • generated_sample (dict)

  • mol_id (str | int)

  • save_dir (str)

  • model_type (Literal['all', 'x2', 'x3', 'x4'])

  • pharm_transparency (float)

  • esp_norm_factor (float)

  • esp_transparency_charged (float)

  • esp_neutral_color_threshold (float)

  • esp_transparency_neutral (float)

  • surf_point_size (float)

  • verbose (bool)

Return type:

None

shepherd_score.visualize.chimera_from_atom_sample(generated_sample, mol_id, save_dir, only_dummy_atoms=False, outputs=None, pharm_transparency=0.5, verbose=True)[source]#

Write ChimeraX files from an atom-only sample [atomic_numbers, positions].

Parameters:

  • outputs (sequence of {'x1','x2','x3','x4'}, optional) – Representations to write. Default is ('x1', 'x4') (what this input can provide). If only_dummy_atoms=True, x1 is omitted.

  • generated_sample (List)

  • mol_id (str | int)

  • save_dir (str)

  • only_dummy_atoms (bool)

  • pharm_transparency (float)

  • verbose (bool)

Return type:

None

shepherd_score.visualize.chimera_from_molecule(molec, mol_id, save_dir, outputs=None, pharm_transparency=0.5, esp_norm_factor=2.0, esp_transparency_charged=0.9, esp_neutral_color_threshold=0.3, esp_transparency_neutral=0.9, surf_point_size=0.05, dummy_atom_pos=None, output_mol_file='sdf', verbose=True)[source]#

Write ChimeraX files from a Molecule object.

Parameters:

  • outputs (sequence of {'x1','x2','x3','x4'}, optional) – Representations to write. Default writes all that are available.

  • molec (Molecule)

  • mol_id (str | int)

  • save_dir (str)

  • pharm_transparency (float)

  • esp_norm_factor (float)

  • esp_transparency_charged (float)

  • esp_neutral_color_threshold (float)

  • esp_transparency_neutral (float)

  • surf_point_size (float)

  • dummy_atom_pos (Optional[np.ndarray])

  • output_mol_file (Literal['sdf', 'xyz'])

  • verbose (bool)

Return type:

None

shepherd_score.visualize.draw_2d_valid(ref_mol, mols, mols_per_row=5, use_svg=True, find_atomic_overlap=True)[source]#

Draw 2D grid image of the reference molecule and a list of corresponding molecules. It will align the molecules to the reference molecule using the MCS and highlight the maximum common substructure between the reference molecule and the other molecules.

Parameters:

  • ref_mol (Chem.Mol) – The reference molecule to align the other molecules to.

  • mols (List[Chem.Mol | None]) – The list of molecules to draw.

  • mols_per_row (int) – The number of molecules to draw per row.

  • use_svg (bool) – Whether to use SVG for the image.

  • find_atomic_overlap (bool)

Returns:

  • MolsToGridImage – The image of the molecules.

  • Credit

  • ——

  • https (//github.com/PatWalters/practical_cheminformatics_tutorials/)

shepherd_score.visualize.draw_2d_highlight(mol, atom_sets, colors=None, label=None, compute_2d_coords=True, add_stereo_annotation=True, width=800, height=600, embed_display=True)[source]#

Create an SVG representation of the molecule with highlighted atom sets.

Parameters:

  • mol (Chem.Mol) – The molecule to draw.

  • atom_sets (List[List[int]]) – The list of atom sets to highlight.

  • colors (List[str]) – The list of colors to use for the atom sets.

  • label (Literal['atomLabel', 'molAtomMapNumber', 'atomNote']) – The label to use for the atom indices.

  • width (int) – The width of the SVG image.

  • height (int) – The height of the SVG image.

  • compute_2d_coords (bool)

  • add_stereo_annotation (bool)

  • embed_display (bool)

Returns:

SVG

Return type:

The SVG representation of the molecule with highlighted atom sets.

shepherd_score.visualize.mol_with_atom_index(mol, label='atomLabel')[source]#
Parameters:

  • mol (rdkit.Chem.Mol)

  • label (Literal['atomLabel', 'molAtomMapNumber', 'atomNote'])

shepherd_score.visualize.view_sample_trajectory(generated_sample, trajectory='x', frame_sleep=0.05, ref_mol=None, only_atoms=True, opacity=0.6, color_scheme=None, custom_carbon_color=None, width=800, height=400)[source]#

View the trajectory of the generated sample. Must set store_trajectory=True or store_trajectory_x0=True in the generate function.

Parameters:

  • trajectory (Literal['x', 'x0'])

  • frame_sleep (float)

  • color_scheme (str | None)

  • custom_carbon_color (str | None)