eagleplot 3.0.0__py3-none-any.whl

eagleplot/nist.py

@@ -0,0 +1,241 @@
+"""NIST Chemistry WebBook integration.
+
+Provides functions to fetch IR spectra and compound information from the
+NIST Chemistry WebBook (https://webbook.nist.gov) using CAS Registry Numbers
+or compound names.
+
+No authentication is required. Requires the ``requests`` package.
+
+Public API
+----------
+fetch_ir_spectrum(cas_or_id, index=0) -> pd.DataFrame
+    Download the IR JCAMP-DX spectrum for a compound and return as DataFrame.
+get_compound_url(cas_or_id) -> str
+    Return the NIST WebBook URL for a compound page.
+get_ir_jcamp_url(cas_or_id, index=0) -> str
+    Return the direct JCAMP-DX download URL for an IR spectrum.
+search_url(query, by='name') -> str
+    Return the NIST WebBook search URL (for 'name' or 'formula' queries).
+list_ir_spectra(cas_or_id) -> list[dict]
+    Return metadata for all available IR spectra for a compound.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from typing import Any, Dict, List
+
+import numpy as np  # noqa: F401  (kept for downstream users who import from this module)
+
+_NIST_BASE = "https://webbook.nist.gov/cgi/cbook.cgi"
+
+
+def _to_nist_id(cas_or_id: str) -> str:
+    """Convert a CAS number to NIST compound ID format (e.g. '64-17-5' → 'C64175').
+
+    If the value already looks like a NIST ID (starts with a letter other than
+    a digit), it is returned unchanged.
+    """
+    stripped = cas_or_id.strip()
+    # Already a NIST-style ID (e.g. 'C64175', 'InChI=...') — leave it alone
+    if not stripped[0].isdigit():
+        return stripped
+    # CAS number: strip dashes and prepend 'C'
+    return "C" + stripped.replace("-", "")
+
+
+def get_compound_url(cas_or_id: str) -> str:
+    """Return the NIST WebBook compound page URL for a CAS number or NIST ID.
+
+    Parameters
+    ----------
+    cas_or_id : str
+        CAS Registry Number (e.g. ``'64-17-5'``) or NIST compound ID
+        (e.g. ``'C64175'``).
+
+    Returns
+    -------
+    str
+        Full URL to the compound's NIST WebBook page.
+
+    Examples
+    --------
+    >>> get_compound_url('64-17-5')
+    'https://webbook.nist.gov/cgi/cbook.cgi?ID=64-17-5&Units=SI'
+    """
+    return f"{_NIST_BASE}?ID={cas_or_id}&Units=SI"
+
+
+def get_ir_jcamp_url(cas_or_id: str, index: int = 0) -> str:
+    """Return the direct JCAMP-DX download URL for an IR spectrum.
+
+    Parameters
+    ----------
+    cas_or_id : str
+        CAS Registry Number (e.g. ``'64-17-5'``) or NIST compound ID
+        (e.g. ``'C64175'``).
+    index : int, default 0
+        Spectrum index (0 = first available IR spectrum).
+
+    Returns
+    -------
+    str
+        Direct URL to the JCAMP-DX file.
+
+    Notes
+    -----
+    NIST's JCAMP endpoint uses ``?JCAMP=<compound_id>`` as the primary
+    parameter, where the compound ID is the CAS number with dashes removed
+    and a ``C`` prefix (e.g. CAS ``64-17-5`` → ``C64175``).
+    """
+    nist_id = _to_nist_id(cas_or_id)
+    return f"{_NIST_BASE}?JCAMP={nist_id}&Index={index}&Type=IR-SPEC"
+
+
+def search_url(query: str, by: str = "name") -> str:
+    """Return a NIST WebBook search URL.
+
+    Parameters
+    ----------
+    query : str
+        Search term.
+    by : {'name', 'formula', 'cas'}, default 'name'
+        Search type.
+
+    Returns
+    -------
+    str
+        NIST WebBook search URL (open in a browser or via requests).
+    """
+    query_enc = query.replace(" ", "+")
+    if by == "formula":
+        return f"{_NIST_BASE}?Formula={query_enc}&Units=SI&cST=on"
+    elif by == "cas":
+        return get_compound_url(query)
+    else:
+        return f"{_NIST_BASE}?Name={query_enc}&Units=SI&cST=on"
+
+
+def fetch_ir_spectrum(cas_or_id: str, index: int = 0) -> Any:
+    """Download the IR spectrum for a compound from NIST WebBook.
+
+    Fetches the JCAMP-DX file for the given compound and returns it as a
+    ``pd.DataFrame`` with columns ``x`` (wavenumber, cm⁻¹) and ``y``
+    (absorbance or transmittance). Compound metadata is stored in
+    ``df.attrs``.
+
+    Parameters
+    ----------
+    cas_or_id : str
+        CAS Registry Number (e.g. ``'64-17-5'``) or NIST compound ID.
+    index : int, default 0
+        Spectrum index when multiple IR spectra are available.
+
+    Returns
+    -------
+    pd.DataFrame
+        Columns: ``x`` (wavenumber, cm⁻¹), ``y`` (absorbance / transmittance).
+        ``df.attrs`` contains JCAMP metadata (``TITLE``, ``DATA TYPE``, etc.).
+
+    Raises
+    ------
+    ImportError
+        If ``requests`` is not installed.
+    RuntimeError
+        If the NIST server returns a non-200 status or no spectrum is found.
+
+    Examples
+    --------
+    >>> df = fetch_ir_spectrum('64-17-5')  # ethanol
+    >>> df.columns.tolist()
+    ['x', 'y']
+    >>> df.attrs.get('TITLE')
+    'Ethanol'
+    """
+    try:
+        import requests
+    except ImportError as exc:
+        raise ImportError(
+            "requests is required for NIST WebBook access. Install it with: pip install requests"
+        ) from exc
+
+    from eagleplot.io import load_jcamp
+
+    url = get_ir_jcamp_url(cas_or_id, index)
+    resp = requests.get(url, timeout=15)
+    if resp.status_code != 200:
+        raise RuntimeError(
+            f"NIST WebBook returned HTTP {resp.status_code} for CAS '{cas_or_id}'. "
+            "Check that the CAS number is correct and the spectrum exists."
+        )
+    content = resp.text
+    if "##TITLE=" not in content and "##title=" not in content.lower():
+        raise RuntimeError(
+            f"No IR spectrum found for CAS '{cas_or_id}' (index={index}). "
+            "The compound may not have an IR spectrum in NIST WebBook."
+        )
+
+    # Write to a temp file so load_jcamp can parse it
+    with tempfile.NamedTemporaryFile(
+        mode="w", suffix=".jdx", delete=False, encoding="utf-8"
+    ) as tmp:
+        tmp.write(content)
+        tmp_path = tmp.name
+
+    try:
+        df = load_jcamp(tmp_path)
+    finally:
+        os.unlink(tmp_path)
+
+    df.attrs["nist_cas"] = cas_or_id
+    df.attrs["nist_url"] = get_compound_url(cas_or_id)
+    return df
+
+
+def list_ir_spectra(cas_or_id: str) -> List[Dict[str, Any]]:
+    """List available IR spectra for a compound on NIST WebBook.
+
+    Attempts to fetch the first few spectrum indices (0–4) and returns
+    metadata for each one that exists.
+
+    Parameters
+    ----------
+    cas_or_id : str
+        CAS Registry Number or NIST compound ID.
+
+    Returns
+    -------
+    list of dict
+        Each dict has keys: ``index`` (int), ``url`` (str),
+        ``title`` (str), ``data_type`` (str).
+        Empty list if no spectra are found or ``requests`` is not available.
+    """
+    try:
+        import requests
+    except ImportError:
+        return []
+
+    results = []
+    for idx in range(5):
+        url = get_ir_jcamp_url(cas_or_id, idx)
+        try:
+            resp = requests.get(url, timeout=10)
+            if resp.status_code != 200:
+                break
+            content = resp.text
+            if "##TITLE=" not in content and "##title=" not in content.lower():
+                break
+            title = ""
+            data_type = ""
+            for line in content.splitlines():
+                if line.upper().startswith("##TITLE="):
+                    title = line.split("=", 1)[1].strip()
+                elif line.upper().startswith("##DATA TYPE="):
+                    data_type = line.split("=", 1)[1].strip()
+                if title and data_type:
+                    break
+            results.append({"index": idx, "url": url, "title": title, "data_type": data_type})
+        except Exception:
+            break
+    return results

eagleplot/pages/10_Molecular_Viz.py

@@ -0,0 +1,225 @@
+"""Molecular Visualization page.
+
+Upload a Gaussian (.log), ORCA (.out), or Molden (.molden) output file,
+parse the vibrational frequency data, and visualize the molecular structure
+and normal mode displacement vectors interactively in 3D using Plotly.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+import tempfile
+import os
+
+import pandas as pd
+import streamlit as st
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from eagleplot.utils.session_state import initialize_session_state
+from eagleplot.molecular import (
+    VibrationalData,
+    build_molecule_figure,
+    parse_vibrations,
+)
+
+initialize_session_state()
+
+st.title("Molecular Visualization")
+st.caption(
+    "Upload a quantum chemistry output file to visualize molecular structure "
+    "and normal-mode vibrational displacements in 3D."
+)
+
+# ─────────────────────────────────────────────────────────────────────────────
+# File uploader
+# ─────────────────────────────────────────────────────────────────────────────
+uploaded = st.file_uploader(
+    "Upload a vibrational frequency output file",
+    type=["log", "out", "molden"],
+    help="Supported formats: Gaussian .log/.out, ORCA .out, Molden .molden",
+)
+
+if uploaded is None:
+    st.info("Upload a Gaussian `.log`, ORCA `.out`, or Molden `.molden` file to begin.")
+    st.stop()
+
+# ── Parse the uploaded file ────────────────────────────────────────────────
+ext = Path(uploaded.name).suffix.lower()
+suffix_map = {".log": ".log", ".out": ".out", ".molden": ".molden"}
+file_suffix = suffix_map.get(ext, ".out")
+
+tmp_path = None
+vib_data: VibrationalData | None = st.session_state.mol_vib_data
+
+# Re-parse if the uploaded filename changed (or first load).
+if vib_data is None or st.session_state.get("mol_vib_filename") != uploaded.name:
+    with tempfile.NamedTemporaryFile(suffix=file_suffix, mode="wb", delete=False) as tmp:
+        tmp.write(uploaded.read())
+        tmp_path = tmp.name
+
+    try:
+        vib_data = parse_vibrations(tmp_path)
+        st.session_state.mol_vib_data = vib_data
+        st.session_state["mol_vib_filename"] = uploaded.name
+        st.success(
+            f"Parsed **{uploaded.name}** — {vib_data.program.title()} format, "
+            f"{len(vib_data.atomic_numbers)} atoms, {len(vib_data.modes)} modes."
+        )
+    except Exception as exc:
+        st.error(f"Failed to parse file: {exc}")
+        if tmp_path and os.path.exists(tmp_path):
+            os.unlink(tmp_path)
+        st.stop()
+    finally:
+        if tmp_path and os.path.exists(tmp_path):
+            os.unlink(tmp_path)
+
+if vib_data is None:
+    st.stop()
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Summary table
+# ─────────────────────────────────────────────────────────────────────────────
+with st.expander("Vibrational Frequency Summary", expanded=False):
+    if vib_data.modes:
+        freq_df = pd.DataFrame(
+            {
+                "Mode #": [m.mode_number for m in vib_data.modes],
+                "Frequency (cm⁻¹)": [m.frequency for m in vib_data.modes],
+                "IR Intensity (km/mol)": [
+                    (f"{m.ir_intensity:.2f}" if m.ir_intensity is not None else "—")
+                    for m in vib_data.modes
+                ],
+                "Imaginary": ["Yes" if m.is_imaginary else "No" for m in vib_data.modes],
+            }
+        )
+        st.dataframe(freq_df, width="stretch")
+    else:
+        st.info("No vibrational modes found in the file.")
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Visualization controls
+# ─────────────────────────────────────────────────────────────────────────────
+st.subheader("3D Molecular Structure")
+
+show_arrows = st.checkbox("Show vibrational displacement arrows", value=False)
+
+mode_number = None
+arrow_color = "red"
+arrow_scale = 1.0
+amplitude = 1.0
+
+if show_arrows and vib_data.modes:
+    mode_numbers = [m.mode_number for m in vib_data.modes]
+    freqs = [m.frequency for m in vib_data.modes]
+    mode_labels = [f"Mode {n}: {f:.1f} cm⁻¹" for n, f in zip(mode_numbers, freqs)]
+
+    selected_label = st.selectbox("Vibrational mode", mode_labels, key="mol_mode_sel")
+    mode_number = mode_numbers[mode_labels.index(selected_label)]
+
+    col1, col2, col3 = st.columns(3)
+    with col1:
+        arrow_color = st.color_picker("Arrow color", value="#FF0000", key="mol_arrow_color")
+    with col2:
+        arrow_scale = st.slider(
+            "Arrow visual scale",
+            min_value=0.1,
+            max_value=5.0,
+            value=1.0,
+            step=0.1,
+            key="mol_arrow_scale",
+        )
+    with col3:
+        amplitude = st.slider(
+            "Displacement amplitude",
+            min_value=0.1,
+            max_value=5.0,
+            value=1.0,
+            step=0.1,
+            key="mol_amplitude",
+        )
+elif show_arrows and not vib_data.modes:
+    st.warning("No vibrational modes available in this file.")
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Build and display figure
+# ─────────────────────────────────────────────────────────────────────────────
+try:
+    fig = build_molecule_figure(
+        vib_data,
+        mode_number=mode_number,
+        arrow_color=arrow_color,
+        arrow_scale=float(arrow_scale),
+        amplitude=float(amplitude),
+    )
+    title_text = uploaded.name
+    if mode_number is not None:
+        mode_obj = vib_data.get_mode(mode_number)
+        if mode_obj:
+            title_text += f" — Mode {mode_number} ({mode_obj.frequency:.1f} cm⁻¹)"
+    fig.update_layout(title=title_text, height=600)
+    st.plotly_chart(fig, width="stretch")
+except Exception as exc:
+    st.error(f"Error building figure: {exc}")
+    st.stop()
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Export
+# ─────────────────────────────────────────────────────────────────────────────
+st.subheader("Export")
+
+col1, col2 = st.columns(2)
+
+with col1:
+    if st.button("Export as interactive HTML", key="mol_export_html"):
+        try:
+            html_str = fig.to_html(full_html=True, include_plotlyjs="cdn")
+            st.download_button(
+                "Download HTML",
+                data=html_str,
+                file_name=f"{Path(uploaded.name).stem}_mol.html",
+                mime="text/html",
+                key="mol_dl_html",
+            )
+        except Exception as exc:
+            st.error(str(exc))
+
+with col2:
+    if vib_data.modes and st.button("Download frequency table (CSV)", key="mol_dl_csv"):
+        freq_df_dl = pd.DataFrame(
+            {
+                "mode": [m.mode_number for m in vib_data.modes],
+                "frequency_cm-1": [m.frequency for m in vib_data.modes],
+                "ir_intensity_km_per_mol": [
+                    (m.ir_intensity if m.ir_intensity is not None else float("nan"))
+                    for m in vib_data.modes
+                ],
+                "is_imaginary": [m.is_imaginary for m in vib_data.modes],
+            }
+        )
+        csv_bytes = freq_df_dl.to_csv(index=False).encode()
+        st.download_button(
+            "Download CSV",
+            data=csv_bytes,
+            file_name=f"{Path(uploaded.name).stem}_frequencies.csv",
+            mime="text/csv",
+            key="mol_dl_csv_btn",
+        )
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Atom coordinates table
+# ─────────────────────────────────────────────────────────────────────────────
+with st.expander("Atomic Coordinates", expanded=False):
+    from eagleplot.molecular.atom_data import get_atom_symbol
+
+    coord_df = pd.DataFrame(
+        {
+            "Atom": [get_atom_symbol(z) for z in vib_data.atomic_numbers],
+            "X (Å)": vib_data.coordinates[:, 0],
+            "Y (Å)": vib_data.coordinates[:, 1],
+            "Z (Å)": vib_data.coordinates[:, 2],
+        }
+    )
+    st.dataframe(coord_df, width="stretch")