mols2grid is an interactive chemical viewer for 2D structures of small molecules, based on RDKit.
β‘οΈ Try the demo notebook on Google Colab, or the more advanced notebook from the RDKit UGM 2021.
mols2grid was developped for Python 3.7+ and requires rdkit (>=2020.03.1), pandas and jinja2 as dependencies.
The easiest way to install it is from conda:
conda install -c conda-forge mols2grid
Alternatively, you can also use pip:
pip install mols2grid
It is fully compatible with Jupyter Notebook and Google Colab and can run on Streamlit.
It also works with Visual Studio notebooks and Jupyterlab, except for accessing your selection with mols2grid.get_selection()
and copying it to the clipboard, but you can still export it as a CSV or SMILES file.
You can also use mols2grid directly in KNIME, by looking for the `Interactive Grid of Molecules` component on the Knime HUB.
Make sure you have setup Knime's Python integration for the node to work.
import mols2grid
mols2grid.display("path/to/molecules.sdf",
# RDKit's MolDrawOptions parameters
fixedBondLength=25,
# rename fields for the output document
rename={"SOL": "Solubility",
"SOL_classification": "Class",
"NAME": "Name"},
# set what's displayed on the grid
subset=["ID", "img", "Solubility"],
# set what's displayed on the tooltips
tooltip=["Name", "smiles", "Class", "Solubility"],
# style for the grid labels and tooltips
style={"Solubility": lambda x: "color: red" if x < -3 else "color: black"},
# change the precision and format (or other transformations)
transform={"Solubility": lambda x: f"{x:+.2f}"})
You can setup the grid from various inputs:
- a pandas DataFrame (with a column of SMILES or RDKit molecules, controlled by the
smiles_col
andmol_col
parameters), - a list of RDKit molecules (with properties accessible through the
mol.GetPropsAsDict()
method), - or an SDF file (
.sdf
or.sdf.gz
)
You can also rename each field of your input with the rename
parameter. Please note that 3 fields are automatically added regardless of your input: mols2grid-id
, SMILES
and img
. If a "SMILES" field already exists, it will not be overwritten.
useSVG=True
: use SVG images or PNGcoordGen=True
: use the coordGen library instead of the RDKit one to depict the molecules in 2DremoveHs=False
: remove explicit hydrogen atoms from the drawingssize=(160, 120)
: size of each imageuse_coords=False
: use the coordinates of the input molecules if availableMolDrawOptions=None
: RDKit's MolDrawOptions class. Useful for making highly customized drawings. You can also leave this toNone
, and directly use the attributes of this class as parameters likeaddStereoAnnotation=True
. Additionally,atomColourPalette
is made available to modify the color palette if you are not prerendering images.prerender=False
: Prerender images for the entire dataset, or generate them on-the-fly when neededcache_selection=False
: Restores the selection from a previous grid with the same name.
You can control the general look of the document through the template
argument:
template="pages"
(default) which is displayed above. It integrates nicely with Jupyter notebooks and has a search bartemplate="table"
, which displays the full list of molecules (no pages). Useful if you ever need to print the full list of molecules on paper (or print to PDF)
Both templates can be configured with the same parameters (a lot of which are CSS declarations).
For the pages
template, the following parameters are available:
subset=None
: list or None
Columns to be displayed in each cell of the grid. Each column's value will be displayed from top to bottom in the same order given here. Use"img"
for the image of the molecule. Default: all columns (with "img" in first position)tooltip=None
: list or None
Columns to be displayed as a tooltip when hovering/clicking on the image of a cell. UseNone
for no tooltip.tooltip_fmt="<strong>{key}</strong>: {value}"
: str
Format string of each key/value pair in the tooltiptooltip_trigger="click hover"
: str
Sequence of triggers for the tooltip: (click, hover, focus)tooltip_placement="bottom"
: str
Position of the tooltip: auto, top, bottom, left, rightn_cols=5
: int
Number of columns per pagen_rows=3
: int
Number of rows per pageborder="1px solid #cccccc"
: str
Styling of the border around each cell (CSS)gap=0
: int Size of the margin around each cell in pxfontsize="12pt"
: str
Font size of the text displayed in each cell (CSS)fontfamily"'DejaVu', sans-serif"
: str
Font used for the text in each cell (CSS)textalign="center"
: str
Alignment of the text in each cell (CSS)hover_color="#e7e7e7"
: str
Background color when hovering a cell (CSS)style=None
: dict or None
CSS styling applied to each item in a cell. The dict must follow akey: function
structure where the key must correspond to one of the columns insubset
ortooltip
. 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:You can also style a whole cell usingstyle={"Solubility": lambda x: "color: red" if x < -3 else ""}
__all__
as a key, the corresponding function then has access to all values for each cell:style={"__all__": lambda x: "background-color: yellow" if x["Solubility"] < -5 else ""}
transform=None
: dict or None
Functions applied to specific items in all cells. The dict must follow akey: function
structure where the key must correspond to one of the columns insubset
ortooltip
. The function takes the item's value as input and transforms it. For example, to round the "Solubility" to 2 decimals, and display the "Melting point" in Celsius instead of Fahrenheit with a single digit precision and some text before ("MP") and after ("Β°C") the value:These transformations only affect columns intransform={"Solubility": lambda x: f"{x:.2f}", "Melting point": lambda x: f"MP: {5/9*(x-32):.1f}Β°C"}
subset
andtooltip
and do not interfere withstyle
.selection=True
: bool
Enables the selection of molecules using a checkbox. Only usefull in the context of a Jupyter notebook. You can retrieve your selection of molecules (index and SMILES) throughmols2grid.get_selection()
cache_selection=False
: bool Restores the selection from a previous grid with the same name ifTrue
custom_css=None
: str or None
Custom CSS properties applied to the content of the HTML documentcustom_header=None
: str or None
Custom libraries (CSS or JS) to be loaded in the header of the documentcallback=None
: str or callable
JavaScript or Python callback to be executed when clicking on an image. A dictionnary containing the data for the full cell is directly available asdata
in JS. For Python, the callback function must havedata
as the first argument to the function. All the values in thedata
dict are parsed as strings, except "mols2grid-id" which is always an integer.sort_by=None
: str or None
Sort the grid according to the following field (which must be present insubset
ortooltip
).substruct_highlight=True
: bool Highlight the query when using a SMARTS substructure search. Only available whenprerender=False
.
Less options are available for the table
template, you can check the complete list of arguments with help(mols2grid.MolGrid.to_table)
You can either:
- save the grid with
mols2grid.save(input, output="path/grid.html", ...)
. The file that is generated is a standalone HTML document that should work with most web browsers. - display it directly in a Jupyter notebook with
mols2grid.display(...)
(optionnal argument:width="100%"
,height=None
)
- Simple example by iwatobipen
- Creating a web app with Streamlit for filtering datasets:
- Blog post by Justin Chavez
- Video tutorial by Data Professor
- Viewing clustered chemical structures and Exploratory data analysis by Pat Walters
- Advanced notebook (RDKit UGM 2021)
- @fredrikw (contributor)
- @JustinChavez (contributor)
- @hadim (conda feedstock maintainer)
Unless otherwise noted, all files in this directory and all subdirectories are distributed under the Apache License, Version 2.0:
Copyright 2021-2022 CΓ©dric BOUYSSET
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.