Rendering¶

MolPlotter¶

class chemFilters.img_render.MolPlotter(from_smi=False, size=(300, 300), cmap='rainbow', font_name='Telex-Regular', label_font_size=None, mol_font_size=None, n_jobs=1, chunk_size=None, bond_line_width=2.0, no_atom_labels=False, add_atom_indices=False, add_bond_indices=False, annotation_font_scale=None, explicit_methyl=False, unspecified_stereo_unknown=False, bg_transparent=False, bw=False, **kwargs)[source]¶

Bases: MoleculeHandler

MolPlotter class to render molecules into images. It uses RDKit’s DrawMolecule method to generate the images. The images can be rendered with labels and/or substructure matches.

Parameters:

from_smi (bool)
size (tuple)
cmap (str)
font_name (str)
label_font_size (int)
mol_font_size (int)
n_jobs (int)
chunk_size (int)
bond_line_width (float)
no_atom_labels (bool)
add_atom_indices (bool)
add_bond_indices (bool)
annotation_font_scale (float)
explicit_methyl (bool)
unspecified_stereo_unknown (bool)
bg_transparent (bool)
bw (bool)

_from_smi¶: output images directly from smiles. Defaults to False.

_cmap¶: colormap for render_with_color method. Defaults to “rainbow”.

_size¶: size of the output images. Defaults to (300, 300).

_mol_font_size¶: custom font size on the rendered molecules. Defaults to None.

_label_font_size¶: custom font size for the label of the molecules, if any. Defaults to None.

_annotation_font_scale¶: scale factor for the font size of the annotations.

_font_name¶: : font name found by img_render.FondManager class. Defaults to “DejaVu Sans”.

_n_jobs¶: number of jobs to run in parallel. Defaults to 1.

_bg_transparent¶: render the background as transparent. Defaults to False.

d2d_params¶: dictionary with the parameters to be passed to get_d2d method.

available_fonts¶: dictionary with fonts available in the system and in matplotlib

__init__(from_smi=False, size=(300, 300), cmap='rainbow', font_name='Telex-Regular', label_font_size=None, mol_font_size=None, n_jobs=1, chunk_size=None, bond_line_width=2.0, no_atom_labels=False, add_atom_indices=False, add_bond_indices=False, annotation_font_scale=None, explicit_methyl=False, unspecified_stereo_unknown=False, bg_transparent=False, bw=False, **kwargs)[source]¶

Initialize the MolPlotter class. The class is used to render molecules into either .sdf or .png files. It uses RDKit’s DrawMolecule method to generate the images and self.d2d_params to set the parameters for the rendering process.

Parameters:

from_smi (bool) – if true, methods will treat inputs as smiles. Defaults to False.
size (tuple) – size of the image to de displayed. Defaults to (300, 300).
cmap (str) – colormap for the structure matching. Defaults to “rainbow”.
font_name (str) – font used on molecules’ legends. Defaults to “DejaVu Sans”.
label_font_size (int) – custom font size for the label of the molecules, if any. Defaults to None.
mol_font_size (int) – custom font size on the rendered molecules. Defaults to None.
n_jobs (int) – number of jobs to run in parallel. Defaults to 1.
chunk_size (int) – size of chunks for ParallelApplier. If None, auto-calculated. Defaults to None.
bond_line_width (MolDraw2DCairo) – width of bond lines. Defaults to 2.0.
no_atom_labels (MolDraw2DCairo) – do not add atom labels to the rendered mol.
add_atom_indices (MolDraw2DCairo) – add atom indices to the rendered mols. Defaults to False.
add_bond_indices (MolDraw2DCairo) – add bond indices to the rendered mols. Defaults to False.
annotation_font_scale (float) – scale factor for the font size of the annotations. Defaults to None
explicit_methyl (MolDraw2DCairo) – explicitly displays a methil as CH3. Defaults to False.
unspecified_stereo_unknown (MolDraw2DCairo) – unspecified stereo atoms/bonds are drawn as if they were unknown. Defaults to False.
bg_transparent (bool) – render the background as transparent. Defaults to False.
bw (bool) – render the molecule as black and white. Defaults to False.
kwargs – additional keyword arguments defining extra MolDraw2D attributes, set by passing them to self.get_d2d method.

Return type:

None

property available_fonts¶

static geometric_mean(arr, axis=0)[source]¶: Calculate the geometric mean of an array. Adapted from SciPy: https://github.com/scipy/blob/v1.10.1/scipy/stats/_stats.py.py#L199=L269

get_d2d(bondLineWidth=2.0, noAtomLabels=False, addAtomIndices=False, addBondIndices=False, explicitMethyl=False, unspecifiedStereoIsUnknown=False, bw=False, svg=False, **kwargs)[source]¶

Function to get the rdkit’s MolDraw2DCairo object with the desired options.

Parameters:

bondLineWidth (float) – width of the bonds in the drawing. RDKit defaults to 2.0.
noAtomLabels (bool) – do not add atom labels to the rendered mol. Defaults to False.
addAtomIndices (bool) – add the atom indices to the rendered mol. Defaults to False.
addBondIndices (bool) – add the bond indices to the rendered mol. Defaults to False.
explicitMethyl (bool) – explicitly displays a methil as CH3. Defaults to False.
unspecifiedStereoIsUnknown (bool) – unspecified stereo atoms/bonds are drawn as if they were unknown. Defaults to False.
bw (bool) – render the molecule as black and white. Defaults to False.
svg (bool) – if True, returns a Draw.MolDraw2DSVG object. Defaults to False.
kwargs – additional keyword arguments defining extra MolDraw2D attributes.

Returns:

Draw.MolDraw2DCairo object with the desired options.

Return type:

MolDraw2DCairo

render_ACS1996(mol, mean_bond_length=None, label=None, return_svg=False, **kwargs)[source]¶

Render molecules using the ACS 1996 style. This is a mode which is designed to produce images compatible with the drawing standards for American Chemical Society (ACS) journals.

Parameters:

mol (Mol) – rdkit mol object.
mean_bond_length (float) – the mean bond length of the molecule. Defaults to None.
label (str | None) – the label to be added to the molecule. Defaults to “”.
return_svg – whether to return an svg image instead. Defaults to False.
kwargs – additional keyword arguments to be passed to the DrawMolecule method

Returns:

a PIL.Image.Image object or a string with the SVG representation in case: return_svg is True.

Return type:

Image | str

render_mol(mol, label=None, match_pose=None, return_svg=False, **kwargs)[source]¶

Plot molecules using rdMolDraw2D.MolDraw2DCairo. Keyword arguments provided will be passed into DrawMolecule method of the same class.

Parameters:

mol (Mol) – rdkit mol object.
label (str | None) – the label to be added to the molecule. Defaults to None.
match_pose (str | Mol | None) – if desired, input a SMILES, a SMARTS or a rdkit mol object to render mol into a matching position. Defaults to None.
return_svg (bool) – if you’d like to return an svg image instead. Defaults to False.
kwargs – additional keyword arguments to be passed to the DrawMolecule method

Raises:

ValueError – _description_

Returns:

a PIL.Image.Image object or a string with the SVG representation in case: return_svg is True.

Return type:

Image | str

render_with_matches(mol, substructs, label=None, match_pose=None, **kwargs)[source]¶

Render the substructures on the molecules using default RDKit coloring.

Parameters:

mol (Mol) – molecule to be rendered.
substructs – substructures output from RDKitFilters.filter_mols.
label (str | None) – if desired, add a label to the molecule. Defaults to None.
match_pose (str | Mol | None) – a common structure between smiles used to generate the matching 2D images. If None, 2D rendering won’t match. Defaults to None.
kwargs – additional keyword arguments to be passed to the DrawMolecule method

Returns:

PIL.Image.Image with the molecule and the highlighted substructures.

Return type:

Image

render_with_colored_matches(mol, descriptions, substructs, label=None, cmap='rainbow', alpha=0.5, match_pose=None, **kwargs)[source]¶

Take descriptions and substructures output from RDKitFilters.filter_mols and renders them on the molecular structure, coloring the substructures and adding labels according to the descriptions.

Note: in case of overlap between colors, the final color corresponds to the their respective geometric mean.

Parameters:

mol (Mol) – rdkit molecule object.
descriptions (List[str]) – descriptions (output[0]) from RDKitFilters.filter_mols.
substructs (List[Mol]) – substructures (output[1]) from RDKitFilters.filter_mols.
label (str | None) – if desired, add a label to the molecule. Defaults to None.
cmap (str) – colormap for the substructures. Defaults to “viridis”.
alpha (float) – transparency of the colors. Defaults to 0.5.
match_pose (str | Mol | None) – a common structure between smiles used to generate the matching 2D images. If None, 2D rendering won’t match. Defaults to None.
kwargs – additional keyword arguments to be passed to the DrawMolecule method

Returns:

matplotlib.figure.Figure and Axis with the molecule and the: highlighted substructures.

colored_matches_legend(descriptions, substructures, cmap='rainbow', alpha=0.5, ax=None)[source]¶

MolGridPlotter¶

class chemFilters.img_render.MolGridPlotter(from_smi=False, size=(300, 300), cmap='rainbow', font_name='Telex-Regular', label_font_size=None, mol_font_size=None, n_jobs=1, chunk_size=None, bond_line_width=2.0, no_atom_labels=False, add_atom_indices=False, add_bond_indices=False, annotation_font_scale=None, explicit_methyl=False, unspecified_stereo_unknown=False, bg_transparent=False, bw=False, **kwargs)[source]¶

Bases: MolPlotter

MolGridPlotter class to render molecules into grids of images. It uses RDKit’s DrawMolecule method to generate the images and PIL to patch images together. The images can be rendered with labels and/or substructure matches, similar to its parent class.

Parameters:

from_smi (bool)
size (tuple)
cmap (str)
font_name (str)
label_font_size (int)
mol_font_size (int)
n_jobs (int)
chunk_size (int)
bond_line_width (float)
no_atom_labels (bool)
add_atom_indices (bool)
add_bond_indices (bool)
annotation_font_scale (float)
explicit_methyl (bool)
unspecified_stereo_unknown (bool)
bg_transparent (bool)
bw (bool)

_from_smi¶: output images directly from smiles. Defaults to False.

_cmap¶: colormap for render_with_color method. Defaults to “rainbow”.

_size¶: size of the output images. Defaults to (300, 300).

_mol_font_size¶: custom font size on the rendered molecules. Defaults to None.

_label_font_size¶: custom font size for the label of the molecules, if any. Defaults to None.

_annotation_font_scale¶: scale factor for the font size of the annotations.

_font_name¶: : font name found by img_render.FondManager class. Defaults to “DejaVu Sans”.

_n_jobs¶: number of jobs to run in parallel. Defaults to 1.

_bg_transparent¶: render the background as transparent. Defaults to False.

d2d_params¶: dictionary with the parameters to be passed to get_d2d method.

available_fonts¶: dictionary with fonts available in the system and in matplotlib

initialize the MolGridPlotter class. The class is used to render molecules into either .sdf or .png files. It uses RDKit’s DrawMolecule method to generate the images and self.d2d_params to set the parameters for the rendering process

Parameters:

from_smi (bool) – if true, methods will treat inputs as smiles. Defaults to False.
size (tuple) – size of the image to de displayed. Defaults to (300, 300).
cmap (str) – colormap for the structure matching. Defaults to “rainbow”.
font_name (str) – font used on molecules’ legends. Defaults to “DejaVu Sans”.
label_font_size (int) – custom font size for the label of the molecules, if any. Defaults to None.
mol_font_size (int) – custom font size on the rendered molecules. Defaults to None.
n_jobs (int) – number of jobs to run in parallel. Defaults to 1.
chunk_size (int) – size of chunks for ParallelApplier. If None, auto-calculated. Defaults to None.
bond_line_width (MolDraw2DCairo) – width of bond lines. Defaults to 2.0.
no_atom_labels (MolDraw2DCairo) – do not add atom labels to the rendered mol.
add_atom_indices (MolDraw2DCairo) – add atom indices to the rendered mols. Defaults to False.
add_bond_indices (MolDraw2DCairo) – add bond indices to the rendered mols. Defaults to False.
annotation_font_scale (float) – scale factor for the font size of the annotations. Defaults to None
explicit_methyl (MolDraw2DCairo) – explicitly displays a methil as CH3. Defaults to False.
unspecified_stereo_unknown (MolDraw2DCairo) – unspecified stereo atoms/bonds are drawn as if they were unknown. Defaults to False.
bg_transparent (bool) – render the background as transparent. Defaults to False.
bw (bool) – render the molecule as black and white. Defaults to False.
kwargs – additional keyword arguments defining extra MolDraw2D attributes, set by passing them to self.get_d2d method.

Return type:

None

mol_grid_png(mols, labels=None, n_cols=None, match_pose=None, **kwargs)[source]¶

Parameters:

mols (list) – list of molecules to display.
labels (list | None) – list of labels to be written on the mol images. Defaults to None
n_cols (int) – N columns with molecules. If None, n_cols = len(smiles). Defaults to None.
match_pose (str | Mol | None) – a common structure between smiles used to generate the matching 2D images. If None, 2D rendering won’t match. Defaults to None.
kwargs – additional keyword arguments to be passed to the DrawMolecule method

Returns:

PIL.Image.Image

Return type:

Image

mol_structmatch_grid_png(mols, substructs, labels=None, n_cols=None, match_pose=None, **kwargs)[source]¶

Parameters:

mols (list) – list of molecules to display.
substructs (list) – list of substructures to be highlighted on the mol images.
labels (list | None) – list of labels to be written on the mol images. Defaults to None
n_cols (int) – N columns with molecules. If None, n_cols = len(smiles). Defaults to None.
match_pose (str | Mol | None) – a common structure between smiles used to generate the matching 2D images. If None, 2D rendering won’t match. Defaults to None.
kwargs – additional keyword arguments to be passed to the DrawMolecule method

Returns:

PIL.Image.Image

Return type:

Image

mol_structmatch_color_grid_png(mols, descriptions, substructs, labels=None, n_cols=None, match_pose=None, **kwargs)[source]¶

Parameters:

mols (list) – list of molecules to display.
descriptions (List[str]) – descriptions (output[0]) from RDKitFilters.filter_mols
substructs (List[Mol]) – substructures (output[1]) from RDKitFilters.filter_mols.
labels (list | None) – list of labels to be written on the mol images. Defaults to None
n_cols (int) – N columns with molecules. If None, n_cols = len(smiles). Defaults to None.
match_pose (str | Mol | None) – a common structure between smiles used to generate the matching 2D images. If None, 2D rendering won’t match. Defaults to None.
kwargs – additional keyword arguments to be passed to the DrawMolecule method

Returns:

PIL.Image.Image

Return type:

Image

FontManager¶

class chemFilters.img_render.FontManager(wsl='auto')[source]¶

Bases: object

Parameters:: wsl (bool | str)

__init__(wsl='auto')[source]¶

Initialize the FontManager class. It will search for fonts in the system and in matplotlib.

Parameters:: wsl (bool | str) – If you’re using windows subsystem for linux. Allows for using fonts installed in windows. Defaults to “auto”.

property operating_system¶

property available_fonts: Dict[str, Path]¶

get_font_path(font_name)[source]¶

Get the path to a specific font by name.

Parameters:: font_name (str) – Name of the font to find
Returns:: Path to the font file or None if not found
Return type:: Path | None

list_available_fonts()[source]¶

Return a list of all available font names.

Return type:: list

has_font(font_name)[source]¶

Check if a font is available.

Parameters:: font_name (str) – Name of the font to check
Returns:: True if font is available, False otherwise
Return type:: bool