Simple usage

The most straightforward way to use mols2grid! For a more advanced usage, see MolGrid.

mols2grid.display(arg, **kwargs)[source]

mols2grid.display(df: dict, **kwargs)

mols2grid.display(df: pandas.core.frame.DataFrame, **kwargs)

mols2grid.display(sdf: pathlib.Path, **kwargs)

mols2grid.display(sdf: str, **kwargs)

mols2grid.display(mols: tuple, **kwargs)

mols2grid.display(mols: list, **kwargs)

mols2grid.display(mols: pandas.core.series.Series, **kwargs)

Display molecules on an interactive grid.

argpandas.DataFrame, SDF file or list of molecules: The input containing your molecules.
smiles_colstr or None, default=”SMILES”: If a pandas dataframe is used, name of the column with SMILES.
mol_colstr or None, default=None: If a pandas dataframe is used, name of the column with RDKit molecules. If available, coordinates and atom/bonds annotations from this will be used for depiction.

templatestr, default=”interactive”

Either "interactive" or "static". See render() for more details.

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.

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”

Only available for the “static” template. 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).

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

Only available for the “interactive” template. Number of items to display per page. A multiple of 12 is recommended for optimal display.

n_colsint, default=5

Only available for the “static” template. Number of columns in the table.

selectionbool, default=True

Only available for the “interactive” template. 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.

cache_selectionbool, default=False

Only available for the “interactive” template. Restores the selection from a previous grid with the same name.

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.

iframe_widthstr, default=”100%

Width of the iframe

iframe_heightint or None, default=None

Height of the frame. When set to None, the height is set dynamically based on the content.

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.
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”

Only available for the “interactive” template. Background color of a cell.

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

Only available for the “interactive” template. 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 ""}

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.
custom_headerstr or None, default=None: Custom libraries to be loaded in the header of the document.
callbackstr, callable or None, default=None: Only available for the “interactive” template. 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: view
Return type: IPython.core.display.HTML

Notes

You can also directly use RDKit’s MolDrawOptions parameters as arguments. Additionally, atomColourPalette is available to customize the atom palette if you’re not prerendering image (prerender=False).

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.

mols2grid.save(arg, **kwargs)[source]

mols2grid.save(df: pandas.core.frame.DataFrame, **kwargs)

mols2grid.save(sdf: pathlib.Path, **kwargs)

mols2grid.save(sdf: str, **kwargs)

mols2grid.save(mols: tuple, **kwargs)

mols2grid.save(mols: list, **kwargs)

mols2grid.save(mols: pandas.core.series.Series, **kwargs)

Generate an interactive grid of molecules and save it.

Parameters

arg (pandas.DataFrame, SDF file or list of molecules) – The input containing your molecules.
output (str) – Name and path of the output document.

Notes

See display() for the full list of arguments.

mols2grid.get_selection(name=None)

Returns the selection for a specific MolGrid instance

Parameters: name (str or None) – Name of the grid to fetch the selection from. If None, the most recently updated grid is returned