cnotebook 2.1.0__py3-none-any.whl

cnotebook/render.py

@@ -0,0 +1,200 @@
+import logging
+import base64
+from .context import CNotebookContext, pass_cnotebook_context
+from openeye import oechem, oedepict
+
+log = logging.getLogger("cnotebook")
+
+
+########################################################################################################################
+# Renderers for specific types
+########################################################################################################################
+
+def create_img_tag(
+        width: float,
+        height: float,
+        image_mime_type: str,
+        image_bytes: bytes,
+        wrap_svg: bool = True
+
+) -> str:
+    """
+    Create the <img> HTML tag for rendering image bytes. This could be either plain text (in the case of SVG) or base64
+    encoded (in binary format cases).
+    :param width: Image width
+    :param height: Image height
+    :param image_mime_type: Image MIME type
+    :param image_bytes: Image bytes
+    :param wrap_svg: Wrap SVG in a specifically sized <div> tag for maximum control of size
+    :return: Image tag
+    """
+    if image_mime_type == "image/svg+xml":
+        if wrap_svg:
+            return '<div style=\'width:{}px;max-width:{}px;height:{}px;max-height:{}px\'>\n\t{}\n</div>'.format(
+                int(width),
+                int(width),
+                int(height),
+                int(height),
+                image_bytes.decode("utf-8")
+            )
+        else:
+            return image_bytes.decode("utf-8")
+
+    return '<img src=\'data:{};base64,{}\' style=\'width:{}px;max-width:{}px;height:{}px;max-height:{}px\' />'.format(
+        image_mime_type,
+        base64.b64encode(image_bytes).decode("utf-8"),
+        int(width),
+        int(width),
+        int(height),
+        int(height)
+    )
+
+
+@pass_cnotebook_context
+def oedisp_to_html(
+        disp: oedepict.OE2DMolDisplay,
+        *,
+        ctx: CNotebookContext
+) -> str:
+    """
+    Convert an OpenEye 2D molecule display object to HTML
+    :param ctx: Current molecule render context
+    :param disp: OpenEye 2D molecule display object
+    :return: HTML image tag
+    """
+    # Convert the display object to an <img> tag
+    image = oedepict.OEImage(disp.GetWidth(), disp.GetHeight())
+    oedepict.OERenderMolecule(image, disp)
+    image_bytes = oedepict.OEWriteImageToString(ctx.image_format, image)
+
+    return create_img_tag(
+        disp.GetWidth(),
+        disp.GetHeight(),
+        image_mime_type=ctx.image_mime_type,
+        image_bytes=image_bytes,
+        wrap_svg=ctx.structure_scale != oedepict.OEScale_AutoScale
+    )
+
+
+def render_empty_molecule(*, ctx: CNotebookContext) -> str:
+    """
+    Render an image that says Empty Molecule
+    :param ctx: Render context
+    :return: Image tag
+    """
+    image = oedepict.OEImage(ctx.min_width, ctx.min_height)
+    image.DrawText(
+        oedepict.OE2DPoint(ctx.min_width / 2, ctx.min_height / 2),
+        "Empty Molecule",
+        oedepict.OEFont(
+            oedepict.OEFontFamily_Arial,
+            oedepict.OEFontStyle_Normal,
+            14,
+            oedepict.OEAlignment_Center,
+            oechem.OEDarkBlue
+        )
+    )
+
+    return create_img_tag(
+        ctx.min_width,
+        ctx.min_height,
+        image_mime_type=ctx.image_mime_type,
+        image_bytes=oedepict.OEWriteImageToString(ctx.image_format, image),
+        wrap_svg=ctx.structure_scale != oedepict.OEScale_AutoScale
+    )
+
+
+def render_invalid_molecule(*, ctx: CNotebookContext) -> str:
+    """
+    Render an image that says Empty Molecule
+    :param ctx: Render context
+    :return: Image tag
+    """
+    image = oedepict.OEImage(ctx.min_width, ctx.min_height)
+    image.DrawText(
+        oedepict.OE2DPoint(ctx.min_width / 2, ctx.min_height / 2),
+        "Invalid Molecule",
+        oedepict.OEFont(
+            oedepict.OEFontFamily_Arial,
+            oedepict.OEFontStyle_Normal,
+            14,
+            oedepict.OEAlignment_Center,
+            oechem.OERed
+        )
+    )
+
+    return create_img_tag(
+        ctx.min_width,
+        ctx.min_height,
+        image_mime_type=ctx.image_mime_type,
+        image_bytes=oedepict.OEWriteImageToString(ctx.image_format, image),
+        wrap_svg=ctx.structure_scale != oedepict.OEScale_AutoScale
+    )
+
+
+def oemol_to_disp(
+        mol: oechem.OEMolBase,
+        *,
+        ctx: CNotebookContext
+) -> oedepict.OE2DMolDisplay:
+    """
+    Convert a valid OpenEye molecule object to a display object for depiction. Note that it is highly recommended to
+    test that the molecule is valid first before calling this function.
+    :param ctx: Render context
+    :param mol: Molecule to convert
+    :return: Display object for depiction
+    """
+    # Only recalculate coordinates if we don't have a 2D structure
+    if mol.GetDimension() == 2:
+        oedepict.OEPrepareDepiction(mol, False)
+    else:
+        oedepict.OEPrepareDepiction(mol, True)
+
+    return ctx.create_molecule_display(mol)
+
+
+@pass_cnotebook_context
+def oemol_to_html(mol: oechem.OEMolBase, *, ctx: CNotebookContext) -> str:
+    """
+    Convert an OpenEye Molecule object to HTML
+    :param ctx: Render context
+    :param mol: Molecule to convert
+    :return: HTML string
+    """
+    # Render valid molecules
+    if mol.IsValid():
+
+        # Create the display object from the context
+        disp = oemol_to_disp(mol, ctx=ctx)
+
+        # Render the display
+        return oedisp_to_html(disp, ctx=ctx)
+
+    # Render empty molecules
+    elif mol.NumAtoms() == 0:
+        return render_empty_molecule(ctx=ctx)
+
+    # Render other invalid molecules
+    else:
+        return render_invalid_molecule(ctx=ctx)
+
+
+@pass_cnotebook_context
+def oeimage_to_html(image: oedepict.OEImage, *, ctx: CNotebookContext) -> str:
+    """
+    Convert an OEImage to HTML
+    :param ctx: Render context
+    :param image: Image to render
+    :return: HTML string
+    """
+    # Convert the image to an <img> tag
+    image_bytes = oedepict.OEWriteImageToString(ctx.image_format, image)
+    return create_img_tag(
+        image.GetWidth(),
+        image.GetHeight(),
+        image_mime_type=ctx.image_mime_type,
+        image_bytes=image_bytes,
+        wrap_svg=ctx.structure_scale != oedepict.OEScale_AutoScale
+    )
+
+

cnotebook-2.1.0.dist-info/METADATA

@@ -0,0 +1,336 @@
+Metadata-Version: 2.4
+Name: cnotebook
+Version: 2.1.0
+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))
+
+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.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+cnotebook/__init__.py,sha256=C5wYJ0-6bmccYcbKCekAat08vWyk_IyqSHvob6AWfMU,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=iOURve2nDg1z37Jq56GjP1KyvgG7BH9DYu4hlTsfIzg,43323
+cnotebook/polars_ext.py,sha256=AMWVGPdS8qbFH-lNcGrekPwT9vFUxZxq41Rlqx4jjB4,47725
+cnotebook/render.py,sha256=jn47U5I0t0H5R_iydhBsz_vVdtBVXyQYwrMb_XG8zy0,6143
+cnotebook/grid/__init__.py,sha256=yNcddI5PP-6BBXCNhRALvNrlgAn7UeR9ntrhmMMShu8,1804
+cnotebook/grid/grid.py,sha256=y-uV_cNmazI3aDWbRI2JSuOB83jhdZbiivlsPS4wBSk,51217
+cnotebook-2.1.0.dist-info/licenses/LICENSE,sha256=HbIgeZz-pWGC7BEnYFCQ-jfD1m_BfiosF9qjgWw64GU,1080
+cnotebook-2.1.0.dist-info/METADATA,sha256=adbX-E5iLz0yJwJaK_X7FUyT-FNzrYyH-e4GPIvQP5M,11860
+cnotebook-2.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+cnotebook-2.1.0.dist-info/top_level.txt,sha256=jzkieTjQwdNKfMwnoElvDDtNPkeLMjbvWbsbkSsboo8,10
+cnotebook-2.1.0.dist-info/RECORD,,

cnotebook-2.1.0.dist-info/WHEEL

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

cnotebook-2.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 Scott Arne Johnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cnotebook-2.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cnotebook