cnotebook 1.0.1__py3-none-any.whl

cnotebook/render.py

@@ -0,0 +1,198 @@
+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-1.0.1.dist-info/METADATA

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: cnotebook
+Version: 1.0.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.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas<3.0.0,>=2.0.0
+Requires-Dist: oepandas>=2.0.0
+Requires-Dist: openeye-toolkits
+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 - Chemistry Visualization for Jupyter & Marimo
+
+**Author:** Scott Arne Johnson ([scott.arne.johnson@gmail.com](mailto:scott.arne.johnson@gmail.com))
+
+CNotebook provides ergonomic chemistry visualization in Jupyter Notebooks and Marimo with the OpenEye Toolkits. Simply import the package and your molecular data will be automatically rendered as beautiful chemical structures - no additional configuration required!
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install cnotebook
+```
+
+**Prerequisites:** Requires OpenEye Toolkits and oepandas to be installed and properly licensed.
+
+### Basic Usage
+
+```python
+import cnotebook
+from openeye import oechem
+
+# Create a molecule
+mol = oechem.OEGraphMol()
+oechem.OESmilesToMol(mol, "n1cnccc1")
+
+# Display it - automatically renders as a chemical structure!
+mol
+```
+
+That's it! CNotebook automatically registers formatters so that OpenEye molecule objects display as chemical structures instead of cryptic text representations.
+
+## 📚 Features
+
+### ✨ Automatic Rendering
+- **Zero Configuration**: Just import and go - molecules automatically render as structures
+- **Multiple Formats**: Supports both Jupyter Notebooks and Marimo environments
+- **Smart Detection**: Automatically detects your notebook environment
+
+### 🧪 Molecule Support
+- **OEMol Objects**: Direct rendering of `oechem.OEMolBase` derived objects
+- **OE2DMolDisplay**: Advanced rendering with custom depiction options
+- **Pandas Integration**: Seamless rendering in DataFrames with oepandas
+
+### 🎨 Visualization Options
+- **Multiple Formats**: PNG (default) or SVG output
+- **Customizable Sizing**: Configurable width, height, and scaling
+- **Grid Layouts**: Multi-molecule grid displays
+- **Substructure Highlighting**: SMARTS pattern highlighting
+- **Molecular Alignment**: Align molecules to reference structures
+
+### 📊 Pandas Integration
+- **DataFrame Rendering**: Automatic molecule column detection and rendering
+- **Column Highlighting**: Highlight different patterns per row
+- **Alignment Tools**: Align molecular depictions in DataFrames
+- **Fingerprint Similarity**: Visual similarity coloring
+- **Property Calculation**: Chemistry-aware DataFrame operations
+
+## 🛠️ Environment Support
+
+### Jupyter Notebooks
+CNotebook automatically integrates with Jupyter when imported:
+
+```python
+import cnotebook
+import pandas as pd
+from openeye import oechem
+
+# Molecules will automatically render in cells
+mol = oechem.OEGraphMol()
+oechem.OESmilesToMol(mol, "CCO")
+mol  # Displays as chemical structure
+```
+
+### Marimo
+CNotebook provides seamless Marimo integration:
+
+```python
+import marimo as mo
+import cnotebook
+from openeye import oechem
+
+# Create and display molecules
+mol = oechem.OEGraphMol()
+oechem.OESmilesToMol(mol, "c1ccccc1")
+mol  # Automatically renders as PNG for Marimo compatibility
+```
+
+## 📖 Advanced Usage
+
+### Rendering Configuration
+
+```python
+# Access global rendering context
+ctx = cnotebook.cnotebook_context.get()
+
+# Customize rendering options
+ctx.width = 300
+ctx.height = 300
+ctx.image_format = "svg"  # Use SVG instead of PNG
+ctx.max_width = 600      # Prevent oversized molecules
+
+# Reset to defaults
+ctx.reset()
+```
+
+### Molecule Grids
+
+```python
+# Display multiple molecules in a grid
+molecules = [mol1, mol2, mol3, mol4]
+cnotebook.render_molecule_grid(
+    molecules,
+    ncols=2,
+    smarts="c1ccccc1",  # Highlight benzene rings
+    scale=0.8
+)
+```
+
+### Pandas DataFrame Integration
+
+```python
+import oepandas as oepd
+import pandas as pd
+
+# Create DataFrame with SMILES
+df = pd.DataFrame({
+    "Name": ["Benzene", "Pyridine", "Pyrimidine"],
+    "SMILES": ["c1ccccc1", "c1cnccc1", "n1cnccc1"]
+})
+
+# Convert to molecules
+df.as_molecule("SMILES", inplace=True)
+
+# DataFrame automatically renders molecules as structures
+df  # Molecule column shows chemical structures!
+
+# Add substructure highlighting
+df.SMILES.highlight("c1ccccc1")  # Highlight aromatic rings
+df
+
+# Align molecules to a reference
+df.SMILES.align_depictions("first")  # Align to first molecule
+df
+```
+
+### Substructure Highlighting
+
+```python
+# Highlight SMARTS patterns
+df["Pattern"] = ["cc", "cnc", "ncn"]
+df.highlight_using_column("Molecule", "Pattern", inplace=True)
+df  # Shows molecules with different highlights per row
+```
+
+### Fingerprint Similarity
+
+```python
+# Color molecules by fingerprint similarity
+reference_mol = oechem.OEGraphMol()
+oechem.OESmilesToMol(reference_mol, "c1ccc(N)cc1")
+
+df.fingerprint_similarity("Molecule", reference_mol, inplace=True)
+df  # Shows similarity coloring and Tanimoto coefficients
+```
+
+## 📁 Demo Notebooks
+
+Explore comprehensive examples in the `demos/` directory:
+
+### [Small_Molecules.ipynb](demos/Small_Molecules.ipynb)
+**Complete CNotebook Tutorial** - Comprehensive guide covering:
+- Basic molecule rendering and display options
+- OE2DMolDisplay objects with custom styling
+- Molecule grid layouts with highlighting
+- Advanced rendering configuration
+- Pandas DataFrame integration with oepandas
+- Substructure highlighting and SMARTS patterns
+- Column-based highlighting with different patterns per row
+- Molecular alignment techniques
+- Fingerprint similarity visualization
+- Empty and invalid molecule handling
+
+### [SVGs.ipynb](demos/SVGs.ipynb)
+**SVG Rendering Guide** - Learn how to:
+- Switch from PNG to SVG output format
+- Benefits and trade-offs of SVG vs PNG
+- High-quality crisp molecular graphics
+- SVG compatibility considerations
+
+## 🔧 Configuration Options
+
+### Global Context Settings
+
+```python
+ctx = cnotebook.cnotebook_context.get()
+
+# Image dimensions
+ctx.width = 250          # Default width in pixels
+ctx.height = 250         # Default height in pixels
+ctx.max_width = 1200     # Maximum width (prevents oversized molecules)
+ctx.max_height = 800     # Maximum height
+
+# Output format
+ctx.image_format = "png"  # or "svg"
+
+# Display options
+ctx.scale = 1.0          # Scaling factor
+```
+
+### Environment-Specific Behavior
+
+- **Jupyter**: Supports both PNG and SVG formats
+- **Marimo**: Automatically uses PNG format for compatibility
+- **Console**: Falls back to string representations
+
+## 🤝 Contributing
+
+We welcome contributions! 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
+
+## 📄 License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## 🐛 Issues & Support
+
+For bug reports, feature requests, or general support, please open an issue on GitHub or contact the author at [scott.arne.johnson@gmail.com](mailto:scott.arne.johnson@gmail.com).
+
+---
+
+*CNotebook makes chemical data visualization effortless. Import once, visualize everywhere!* 🧬✨

cnotebook-1.0.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+cnotebook/__init__.py,sha256=cdQtNy_bYo3ezhhLrSfQidCaRRAGVfqeIJA6XCh2wV0,2695
+cnotebook/align.py,sha256=u22GEHJc8QzCb9If2mjuapKPOTBEB2iu6jtUfgmm1UQ,14086
+cnotebook/context.py,sha256=MXOIIZ7PkWZ8Wi11L00ldAqsaNCBmJRc76bETelIq9w,17493
+cnotebook/helpers.py,sha256=r5-CIcmomd8vbd6ILGU6uW3sAjWZPcng82cikZ0ZDZ8,2193
+cnotebook/ipython_ext.py,sha256=T6kggGkT7YtDfW7XL3kM_wIhac9jVBQaeDgSrjlQp1g,8869
+cnotebook/marimo_ext.py,sha256=b7TJU_Wj-UvfeCkvFWKzn28dPR4olbsd4auWG3UpzQ8,1055
+cnotebook/pandas_ext.py,sha256=9ED28VrxOzdCELIpUpHminbUrccsNcqDFRMLNc26wVA,34795
+cnotebook/render.py,sha256=N5W8-QQGD3d149K6E15MkUvnYtIyFeJ5o4Gphf8Bcuo,6141
+cnotebook-1.0.1.dist-info/licenses/LICENSE,sha256=HbIgeZz-pWGC7BEnYFCQ-jfD1m_BfiosF9qjgWw64GU,1080
+cnotebook-1.0.1.dist-info/METADATA,sha256=MvrUjSCF8Up_dJOF1dQ1pwlo_LZv0Ft9MStmFDPXQV4,8575
+cnotebook-1.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cnotebook-1.0.1.dist-info/top_level.txt,sha256=jzkieTjQwdNKfMwnoElvDDtNPkeLMjbvWbsbkSsboo8,10
+cnotebook-1.0.1.dist-info/RECORD,,

cnotebook-1.0.1.dist-info/WHEEL

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

cnotebook-1.0.1.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-1.0.1.dist-info/top_level.txt

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