Add Chemiscope explorer

README.md

@@ -20,8 +20,8 @@ This is a Hugging Face Space providing API access to various RDKit cheminformati
 - `POST /api/smiles_to_mol` : Convert SMILES to canonical SMILES
 - `POST /api/molecular_weight` : Calculate molecular weight
 - `POST /api/logp` : Calculate logP (partition coefficient)
-- `POST /api/tpsa` : Calculate topological polar surface area
 - `POST /api/tpsa` : Calculate TPSA (topological polar surface area)
+- `POST /api/chemiscope_explorer` : Build a Chemiscope dataset + visualization from a batch of SMILES
 - `POST /api/mol_image` : Generate 2D molecule image (returns PIL Image)
 
 ## Usage
@@ -35,4 +35,14 @@ pip install -r requirements.txt
 python app.py
 ```
 
-The API endpoints can be accessed programmatically using the Gradio client or HTTP requests.
+The API endpoints can be accessed programmatically using the Gradio client or HTTP requests.
+
+## Chemiscope-powered exploration
+
+The new **Chemiscope Explorer** tab leverages the official [`chemiscope` Python package](https://chemiscope.org/docs/python/index.html) plus the standalone Chemiscope web viewer to create rich, shareable datasets directly inside the Space:
+
+1. Paste up to 12 SMILES (one per line or comma-separated). RDKit generates 3D ETKDG conformers, computes descriptors (MolWt, logP, TPSA, H-bond counts, rotatable bonds) and per-atom Gasteiger charges.
+2. The resulting ASE frames and descriptors are converted into the Chemiscope JSON schema and embedded with the [`chemiscope_standalone.html`](https://chemiscope.org/docs/index.html) viewer so you can explore structures + map plots without leaving the Space.
+3. Download the `.json.gz` artifact and reload it later on [chemiscope.org](https://chemiscope.org/) via the *Load/Save* menu or by hosting it and passing `?load=<url>` to share interactive analyses with collaborators.
+
+This flow keeps the Hugging Face interface lightweight while exposing the full Chemiscope feature set for interactive dataset mining.

app.py

@@ -1,5 +1,11 @@
 import plotly.graph_objects as go
 import numpy as np
+import json
+import re
+import urllib.request
+
+import chemiscope
+from ase import Atoms
 
 
 def parse_cube_file(cube_file):
@@ -157,6 +163,219 @@ def smiles_to_name(smiles: str) -> str:
     return f"No name available. Canonical SMILES: {canonical_smiles}"
 
 
+CHEMISCOPE_TEMPLATE_URL = "https://chemiscope.org/chemiscope_standalone.html"
+CHEMISCOPE_TEMPLATE_CACHE = Path(tempfile.gettempdir()) / "chemiscope_standalone.html"
+_CHEMISCOPE_TEMPLATE = None
+_MAX_CHEMISCOPE_MOLECULES = 12
+
+
+def _load_chemiscope_template():
+    """Load (and cache) the standalone Chemiscope HTML shell."""
+    global _CHEMISCOPE_TEMPLATE
+    if _CHEMISCOPE_TEMPLATE:
+        return _CHEMISCOPE_TEMPLATE
+
+    if CHEMISCOPE_TEMPLATE_CACHE.exists():
+        try:
+            _CHEMISCOPE_TEMPLATE = CHEMISCOPE_TEMPLATE_CACHE.read_text(encoding="utf-8")
+            return _CHEMISCOPE_TEMPLATE
+        except OSError:
+            # Cache is best-effort; fall back to downloading a fresh copy.
+            pass
+
+    try:
+        with urllib.request.urlopen(CHEMISCOPE_TEMPLATE_URL, timeout=10) as response:
+            template = response.read().decode("utf-8")
+    except Exception as exc:
+        raise gr.Error(
+            "Unable to download the Chemiscope viewer. Please try again in a moment."
+        ) from exc
+
+    try:
+        CHEMISCOPE_TEMPLATE_CACHE.write_text(template, encoding="utf-8")
+    except OSError:
+        # The temp directory might be read-only; ignore caching failures.
+        pass
+
+    _CHEMISCOPE_TEMPLATE = template
+    return template
+
+
+def _smiles_list_from_block(smiles_block: str):
+    """Split a block of SMILES lines/CSV text into a unique, validated list."""
+    tokens = re.split(r"[,\n;]+", smiles_block or "")
+    smiles_list = [token.strip() for token in tokens if token.strip()]
+    if not smiles_list:
+        raise gr.Error("Provide at least one SMILES string (one per line or comma separated).")
+
+    unique_smiles = []
+    for token in smiles_list:
+        canonical = Chem.MolToSmiles(_mol_from_smiles(token))
+        if canonical not in unique_smiles:
+            unique_smiles.append(canonical)
+
+    if len(unique_smiles) > _MAX_CHEMISCOPE_MOLECULES:
+        raise gr.Error(
+            f"Please limit Chemiscope batches to {_MAX_CHEMISCOPE_MOLECULES} molecules to keep the viewer responsive."
+        )
+
+    return unique_smiles
+
+
+def _embed_smiles_in_3d(smiles: str, seed: int):
+    mole = Chem.AddHs(_mol_from_smiles(smiles))
+    params = AllChem.ETKDGv3()
+    params.randomSeed = seed + 1
+    params.maxAttempts = 20
+    status = AllChem.EmbedMolecule(mole, params)
+    if status == -1:
+        params.useRandomCoords = True
+        status = AllChem.EmbedMolecule(mole, params)
+    if status == -1:
+        raise gr.Error(f"Unable to generate a 3D conformer for {smiles}. Try a smaller molecule.")
+
+    AllChem.UFFOptimizeMolecule(mole, maxIters=200)
+    Chem.rdPartialCharges.ComputeGasteigerCharges(mole)
+    return mole
+
+
+def _rdkit_to_ase_atoms(mol: Chem.Mol, label: str) -> Atoms:
+    """Convert an RDKit molecule with coordinates into an ASE Atoms object."""
+    conf = mol.GetConformer()
+    coords = []
+    for atom_idx in range(mol.GetNumAtoms()):
+        pos = conf.GetAtomPosition(atom_idx)
+        coords.append((float(pos.x), float(pos.y), float(pos.z)))
+    symbols = [atom.GetSymbol() for atom in mol.GetAtoms()]
+    ase_atoms = Atoms(symbols=symbols, positions=coords)
+    ase_atoms.info["name"] = label
+    return ase_atoms
+
+
+def _extract_gasteiger_charges(mol: Chem.Mol):
+    charges = []
+    for atom in mol.GetAtoms():
+        if atom.HasProp("_GasteigerCharge"):
+            try:
+                charges.append(float(atom.GetProp("_GasteigerCharge")))
+            except ValueError:
+                charges.append(0.0)
+        else:
+            charges.append(0.0)
+    return charges
+
+
+def _build_chemiscope_embed(dataset_payload: dict) -> str:
+    """Create a standalone iframe with the Chemiscope viewer and dataset content."""
+    template_html = _load_chemiscope_template()
+    dataset_json = json.dumps(dataset_payload, ensure_ascii=False, separators=(",", ":"))
+    combined = template_html + dataset_json
+    encoded = base64.b64encode(combined.encode("utf-8")).decode("ascii")
+    return (
+        "<div style='width:100%;'>"
+        "<iframe "
+        "title='Chemiscope explorer' "
+        "style='width:100%;height:620px;border:none;border-radius:8px;' "
+        f"src='data:text/html;base64,{encoded}'></iframe>"
+        "<p style='font-size:0.9em;margin-top:0.5rem;'>"
+        "Use the map view to explore descriptors interactively or download the dataset for "
+        "https://chemiscope.org/. "
+        "</p>"
+        "</div>"
+    )
+
+
+def smiles_to_chemiscope_dataset(smiles_block: str):
+    """Generate a Chemiscope dataset and embed it alongside a downloadable artifact."""
+    smiles_list = _smiles_list_from_block(smiles_block)
+    frames = []
+    smiles_labels = []
+    atom_counts = []
+    mw_values = []
+    logp_values = []
+    tpsa_values = []
+    hbd_values = []
+    hba_values = []
+    rotatable_values = []
+    atomic_charges = []
+
+    for idx, smiles in enumerate(smiles_list):
+        mol3d = _embed_smiles_in_3d(smiles, idx)
+        canonical = Chem.MolToSmiles(Chem.RemoveHs(mol3d))
+        frames.append(_rdkit_to_ase_atoms(mol3d, canonical))
+        smiles_labels.append(canonical)
+        atom_counts.append(int(mol3d.GetNumAtoms()))
+        atomic_charges.extend(_extract_gasteiger_charges(mol3d))
+
+        descriptor_mol = Chem.RemoveHs(mol3d)
+        mw_values.append(float(Descriptors.MolWt(mol3d)))
+        logp_values.append(float(Descriptors.MolLogP(descriptor_mol)))
+        tpsa_values.append(float(Descriptors.TPSA(descriptor_mol)))
+        hbd_values.append(float(Descriptors.NumHDonors(descriptor_mol)))
+        hba_values.append(float(Descriptors.NumHAcceptors(descriptor_mol)))
+        rotatable_values.append(float(Descriptors.NumRotatableBonds(descriptor_mol)))
+
+    properties = {
+        "SMILES": {"target": "structure", "values": smiles_labels},
+        "Atom count": {"target": "structure", "values": atom_counts, "units": "atoms"},
+        "Molecular weight (g/mol)": {
+            "target": "structure",
+            "values": mw_values,
+            "units": "g/mol",
+        },
+        "logP": {"target": "structure", "values": logp_values},
+        "TPSA (Ų)": {"target": "structure", "values": tpsa_values, "units": "Ų"},
+        "H-bond donors": {"target": "structure", "values": hbd_values},
+        "H-bond acceptors": {"target": "structure", "values": hba_values},
+        "Rotatable bonds": {"target": "structure", "values": rotatable_values},
+        "Gasteiger charge (e)": {
+            "target": "atom",
+            "values": atomic_charges,
+            "units": "e",
+        },
+    }
+
+    settings = {
+        "map": {
+            "x": {"property": "Molecular weight (g/mol)"},
+            "y": {"property": "logP"},
+            "color": {"property": "TPSA (Ų)"},
+            "size": {"property": "Atom count"},
+        }
+    }
+
+    meta = {
+        "name": "RDKit Chemiscope Explorer",
+        "description": (
+            "Interactive Chemiscope session generated directly inside the RDKit Hugging Face Space."
+        ),
+        "references": [
+            "https://chemiscope.org/docs/python/index.html",
+            "https://chemiscope.org/docs/index.html",
+        ],
+    }
+
+    dataset = chemiscope.create_input(
+        frames=frames,
+        properties=properties,
+        meta=meta,
+        settings=settings,
+    )
+
+    tmp_file = tempfile.NamedTemporaryFile(delete=False, suffix=".json.gz")
+    tmp_file.close()
+    chemiscope.write_input(
+        tmp_file.name,
+        frames=frames,
+        properties=properties,
+        meta=meta,
+        settings=settings,
+    )
+
+    viewer_html = _build_chemiscope_embed(dataset)
+    return viewer_html, tmp_file.name
+
+
 def smiles_to_molecular_orbitals(smiles_input: str, name_input: str) -> str:
     """Generate HOMO/LUMO isosurfaces using Psikit, when available."""
     smiles = smiles_input.strip()
@@ -529,11 +748,31 @@ molecule_3d_interface = gr.Interface(
     examples=[["benzene"], ["aspirin"], ["caffeine"], ["ethanol"]],
 )
 
+chemiscope_interface = gr.Interface(
+    fn=smiles_to_chemiscope_dataset,
+    inputs=gr.Textbox(
+        label="SMILES batch",
+        lines=6,
+        placeholder="One SMILES per line or comma separated (max 12 molecules).",
+    ),
+    outputs=[
+        gr.HTML(label="Chemiscope Viewer"),
+        gr.File(label="Chemiscope Dataset (.json.gz)"),
+    ],
+    api_name="chemiscope_explorer",
+    description=(
+        "Generate a Chemiscope dataset using RDKit + ASE + Chemiscope tooling, then explore it "
+        "directly inside the Space or download the JSON for chemiscope.org."
+    ),
+    examples=[["CCO\nc1ccccc1"]],
+)
+
 
 demo = gr.TabbedInterface(
     [
         name_interface,
         molecule_3d_interface,
+        chemiscope_interface,
         orbital_interface,
         smiles_interface,
         smiles_to_name_interface,
@@ -544,6 +783,7 @@ demo = gr.TabbedInterface(
     [
         "Name to SMILES",
         "3D Molecule Viewer",
+        "Chemiscope Explorer",
         "Molecular Orbitals",
         "SMILES to Canonical",
         "SMILES to Name",
@@ -557,4 +797,4 @@ demo = gr.TabbedInterface(
 
 
 if __name__ == "__main__":
-    demo.queue().launch(server_name="0.0.0.0", server_port=7860)
+    demo.queue().launch(server_name="0.0.0.0", server_port=7860)

requirements.txt

@@ -7,6 +7,8 @@ pubchempy
 psikit
 py3Dmol
 pyscf
+chemiscope
+ase
 plotly
 matplotlib
-pillow
+pillow