cnotebook 1.2.0__py3-none-any.whl → 2.1.1__py3-none-any.whl

cnotebook/render.py

@@ -2,9 +2,6 @@ import logging
 import base64
 from .context import CNotebookContext, pass_cnotebook_context
 from openeye import oechem, oedepict
-from typing import Literal
-from math import floor, ceil
-from collections.abc import Iterable, Sequence
 
 log = logging.getLogger("cnotebook")
 
@@ -201,195 +198,3 @@ def oeimage_to_html(image: oedepict.OEImage, *, ctx: CNotebookContext) -> str:
     )
 
 
-@pass_cnotebook_context
-def render_molecule_grid(
-        mols: Sequence[oechem.OEMolBase],
-        nrows: int | None = None,
-        ncols: int | None = None,
-        max_width: int = 1280,
-        max_columns: int = 100,
-        min_width: int | None = None,
-        min_height: int | None = None,
-        align: oechem.OEMolBase | Literal["first"] | None = None,
-        smarts: str | Iterable[str] | oechem.OESubSearch | Iterable[oechem.OESubSearch] | None = None,
-        color: oechem.OEColor = oechem.OEColor(oechem.OELightBlue),
-        style: int = oedepict.OEHighlightStyle_Stick,
-        scale: float = 1.0,
-        *,
-        ctx: CNotebookContext
-) -> oedepict.OEImage:
-    """
-    Convenience function to render a molecule grid
-    :param ctx: Current OpenEye rendering context
-    :param mols: Iterable of OpenEye molecules
-    :param nrows: Number of rows to display in the grid
-    :param ncols: Number of columns to display in the grid
-    :param max_width: Maximum width of the image
-    :param max_columns: Maximum number of columns (if ncols is being automatically calculated)
-    :param min_width: Minimum image width (prevents tiny images)
-    :param min_height: Minimum image height (prevents tiny images)
-    :param align: Alignment to the first molecule, or to a reference molecule
-    :param smarts: SMARTS substructure highlighting
-    :param color: SMARTS highlighting color
-    :param style: SMARTS highlighting style
-    :param scale: Image scale in the 2D grid
-    :return: Image of the molecule grid
-    """
-    from .helpers import create_structure_highlighter
-
-    # Re-scale the images
-    ctx.display_options.SetScale(ctx.display_options.GetScale() * scale)
-
-    # ---------------------------------------------------------------
-    # Input validation
-    # ---------------------------------------------------------------
-
-    # Handle single molecules
-    if isinstance(mols, oechem.OEMolBase):
-        mols = [mols]
-
-    # Make a copy of the molecules (so we do not modify them)
-    # We can use OEGraphMol here because we don't care about conformers
-    # Filter out None values first
-    mols = [oechem.OEGraphMol(mol) for mol in mols if mol is not None]
-
-    if len(mols) == 0:
-        log.warning("No molecules or display objects to render into a grid")
-        # Return a minimal 1x1 image instead of 0x0 to avoid OpenEye bug
-        return oedepict.OEImage(1, 1)
-
-    # Get the subset of molecules that will actually be displayed
-    valid = []
-
-    for idx, mol in enumerate(mols):
-        if mol is not None:
-            if isinstance(mol, oechem.OEMolBase):
-                if mol.IsValid():
-                    valid.append(mol)
-                else:
-                    log.warning(f'Molecule at index {idx} is not valid')
-
-            else:
-                log.warning(f'Object at index is not a molecule but type {type(mol).__name__}')
-
-    if len(valid) == 0:
-        log.warning("No valid molecules or display objects to render into a grid")
-        # Return a minimal 1x1 image instead of 0x0 to avoid OpenEye bug
-        return oedepict.OEImage(1, 1)
-
-    # ---------------------------------------------------------------
-    # For highlighting SMARTS
-    # ---------------------------------------------------------------
-
-    highlighers = None
-
-    if smarts is not None:
-        highlighers = []
-        # Case: Single pattern
-        if isinstance(smarts, (str, oechem.OESubSearch)):
-            highlighers.append(
-                create_structure_highlighter(
-                    smarts,
-                    color=color,
-                    style=style
-                )
-            )
-
-        else:
-            for pattern in smarts:
-                highlighers.append(
-                    create_structure_highlighter(
-                        pattern,
-                        color=color,
-                        style=style
-                    )
-                )
-
-    # ---------------------------------------------------------------
-    # For substructure alignment
-    # ---------------------------------------------------------------
-
-    align_mcss = None
-
-    if align is not None:
-
-        # If we are doing an alignment
-        if isinstance(align, bool) and align:
-            align_ref = mols[0]
-
-        elif isinstance(align, oechem.OEMolBase):
-            align_ref = align
-
-        else:
-            raise TypeError(f'Cannot initialize MCSS alignment reference from type {type(align).__name__}')
-
-        # Set up the MCSS
-        align_mcss = oechem.OEMCSSearch(oechem.OEMCSType_Approximate)
-        align_mcss.Init(align_ref, oechem.OEExprOpts_DefaultAtoms, oechem.OEExprOpts_DefaultBonds)
-
-    # ---------------------------------------------------------------
-    # Create the display objects for each molecule
-    # ---------------------------------------------------------------
-
-    displays = []
-    max_disp_width = float('-inf')
-    max_disp_height = float('-inf')
-
-    for mol in valid:
-        if align_mcss is not None:
-            oedepict.OEPrepareAlignedDepiction(mol, align_mcss)
-        else:
-            oedepict.OEPrepareDepiction(mol)
-
-        # Create the display object
-        disp = ctx.create_molecule_display(mol, min_width=min_width, min_height=min_height)
-
-        # Highlight SMARTS patterns
-        if highlighers is not None:
-            for highlight in highlighers:
-                highlight(disp)
-
-        displays.append(disp)
-
-        if disp.GetWidth() > max_disp_width:
-            max_disp_width = disp.GetWidth()
-
-        if disp.GetHeight() > max_disp_height:
-            max_disp_height = disp.GetHeight()
-
-    # ---------------------------------------------------------------
-    # Figure out the geometry of the full image
-    # ---------------------------------------------------------------
-    # Case: We have one molecule
-    if len(displays) == 1:
-        ncols = 1
-        nrows = 1
-
-    # Case: We are computing based on max_width
-    elif ncols is None and nrows is None:
-
-        # Number of columns we can fit into max_width
-        ncols = min(floor(max_width / max_disp_width), max_columns, len(displays))
-        nrows = ceil(len(displays) / ncols)
-
-    elif nrows is not None:
-        ncols = ceil(len(displays) / nrows)
-
-    elif ncols is not None:
-        nrows = ceil(len(displays) / ncols)
-
-    else:
-        raise RuntimeError("Cannot determine number of rows and columns in molecule grid")
-
-    # Image width and height
-    width = max_disp_width * ncols
-    height = max_disp_height * nrows
-
-    image = oedepict.OEImage(width, height)
-    grid = oedepict.OEImageGrid(image, nrows, ncols)
-
-    # Render the molecules
-    for disp, cell in zip(displays, grid.GetCells()):
-        oedepict.OERenderMolecule(cell, disp)
-
-    return image

cnotebook-2.1.1.dist-info/METADATA

@@ -0,0 +1,338 @@
+Metadata-Version: 2.4
+Name: cnotebook
+Version: 2.1.1
+Summary: Chemistry visualization in Jupyter Notebooks with the OpenEye Toolkits
+Author-email: Scott Arne Johnson <scott.arne.johnson@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/scott-arne/cnotebook
+Project-URL: Bug Reports, https://github.com/scott-arne/cnotebook/issues
+Project-URL: Source, https://github.com/scott-arne/cnotebook
+Project-URL: Documentation, https://github.com/scott-arne/cnotebook#readme
+Project-URL: Changelog, https://github.com/scott-arne/cnotebook/blob/master/CHANGELOG.md
+Keywords: chemistry,cheminformatics,computational-chemistry,molecular-visualization,jupyter,marimo,openeye,scientific-computing
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: Jupyter
+Classifier: Framework :: IPython
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openeye-toolkits>=2025.2.1
+Requires-Dist: anywidget>=0.9.0
+Requires-Dist: jinja2>=3.0.0
+Provides-Extra: dev
+Requires-Dist: invoke; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Dynamic: license-file
+
+# CNotebook
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![OpenEye Toolkits](https://img.shields.io/badge/OpenEye-2025.2.1+-green.svg)](https://www.eyesopen.com/toolkits)
+
+**Author:** Scott Arne Johnson ([scott.arne.johnson@gmail.com](mailto:scott.arne.johnson@gmail.com))
+
+**Documentation:** https://cnotebook.readthedocs.io/en/latest/
+
+CNotebook provides chemistry visualization for Jupyter Notebooks and Marimo using the OpenEye Toolkits. 
+Import the package and your molecular data will automatically render as chemical structures without additional 
+configuration.
+
+Supports both Pandas and Polars DataFrames with automatic environment detection.
+
+**Render molecules in Jupyter and Marimo with style**
+<br>
+<img src="docs/_static/molecule_with_style.png" height="200">
+
+**Maintain Jupyter table formatting for Pandas and Polars**
+<br>
+<img src="docs/_static/simple_pandas.png" height="600">
+
+**Compatible with native Marimo tables**
+<br>
+<img src="docs/_static/marimo_pandas_polars.png" height="600">
+
+**Interactive molecule grids that support data**
+<br>
+<img src="docs/_static/simple_molgrid.png" height="300">
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Features](#features)
+- [MolGrid Interactive Visualization](#molgrid-interactive-visualization)
+- [DataFrame Integration](#dataframe-integration)
+- [Advanced Usage](#advanced-usage)
+- [Example Notebooks](#example-notebooks)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+```bash
+pip install cnotebook
+```
+
+**Prerequisites:** 
+- [OpenEye Toolkits](http://eyesopen.com): `pip install openeye-toolkits`
+- You must have a valid license (free for academia).
+
+**Optional backends:**
+- Pandas support: `pip install pandas oepandas`
+- Polars support: `pip install polars oepolars`
+
+Both backends can be installed together, neither are required unless you want to work with DataFrames.
+
+## Getting Started
+
+The fastest way to learn CNotebook is through the example notebooks in the `examples/` directory:
+
+| Environment | Pandas                                                          | Polars                                                          | MolGrid                                                           |
+|-------------|-----------------------------------------------------------------|-----------------------------------------------------------------|-------------------------------------------------------------------|
+| **Jupyter** | [pandas_jupyter_demo.ipynb](examples/pandas_jupyter_demo.ipynb) | [polars_jupyter_demo.ipynb](examples/polars_jupyter_demo.ipynb) | [molgrid_jupyter_demo.ipynb](examples/molgrid_jupyter_demo.ipynb) |
+| **Marimo**  | [pandas_marimo_demo.py](examples/pandas_marimo_demo.py)         | [polars_marimo_demo.py](examples/polars_marimo_demo.py)         | [molgrid_marimo_demo.py](examples/molgrid_marimo_demo.py)         |
+
+### Basic Usage
+
+```python
+import cnotebook
+from openeye import oechem
+
+# Create a molecule (supports titles in SMILES)
+mol = oechem.OEGraphMol()
+oechem.OESmilesToMol(mol, "c1cnccc1 Benzene")
+
+# Display it - automatically renders as a chemical structure
+mol
+```
+<img src="docs/_static/benzene.png" />
+
+CNotebook registers formatters so OpenEye molecule objects display as chemical structures instead of text representations.
+
+## Features
+
+### Automatic Rendering
+- Zero configuration required
+- Supports Jupyter Notebooks and Marimo
+- Automatic environment and backend detection
+
+### Molecule Support
+- Direct rendering of `oechem.OEMolBase` objects
+- Advanced rendering with `OE2DMolDisplay` options
+- Pandas integration via OEPandas
+- Polars integration via OEPolars
+
+### Visualization Options
+- PNG (default) or SVG output
+- Configurable width, height, and scaling
+- Substructure highlighting with SMARTS patterns
+- Molecular alignment to reference structures
+
+### MolGrid Interactive Visualization
+- Paginated grid display for browsing molecules
+- Text search across molecular properties
+- SMARTS substructure filtering
+- Selection tools with export to SMILES or CSV
+- Information tooltips with molecular data
+- DataFrame integration with automatic field detection
+
+### DataFrame Integration
+- Automatic molecule column detection and rendering
+- Per-row substructure highlighting
+- Molecular alignment within DataFrames
+- Fingerprint similarity visualization
+- Property calculations on molecule columns
+
+## MolGrid Interactive Visualization
+
+MolGrid provides an interactive grid for browsing molecular datasets with search and selection capabilities.
+
+### Basic Example
+
+```python
+from cnotebook import MolGrid
+from openeye import oechem
+
+# Create molecules
+molecules = []
+for smi in ["CCO", "c1ccccc1", "CC(=O)O"]:
+    mol = oechem.OEGraphMol()
+    oechem.OESmilesToMol(mol, smi)
+    molecules.append(mol)
+
+# Display interactive grid
+grid = MolGrid(molecules)
+grid.display()
+```
+<img src="docs/_static/simple_molgrid.png" height="300">
+
+### Search and Filter
+
+MolGrid provides two search modes:
+- **Properties mode:** Search by molecular titles and configurable text fields
+- **SMARTS mode:** Filter by substructure patterns with match highlighting
+
+### Selection
+
+- Click molecules or checkboxes to select
+- Use the menu for Select All, Clear, and Invert operations
+- Export selections to SMILES or CSV files
+
+### Information Tooltips
+
+- Hover over the information button to view molecular data
+- Click to pin tooltips for comparing multiple molecules
+- Configure displayed fields with the `data` parameter
+
+### DataFrame Integration
+
+```python
+import pandas as pd
+from cnotebook import MolGrid
+from openeye import oechem, oemolprop
+
+# Create DataFrame
+df = pd.DataFrame(
+    {"Molecule": ["CCO", "c1ccccc1", "CC(=O)O"]}
+).chem.as_molecule("Molecule")
+
+# Calculate some properties
+df["MW"] = df.Molecule.apply(oechem.OECalculateMolecularWeight)
+df["PSA"] = df.Molecule.apply(oemolprop.OEGet2dPSA)
+df["HBA"] = df.Molecule.apply(oemolprop.OEGetHBondAcceptorCount)
+df["HBD"] = df.Molecule.apply(oemolprop.OEGetHBondDonorCount)
+
+# Display the grid (using the 'Molecule' column for structures)
+grid = df.chem.molgrid("Molecule")
+grid.display()
+```
+
+This will display the same grid as above, but with molecule data if you click the "i".
+
+### Retrieving Selections
+
+```python
+# Get selected molecules
+selected_mols = grid.get_selection()
+
+# Get selected indices
+indices = grid.get_selection_indices()
+```
+
+## DataFrame Integration
+
+### Pandas DataFrames
+
+```python
+import cnotebook
+import oepandas as oepd
+
+# Read the example unaligned molecules
+df = oepd.read_sdf("examples/assets/rotations.sdf", no_title=True)
+
+# Rename the "Molecule" column to "Original" so that we can
+# see the original unaligned molecules
+df = df.rename(columns={"Molecule": "Original"})
+
+# Create a new molecule column called "Aligned" so that we can
+# see the aligned molecules
+df["Aligned"] = df.Original.chem.copy_molecules()
+
+# Add substructure highlighting
+df["Original"].chem.highlight("c1ccccc1")
+df["Aligned"].chem.highlight("c1ccccc1")
+
+# Align molecules to a reference
+df["Aligned"].chem.align_depictions("first")
+
+# Display the DataFrame
+df
+```
+
+<img src="docs/_static/pandas_highlight_and_align_dataframe.png" height="400">
+
+### Polars DataFrames
+
+Same example as above using Polars instead of Pandas. The main difference is that some methods are called
+from the DataFrame instead of the Series.
+
+```python
+import cnotebook
+import oepolars as oepl
+
+# Read the example unaligned molecules
+df = oepl.read_sdf("examples/assets/rotations.sdf", no_title=True)
+
+# Rename the "Molecule" column to "Original" so that we can
+# see the original unaligned molecules
+df = df.rename({"Molecule": "Original"})
+
+# # Create a new molecule column called "Aligned" so that we can
+# # see the aligned molecules
+df = df.chem.copy_molecules("Original", "Aligned")
+
+# # Add substructure highlighting
+df.chem.highlight("Original", "c1ccccc1")
+df.chem.highlight("Aligned", "c1ccccc1")
+
+# # Align molecules to a reference
+df["Aligned"].chem.align_depictions("first")
+
+# Display the DataFrame
+df
+```
+
+This will display the exact same table as above.
+
+## Example Notebooks
+
+The `examples/` directory contains comprehensive tutorials for learning CNotebook:
+
+### Jupyter Notebooks
+
+- **[pandas_jupyter_demo.ipynb](examples/pandas_jupyter_demo.ipynb)** - Complete Pandas integration tutorial covering molecule rendering, highlighting, alignment, and fingerprint similarity
+- **[polars_jupyter_demo.ipynb](examples/polars_jupyter_demo.ipynb)** - Complete Polars integration tutorial with the same features adapted for Polars patterns
+- **[molgrid_jupyter_demo.ipynb](examples/molgrid_jupyter_demo.ipynb)** - Interactive molecule grid tutorial with search, selection, and export features
+- **[pandas_jupyter_svgs.ipynb](examples/pandas_jupyter_svgs.ipynb)** - SVG vs PNG rendering comparison and quality considerations
+
+### Marimo Applications
+
+- **[pandas_marimo_demo.py](examples/pandas_marimo_demo.py)** - Pandas tutorial in reactive Marimo environment
+- **[polars_marimo_demo.py](examples/polars_marimo_demo.py)** - Polars tutorial in reactive Marimo environment
+- **[molgrid_marimo_demo.py](examples/molgrid_marimo_demo.py)** - MolGrid tutorial with reactive selection feedback
+
+**Recommended starting point:** Begin with the MolGrid demo for your preferred environment, then explore the Pandas or Polars tutorials for DataFrame integration.
+
+## Contributing
+
+Contributions are welcome. Please ensure your code:
+- Follows existing code style and conventions
+- Includes appropriate tests
+- Works with both Jupyter and Marimo environments
+- Maintains compatibility with OpenEye Toolkits
+- Works with both Pandas and Polars when applicable
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
+
+## Support
+
+For bug reports, feature requests, or questions, please open an issue on GitHub or contact [scott.arne.johnson@gmail.com](mailto:scott.arne.johnson@gmail.com).

cnotebook-2.1.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+cnotebook/__init__.py,sha256=MBF3mPnDEI3ytXH8BwA9TqongkaYMVflLbc0lTt5rLI,13746
+cnotebook/align.py,sha256=wDJy79PvRG0O_XHCAXkGv2uqp6nL65g-NO-oQSnOkpI,17926
+cnotebook/context.py,sha256=HKTx0Bxz0LfleaWjBco_AoSGR2iPrVY-0OsJ_ro6O0o,19229
+cnotebook/helpers.py,sha256=TCcNfykhSi77FrTQC2_2W8G9lxP0n3S7V8tEiGcE0hg,7121
+cnotebook/ipython_ext.py,sha256=Z6IhHg_YP6-becgruEDiE-tVkSB0SZTUU6R2MItaVa4,1874
+cnotebook/marimo_ext.py,sha256=F2WBiM0F3vLcL9vAcZesB7XgIWULd7QiWe78dQy1h3s,9790
+cnotebook/pandas_ext.py,sha256=XrmL5CTQ6a_J3ruV-AK_7ZupcsUU-Y0fZ8Ml_koeOTY,43442
+cnotebook/polars_ext.py,sha256=YC1Sezwk4C9Qoz4AHxsvt6D_4nwHn17wLOL5tieEGgw,47864
+cnotebook/render.py,sha256=jn47U5I0t0H5R_iydhBsz_vVdtBVXyQYwrMb_XG8zy0,6143
+cnotebook/grid/__init__.py,sha256=Orgb6l9C7oJD32-uBCC7gDrjUtNzJf0DLXao7FcL6GQ,1859
+cnotebook/grid/grid.py,sha256=VbcoZCNT1whfcMYWjK9UQ2o9Jr5D_y2xYS54QhfwASo,51500
+cnotebook-2.1.1.dist-info/licenses/LICENSE,sha256=HbIgeZz-pWGC7BEnYFCQ-jfD1m_BfiosF9qjgWw64GU,1080
+cnotebook-2.1.1.dist-info/METADATA,sha256=emROyOs1eYOp7auzcB6sIrKy6bLKTGj8Eah0i72OCu0,11924
+cnotebook-2.1.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+cnotebook-2.1.1.dist-info/top_level.txt,sha256=jzkieTjQwdNKfMwnoElvDDtNPkeLMjbvWbsbkSsboo8,10
+cnotebook-2.1.1.dist-info/RECORD,,

{cnotebook-1.2.0.dist-info → cnotebook-2.1.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any