ipyspeck 0.7.1

Speck Jupyter Widget

ipyspeck

A Jupyter Widget for rendering beautiful molecular structures using Speck.

Latest Release
PyPI Downloads

About

Speck is a molecule renderer with the goal of producing figures that are as attractive as they are practical. Express your molecule clearly and with style.

Ipyspeck is an ipywidget wrapper for Speck that allows you to visualize molecular structures directly in Jupyter notebooks and JupyterLab.

Version Compatibility

⚠️ IMPORTANT: Version Compatibility Notice

ipyspeck 0.7.x and later requires:

• JupyterLab >= 3.0
• ipywidgets >= 7.0
• Python >= 3.9

For older environments, use ipyspeck 0.6.x:

• JupyterLab 2.x → use ipyspeck<0.7
• ipywidgets < 7.0 → use ipyspeck<0.7
• Python < 3.9 → use ipyspeck<0.7

Migration Notes:

• Version 0.7.0+ uses the modern JupyterLab 3+ federated extension system
• Version 0.7.0+ supports both ipywidgets 7.x and 8.x with backward compatibility
• Version 0.7.0+ uses Lumino (LuminoJS) instead of deprecated PhosphorJS

Installation

Standard Installation

For JupyterLab 3+ and ipywidgets 7+:

pip install ipyspeck

That's it! The extension will be automatically enabled in JupyterLab 3+.

Legacy Installation (JupyterLab 2.x)

For older JupyterLab versions:

pip install "ipyspeck<0.7"
jupyter nbextension enable --py --sys-prefix ipyspeck
jupyter labextension install ipyspeck

Development Installation

For developers who want to contribute:

git clone https://github.com/denphi/speck.git
cd speck/widget/ipyspeck
pip install -e .

Usage

Basic Usage

The ipyspeck widget renders molecules in XYZ format:

from ipyspeck import Speck

H2O = '''3
Water molecule
O          0.00000        0.00000        0.11779
H          0.00000        0.75545       -0.47116
H          0.00000       -0.75545       -0.47116'''

h2o = Speck(data=H2O)
h2o

Using with Container Widgets

For better control over size and layout, use ipyspeck inside container widgets:

import ipywidgets as widgets

# Create a sized container
container = widgets.Box(
    [h2o],
    layout=widgets.Layout(width="600px", height="400px")
)
container

Customization

Adjust visualization parameters to suit your needs:

# Modify atom size
h2o.atomScale = 0.3

# Change bond thickness
h2o.bondScale = 0.3

# Toggle atom outlines
h2o.outline = 0

Working with Different File Formats

Use OpenBabel to convert various molecular formats to XYZ:

import openbabel
import requests

# Fetch a molecule in SDF format
url = "https://files.rcsb.org/ligands/view/CO2_ideal.sdf"
r = requests.get(url)

# Convert to XYZ
obConversion = openbabel.OBConversion()
obConversion.SetInAndOutFormats("sdf", "xyz")
mol = openbabel.OBMol()
obConversion.ReadString(mol, r.text)
co2 = obConversion.WriteString(mol)

# Visualize
Speck(data=co2)

Streamlit Integration

ipyspeck 0.6+ includes a Streamlit wrapper for building interactive web apps:

import streamlit as st
from ipyspeck import stspeck

H2O = '''3
Water molecule
O          0.00000        0.00000        0.11779
H          0.00000        0.75545       -0.47116
H          0.00000       -0.75545       -0.47116'''

with st.sidebar:
    ao = st.selectbox("Ambient Occlusion", [0, 0.1, 0.2, 0.5, 0.8, 1])
    bonds = st.selectbox("Show Bonds", [True, False])

res = stspeck.Speck(
    data=H2O,
    ao=ao,
    bonds=bonds,
    width="800px",
    height="600px"
)

Features

• 🎨 Beautiful, publication-quality molecular visualizations
• 🔄 Interactive rotation and zoom
• ⚡ Fast rendering with WebGL
• 🎛️ Customizable atom and bond styles
• 📦 Support for XYZ format (use OpenBabel for other formats)
• 🧪 Works in Jupyter Notebook, JupyterLab, and Streamlit
• 🔌 Compatible with ipywidgets ecosystem

Gallery

Development

Building from Source

# Install dependencies
npm install

# Build TypeScript and JavaScript
npm run build

# Or build for production
npm run build:prod

Active Development

When actively developing the extension:

# Watch for changes and rebuild automatically
jupyter lab --watch

Note: On first jupyter lab --watch, you may need to touch a file to trigger JupyterLab to open.

License

BSD-3-Clause

Author

Daniel Mejia (Denphi) - [e-mail]

Links

• GitHub Repository
• PyPI Package
• Issue Tracker