The visual module#

Buildamol can generate a variety of visualizations for molecules using multiple backends. The visual module is technically part of the buildamol.utils package but is documented separately here.

Visualizing from the Molecule class#

Each Molecule (and AtomGraph, and ResidueGraph) comes with a number of visualization methods that can be used to generate the below listed visualizations. So, there is no need to set them up manually, but if the user wishes to customize the visualizations, they can do so by using the visualization classes directly.

Visualizing with Plotly#

Plotly is a web-based visualization library that can be used to generate interactive plots of any kind. Buildamol uses Plotly’s 3D scatter plots to visualize molecules and their graph representations.

Visualizing with NglView#

NglView is a Python package that can be used to visualize molecules in Jupyter notebooks. If it is installed, Buildamol can use it to visualize molecules (but not their graph representations).

Visualizing with 3DMol.js#

3DMol.js is a JavaScript library that can be used to visualize molecules in Jupyter notebooks. It has a python wrapper py3Dmol that Buildamol can use (if installed) to visualize molecules (but not their graph representations).

Visualizing 2D molecules#

Buildamol can also visualize 2D molecules using the rdkit package (if installed). RDKit is a cheminformatics package that can be used to generate high quality 2D molecule schematics.

Chem2DViewer

class buildamol.utils.visual.Chem2DViewer(molecule, drawer: str = 'png', highlight_color: str = None, linewidth: float = None, atoms: str = None)[source]#

Bases: object

View a molecule in 2D using the RDKit library.

Parameters:

molecule – The molecule to view. This may be any object that holds a biopython structure e.g. a Molecule, AtomGraph, or ResidueGraph.
drawer (str) –
The 2D drawer to use. This can be any of:
- png (default, uses MolDraw2DCairo, requires cairo to be installed)
- svg (uses MolDraw2DSVG)
highlight_color (str) – The color to use for highlighting atoms and bonds (deprecated, specify a color when calling highlight_atoms or highlight_bonds instead).
linewidth (float) – The linewidth of the bonds (deprecated, specify a linewidth when calling the draw method instead).
atoms (str) – The label to use for the atoms (deprecated, specify a label when calling the label_atoms method instead). This can be any of the following: - None (element, except for carbons) - “element” (elements, even for carbons) - “serial” (the atom serial number) - “id” (the atom id / name) - “resid” (atom id + parent residue) - “off” (no label) - any function that takes an (rdkit) atom and returns a string.

draw(draw_hydrogens: bool = False, linewidth: float = 1, fontsize: float = 20, width: int = 1000, height: int = 500, background: tuple = None, **kwargs)[source]#

Generate the 2D image.

Parameters:

draw_hydrogens (bool) – Whether to draw hydrogens.
linewidth (float) – The linewidth of the bonds.
fontsize (float) – The font size of the atom labels.
width (int) – The width of the image in pixels.
height (int) – The height of the image in pixels.
background (tuple) – The background color to use. Use None for a transparent background.
**kwargs – Any additional arguments to pass to the MolDrawOptions of the RDKit drawer (either MolDraw2DSVG or MolDraw2DCairo).

Returns:

The SVG string (if drawer is “svg”) or a PIL Image (if drawer is “png”).

Return type:

str or PIL.Image.Image

highlight_atoms(*atoms, color, radius=0.3)[source]#

Highlight atoms in the molecule.

Parameters:

atoms (list) – The Atoms to highlight.
color – The color to use for highlighting. This can be either a string, a tuple of RGB values, or a callable that takes an atom and returns a color.
radius – The radius to use for highlighting. This can be a float or a callable that takes an atom and returns a float.

highlight_bonds(*bonds, color=None)[source]#

Highlight bonds in the molecule.

Parameters:

bonds (list) – The bonds (tuples of BuildAMol Atoms) to highlight.
color – The color to use for highlighting. This can be either a string or a tuple of RGB values, or a callable that takes a bond and returns a color.

highlight_residues(*residues, color)[source]#

Highlight all bonds and atoms in the given residues.

Parameters:

residues (list) – The residues (BuildAMol Residue objects) whose bonds to highlight.
color – The color to use for highlighting. This can be either a string or a tuple of RGB values, or a callable that takes a bond and returns a color.

label_atoms(func_or_mapping, rdkit: bool = None)[source]#

Generate custom atom labels

Parameters:

func_or_mapping (str, callable or dict) – If a string is provided it has to be one of the following: - “element” (elements, even for carbons) - “serial” (the atom serial number) - “id” (the atom id / name) - “resid” (atom id + parent residue) - “off” (no label) Alternatively, either a function that takes an atom and returns a string. Or a dictionary mapping atoms to strings. Only one type of key can be included in the dictionary! Supported dictionary keys are: - BuildAMol Atoms - atom serial numbers (int) - atom ids (str) (will match all atoms with that id)
rdkit (bool) – Whether the function takes an RDKit atom or a BuildAMol atom.

set_colors(_element_colors: dict)[source]#

Set the colors for the atoms.

Parameters:: _element_colors (dict) – A dictionary mapping element symbols to colors. The keys should be elementy symbols (i.e. 6 for carbon, etc.) and the values should be RGB tuples.

set_options(**kwargs)[source]#

Set the default drawing options.

Parameters:: **kwargs – Any additional arguments to pass to MolDrawOptions.

show(draw_hydrogens: bool = False, **kwargs)[source]#

Show the molecule

Parameters:

draw_hydrogens (bool) – Whether to draw hydrogens.
**kwargs – Any additional keyword arguments to pass to draw.