Basic Rendering

Rendering molecules “just works” in both Jupyter and Marimo. OpenEye objects are recognized as first-class objects, so by terminating a cell with an object, it will render.

All you have to do is import cnotebook and it takes care of the rest. There are also extensive customization options if you don’t like the defaults!

Molecules

Concrete molecules, such as OEGraphMol and OEMol are straightforwardly rendered using the global rendering context (more on that later).

import cnotebook
from openeye import oechem

mol = oechem.OEMol()
oechem.OESmilesToMol(mol, "CN1C=NC2=C1C(=O)N(C(=O)N2C)C")

mol

Will output:

Query Molecules

Query molecules, such as OEQMol can also be displayed.

import cnotebook
from openeye import oechem

qmol = oechem.OEQMol()

with oechem.oemolistream("examples/assets/egfr_template.mol") as ifs:
    oechem.OEReadMDLQueryFile(ifs, qmol)

qmol

Will display:

Display Objects

Display objects store many different styling options and are handled natively.

import cnotebook
from openeye import oechem

mol = oechem.OEMol()
oechem.OESmilesToMol(mol, "CN1C=NC2=C1C(=O)N(C(=O)N2C)C")

# Calculate 2D coordinates (since we're using a display object)
oedepict.OEPrepareDepiction(mol)

# Customized display options
opts = oedepict.OE2DMolDisplayOptions(200, 200, oedepict.OEScale_AutoScale)
opts.SetAromaticStyle(oedepict.OEAromaticStyle_Circle)
opts.SetAtomColorStyle(oedepict.OEAtomColorStyle_BlackCPK)
opts.SetTitleLocation(oedepict.OETitleLocation_Bottom)

disp = oedepict.OE2DMolDisplay(mol, opts)

disp

Outputs:

Design Units

OpenEye OEDesignUnit objects are supported natively in both 2D and 3D contexts.

2D Rendering (Marimo)

In Marimo, OEDesignUnit objects are automatically formatted as 2D images when displayed in a notebook cell. The design unit title and a structure overview are rendered using the standard CNotebook rendering pipeline.

from openeye import oechem
from cnotebook.c3d import C3D

du = oechem.OEDesignUnit()
oechem.OEReadDesignUnit("examples/assets/spruce_9Q03_ABC__DU__A1CM7_C-502.oedu", du)

# Display it
du

3D Viewing (C3D)

For interactive 3D visualization of design units, use the C3D viewer:

from openeye import oechem
from cnotebook.c3d import C3D

du = oechem.OEDesignUnit()
oechem.OEReadDesignUnit("examples/assets/spruce_9Q03_ABC__DU__A1CM7_C-502.oedu", du)

viewer = (
    C3D()
    .add_design_unit(du, name="complex")
    .set_preset("sites")
    .orient("resi 502")
)
viewer.display()

The design unit’s full complex (all components) is extracted and converted to PDB format for 3Dmol.js. See C3D Interactive 3D Viewer for full documentation of the 3D viewer.

Substructure Highlighting

The highlight_smarts helper makes SMARTS highlighting fun and easy:

Single Molecule:

from cnotebook import highlight_smarts
from openeye import oechem

mol = oechem.OEGraphMol()
oechem.OESmilesToMol(mol, "c1ccc(cc1)OC(F)(F)F")

# Highlight hydroxyl group
highlight_smarts(mol, smarts="C(O)(F)(F)F")

Outputs:

Rendering Contexts

CNotebook uses contexts to control rendering style. You can also provide local rendering contexts to just about anything for extensive customizability.

Global Context

There is a single global context, which you are free to change however you like.

import cnotebook

# Get the global context
ctx = cnotebook.cnotebook_context.get()

This context object has the following attributes that can be set:

Option	Type	Default	Description
width	float	0 (auto)	Image width in pixels. When 0, determined by scale.
height	float	0 (auto)	Image height in pixels. When 0, determined by scale.
min_width	float | None	200.0	Minimum image width in pixels.
min_height	float | None	200.0	Minimum image height in pixels.
max_width	float | None	None	Maximum image width in pixels.
max_height	float | None	None	Maximum image height in pixels.
structure_scale	float	12.0	Structure scaling factor (OEScale_Default * 0.6).
atom_label_font_scale | float		1.0	Scale factor for atom labels (0.5 to 2.0).
title_font_scale	float	1.0	Scale factor for title font (0.5 to 2.0).
image_format	str	"png"	Output format: "png" or "svg".
bond_width_scaling	bool	False	Enable bond width scaling based on structure scale.
title	bool	True	Whether to display the molecule title.
callbacks	list | None	[]	Callbacks to apply to OE2DMolDisplay before render.

Here is an example of changing the global context to make all molecules a bit bigger, scale bond widths, and turn off displaying titles.

import cnotebook
from openeye import oedepict

# Get the global context
ctx = cnotebook.cnotebook_context.get()

ctx.structure_scale = 2.0 * oedepict.OEScale_Default
ctx.bond_width_scaling = True
ctx.title = False

mol = oechem.OEGraphMol()
oechem.OESmilesToMol(mol, "c1ccc(cc1)OC(F)(F)F")
mol.SetTitle("You won't see this!")

mol

Outputs:

You can always reset the global context:

ctx.reset()

This is useful if you’re interactively making lots of changes.

Local Contexts

Let’s say you only want to limit the scope of your changes. You can copy the global context to a local context and modify it however you like. One cool feature is that if you later modify a part of the global context that hasn’t been explicitly set in the local context, the change will propogate.

You can pass any renderable object (e.g., molecules or DataFrames) to cnotebook.display with an optional context and it will render.

Environment-Specific Behavior

CNotebook automatically adjusts rendering based on the environment. You can check the detected environment using the get_env() function:

import cnotebook

env = cnotebook.get_env()

print(f"IPython: {env.ipython_available} ({env.ipython_version})")
print(f"Marimo: {env.marimo_available} ({env.marimo_version})")
print(f"Pandas: {env.pandas_available} ({env.pandas_version})")
print(f"Polars: {env.polars_available} ({env.polars_version})")
print(f"Jupyter Notebook: {env.is_jupyter_notebook}")
print(f"Marimo Notebook: {env.is_marimo_notebook}")

Results will depend in your specific environment, but it will look something like this:

IPython: False ()
Marimo: True (0.19.5)
Pandas: True (3.0.0)
Polars: True (1.37.1)
Jupyter Notebook: False
Marimo Notebook: True