MolGrid object

The class that creates and controls the grid of molecules. Allows for a more advanced usage, like filtering the grid using external controls such as slider widgets. See the notebooks for examples.

class mols2grid.MolGrid(df, smiles_col='SMILES', mol_col=None, size=(130, 90), useSVG=True, prerender=False, cache_selection=False, removeHs=False, use_coords=False, coordGen=True, MolDrawOptions=None, name='default', rename=None, **kwargs)[source]

Class that handles drawing molecules, rendering the HTML document and saving or displaying it in a Jupyter Notebook.

dfpandas.DataFrame, dict or list, required

Dataframe containing a SMILES or mol column, or dictionary containing a list of SMILES, or list of dictionnaries containing a SMILES field.

smiles_colstr or None, default=”SMILES”

Name of the SMILES column in the dataframe, if available.

mol_colstr or None, default=None

Name of an RDKit molecule column. If available, coordinates and atom/bonds annotations from this will be used for depiction.

sizetuple, default=(130, 90)

The size of the drawing canvas. The cell minimum width is set to the width of the image, so if the cell padding is increased, the image will be displayed smaller.

useSVGbool, default=True

Use SVG images instead of PNG.

prerenderbool, default=False

Prerender images for the entire dataset, or generate them on-the-fly. Prerendering is slow and memory-hungry, but required when template="static" or useSVG=False.

cache_selectionbool, default=False

Restores the selection from a previous grid with the same name.

removeHsbool, default=False

Remove hydrogen atoms from the drawings.

use_coordsbool, default=False

Use the coordinates of the molecules (only relevant when an SDF file, a list of molecules or a DataFrame of RDKit molecules were used as input.)

coordGenbool, default=True

Use the CoordGen library instead of the RDKit one to depict the molecules in 2D.

MolDrawOptionsrdkit.Chem.Draw.rdMolDraw2D.MolDrawOptions or None, default=None

Drawing options. Useful for making highly customized drawings.

namestr, default=”default”

Name of the grid. Used when retrieving selections from multiple grids at the same time.

renamedict or None, default=None

Rename the properties in the final document.

kwargsobject

MolDrawOptions attributes, and the additional atomColourPalette.

Notes

On-the-fly rendering of images does not read the atom colour palette from the MolDrawOptions parameter. If this is needed, use the following:

MolGrid(df, atomColourPalette={1: (.8, 0, 1)})

Changed in version 0.1.0: Added rename parameter to replace mapping.

New in version 0.2.0: Added prerender and cache_selection parameters.

Changed in version 0.2.0: Images are now generated on-the-fly. use_coords is now False by default to avoid a systematic error when using MolGrid.from_sdf.

display(use_iframe=False, iframe_width='100%', iframe_height=None, iframe_allow='clipboard-write', iframe_sandbox='allow-scripts allow-same-origin allow-downloads allow-popups allow-modals', **kwargs)[source]

Render and display the grid in a Jupyter notebook.

Returns

view

Return type

IPython.core.display.HTML

draw_mol(mol)[source]

Draw a molecule.

filter(mask)[source]

Filters the grid using a mask (boolean array).

Parameters

mask (list, pandas.Series or numpy.ndarray) – Boolean array: True when the item should be displayed, False if it should be filtered out.

filter_by_index(indices)[source]

Filters the grid using the dataframe’s index.

classmethod from_mols(mols, **kwargs)[source]

Set up the dataframe used by mols2grid directly from a list of RDKit molecules.

Parameters

  • mols (list) – List of RDKit molecules

  • kwargs (object) – Other arguments passed on initialization

classmethod from_sdf(sdf_file, **kwargs)[source]

Set up the dataframe used by mols2grid directly from an SDFile.

Parameters

  • sdf_file (str, pathlib.Path) – Path to the SDF file (.sdf or .sdf.gz)

  • kwargs (object) – Other arguments passed on initialization

Changed in version 0.2.0: Added support for .sdf.gz files

get_selection()[source]

Retrieve the dataframe subset corresponding to your selection.

Return type

pandas.DataFrame

mol_to_img(mol)[source]

Convert an RDKit mol to an inline PNG image containing a drawing of the molecule.

render(template='interactive', **kwargs)[source]

Returns the HTML document corresponding to the “interactive” or “static” template. See to_interactive() and to_static() for the full list of arguments.

Parameters

template (str) –

What kind of grid to draw:

  • interactive

    An interactive grid that layouts the original set of molecules on several pages, allowing for selecting molecules and filtering them using text or substructure queries.

  • static

    A simple table with all molecules displayed at once, similarly to RDKit’s MolsToGridImage(). This template is mainly used for printing on paper or in a PDF file. Most of the interactive actions aren’t available.

save(output, **kwargs)[source]

Render and save the grid in an HTML document.

property template

Kind of grid displayed, one of:

  • interactive

  • static

to_interactive(subset=None, tooltip=None, tooltip_fmt='<strong>{key}</strong>: {value}', tooltip_placement='auto', transform=None, sort_by=None, use_iframe=False, truncate=True, n_items_per_page=24, selection=True, substruct_highlight=None, single_highlight=False, border='1px solid #cccccc', gap=0, pad=10, fontsize='12px', fontfamily="'DejaVu', sans-serif", textalign='center', background_color='white', hover_color='rgba(0,0,0,0.05)', custom_css=None, style=None, custom_header=None, callback=None, **kwargs)[source]

Returns the HTML document for the “interactive” template.

subset: list or None, default=None

Columns to be displayed in each cell of the grid. Each column’s value will be displayed from top to bottom in the order provided. The "img" and "mols2grid-id" columns are displayed by default, however you can still add the "img" column if you wish to change the display order.

tooltiplist, None or False, default=None

Columns to be displayed inside the tooltip. When no subset is set, all columns will be listed in the tooltip by default. Use False to hide the tooltip.

tooltip_fmtstr, default=”<strong>{key}</strong>: {value}”

Format string of each key/value pair in the tooltip.

tooltip_placementstr, default=”auto”

Position of the tooltip: auto, top, bottom, left or right.

transformdict or None, default=None

Functions applied to specific items in all cells. The dict must follow a key: function structure where the key must correspond to one of the columns in subset or tooltip. The function takes the item’s value as input and transforms it, for example:

transform={
    "Solubility": lambda x: f"{x:.2f}",
    "Melting point": lambda x: f"MP: {5/9*(x-32):.1f}°C"
}

These transformations only affect columns in subset and tooltip, and do not interfere with style.

sort_bystr or None, default=None

Sort the grid according to the following field (which must be present in subset or tooltip).

use_iframebool, default=False

Whether to use an iframe to display the grid. When the grid is displayed inside a Jupyter Notebook or JupyterLab, this will default to True.

truncate: bool, default=True/False

Whether to truncate the text in each cell if it’s too long. Defaults to True for interactive grids, False for static grid.

n_items_per_page, default=24

Number of items to display per page. A multiple of 12 is recommended for optimal display.

selectionbool, default=True

Enables the selection of molecules and displays a checkbox at the top of each cell. In the context of a Jupyter Notebook, this gives you access to your selection (index and SMILES) through mols2grid.get_selection() or MolGrid.get_selection(). In all cases, you can export your selection by clicking on the triple-dot menu.

substruct_highlightbool or None, default=None

Highlight substructure when using the SMARTS search. Active by default when prerender=False.

single_highlightbool, default=False

Highlight only the first match of the substructure query.

borderstr, default=”1px solid #cccccc”

Styling of the border around each cell.

gapint, default=0

Size in pixels of the gap between cells.

padint, default=10

Size in pixels of the cell padding.

fontsizestr, default=”12px”

Font size of the text displayed in each cell.

fontfamilystr, default=“‘DejaVu’, sans-serif”

Font used for the text in each cell.

textalignstr, default=”center”

Alignment of the text in each cell.

background_colorstr, default=”white”

Background color of a cell.

hover_colorstr, default=”rgba(0,0,0,0.05)”

Background color when hovering a cell.

custom_cssstr or None, default=None

Custom CSS properties applied to the generated HTML. Please note that the CSS will apply to the entire page if no iframe is used (see use_iframe for more details).

styledict or None, default=None

CSS styling applied to each item in a cell. The dict must follow a key: function structure where the key must correspond to one of the columns in subset or tooltip. The function takes the item’s value as input, and outputs a valid CSS styling. For example, if you want to color the text corresponding to the “Solubility” column in your dataframe:

style={"Solubility": lambda x: "color: red" if x < -5 else ""}

You can also style a whole cell using the __all__ key, the corresponding function then has access to all values for each cell:

style={"__all__": lambda x: "color: red" if x["Solubility"] < -5 else ""}
custom_headerstr or None, default=None

Custom libraries to be loaded in the header of the document.

callbackstr, callable or None, default=None

JavaScript or Python callback to be executed when clicking on an image. A dictionnary containing the data for the full cell is directly available as data in JS. For Python, the callback function must have data as the first argument to the function. All the values in the data dict are parsed as strings, except “mols2grid-id” which is always an integer. Note that fields containing spaces in their name will be replaced by hyphens, i.e. “mol weight” becomes available as data["mol-weight"].

Returns

html_document

Return type

str

Notes

If subset=None, tooltip=None, the index and image will be directly displayed on the grid while the remaining fields will be in the tooltip.

The cell width is defined by the size[0] parameter.

New in version 0.1.0: Added sort_by, custom_css, custom_header and callback arguments. Added the ability to style an entire cell with style={"__all__": <function>}.

New in version 0.2.0: Added substruct_highlight argument.

Changed in version 0.2.2: If both subset and tooltip are None, the index and image will be directly displayed on the grid while the remaining fields will be in the tooltip.

Changed in version 1.0.0: callback can now be a lambda function. If prerender=True, substructure highlighting will be automatically disabled if it wasn’t explicitely set to True instead of raising an error.

to_static(subset=None, tooltip=None, tooltip_fmt='<strong>{key}</strong>: {value}', tooltip_trigger='focus', tooltip_placement='auto', transform=None, sort_by=None, use_iframe=False, truncate=False, n_cols=5, border='1px solid #cccccc', gap=0, pad=10, fontsize='12px', fontfamily="'DejaVu', sans-serif", textalign='center', custom_css=None, style=None, custom_header=None, **kwargs)[source]

Returns the HTML document for the “static” template

subset: list or None, default=None

Columns to be displayed in each cell of the grid. Each column’s value will be displayed from top to bottom in the order provided. The "img" and "mols2grid-id" columns are displayed by default, however you can still add the "img" column if you wish to change the display order.

tooltiplist, None or False, default=None

Columns to be displayed inside the tooltip. When no subset is set, all columns will be listed in the tooltip by default. Use False to hide the tooltip.

tooltip_fmtstr, default=”<strong>{key}</strong>: {value}”

Format string of each key/value pair in the tooltip.

tooltip_triggerstr, default=”focus”

Sequence of triggers for the tooltip: click, hover or focus

tooltip_placementstr, default=”auto”

Position of the tooltip: auto, top, bottom, left or right.

transformdict or None, default=None

Functions applied to specific items in all cells. The dict must follow a key: function structure where the key must correspond to one of the columns in subset or tooltip. The function takes the item’s value as input and transforms it, for example:

transform={
    "Solubility": lambda x: f"{x:.2f}",
    "Melting point": lambda x: f"MP: {5/9*(x-32):.1f}°C"
}

These transformations only affect columns in subset and tooltip, and do not interfere with style.

sort_bystr or None, default=None

Sort the grid according to the following field (which must be present in subset or tooltip).

use_iframebool, default=False

Whether to use an iframe to display the grid. When the grid is displayed inside a Jupyter Notebook or JupyterLab, this will default to True.

truncate: bool, default=False

Whether to truncate the text in each cell if it’s too long.

n_colsint, default=5

Number of columns in the table.

borderstr, default=”1px solid #cccccc”

Styling of the border around each cell.

gapint, default=0

Size in pixels of the gap between cells.

pad: int, default=10

Size in pixels of the cell padding.

fontsizestr, default=”12pt”

Font size of the text displayed in each cell.

fontfamilystr, default=“‘DejaVu’, sans-serif”

Font used for the text in each cell.

textalignstr, default=”center”

Alignment of the text in each cell.

custom_cssstr or None, default=None

Custom CSS properties applied to the generated HTML. Please note that the CSS will apply to the entire page if no iframe is used (see use_iframe for more details).

styledict or None, default=None

CSS styling applied to each item in a cell. The dict must follow a key: function structure where the key must correspond to one of the columns in subset or tooltip. The function takes the item’s value as input, and outputs a valid CSS styling. For example, if you want to color the text corresponding to the “Solubility” column in your dataframe:

style={"Solubility": lambda x: "color: red" if x < -5 else ""}

You can also style a whole cell using the __all__ key, the corresponding function then has access to all values for each cell:

style={"__all__": lambda x: "color: red" if x["Solubility"] < -5 else ""}
custom_headerstr or None

Custom libraries to be loaded in the header of the document

Returns

html_document

Return type

str

Notes

If subset=None, tooltip=None, the index and image will be directly displayed on the grid while the remaining fields will be in the tooltip.

New in version 0.1.0: Added the ability to style an entire cell with style={"__all__": <function>}

New in version 0.2.2: Added sort_by, custom_css, custom_header arguments.

Changed in version 0.2.2: If both subset and tooltip are None, the index and image will be directly displayed on the grid while the remaining fields will be in the tooltip.