vibe-sketcherDocumentation

Source code for vibesketcher.document.property_data

"""Bounded, read-only property comparisons (#166).

Calculator definitions and literature citations remain in ``chem.analysis``.
The graph source is each species' stored SMILES; no layout or geometry is
generated. Molecular masses use the same rounding as ``chem.report``.
"""

from __future__ import annotations

import csv
import hashlib
import io
import json
import math
from collections.abc import Callable, Sequence
from typing import Any

from vibesketcher.document.model import Document, Species
from vibesketcher.document.properties import PropertiesRefused

MAX_ROWS = 1000
MAX_ATOMS = 25_000
MAX_PAGE = 100

# key, label, unit, calculator, requirement, estimate. These are the existing
# report's fields; adding a calculator is a separate scientific scope decision.
_COLUMNS = (
    ("label", "Label", None, "document", "metadata", False),
    ("smiles", "SMILES", None, "document", "metadata", False),
    (
        "formula",
        "Formula",
        None,
        "CalcMolFormula / recorded material formula",
        "composition",
        False,
    ),
    (
        "average_mass",
        "Average molar mass",
        "g/mol",
        "MolWt / recorded material mass",
        "composition",
        False,
    ),
    (
        "monoisotopic_mass",
        "Monoisotopic mass",
        "Da",
        "ExactMolWt / composition",
        "composition",
        False,
    ),
    ("analysis", "Elemental analysis", None, "elemental_analysis.line", "graph", False),
    (
        "mass_percent",
        "Elemental mass percentages",
        "%",
        "elemental_analysis.mass_percent",
        "graph",
        False,
    ),
    ("logp", "logP (estimate)", None, "Crippen.MolLogP", "graph", True),
    ("molar_refractivity", "MR (estimate)", "cm³/mol", "Crippen.MolMR", "graph", True),
    ("tpsa", "TPSA (estimate)", "Ų", "CalcTPSA (N, O)", "graph", True),
    ("hbond_donors", "H-bond donors", None, "CalcNumLipinskiHBD", "graph", False),
    ("hbond_acceptors", "H-bond acceptors", None, "CalcNumLipinskiHBA", "graph", False),
    ("rotatable_bonds", "Rotatable bonds", None, "CalcNumRotatableBonds", "graph", False),
    ("heavy_atoms", "Heavy atoms", None, "GetNumHeavyAtoms", "graph", False),
    ("rings", "Rings", None, "CalcNumRings (SSSR)", "graph", False),
)
COLUMNS: tuple[dict[str, Any], ...] = tuple(
    dict(key=k, label=label, unit=unit, calculator=calculator, requires=requires, estimate=estimate)
    for k, label, unit, calculator, requires, estimate in _COLUMNS
)
MEDIA_TYPES = {
    "json": "application/json",
    "csv": "text/csv",
    "markdown": "text/markdown",
    "latex": "application/x-latex",
}


[docs] def snapshot_digest(document: Document) -> str: """SHA-256 of the full canonical JSON snapshot, including its revision.""" from vibesketcher.limits import check_size try: data = json.dumps( document.to_json_data(), sort_keys=True, ensure_ascii=False, separators=(",", ":"), allow_nan=False, ) check_size(data, "property-table snapshot") except ValueError as error: raise PropertiesRefused(str(error)) from error return hashlib.sha256(data.encode()).hexdigest()
def _values(species: Species, mol: Any, needed: set[str]) -> tuple[dict[str, Any], dict[str, str]]: from vibesketcher.chem.analysis import descriptors, elemental_analysis from vibesketcher.chem.species import properties values: dict[str, Any] = {"label": species.label, "smiles": species.smiles} errors: dict[str, str] = {} if mol is not None: mass_keys = {"formula", "average_mass", "monoisotopic_mass"} analysis_keys = {"analysis", "mass_percent"} descriptor_keys = {c["key"] for c in COLUMNS if c["requires"] == "graph"} - analysis_keys if needed & mass_keys: try: props = properties(mol) values.update( formula=props.formula, average_mass=round(props.average_mass, 4), monoisotopic_mass=round(props.monoisotopic_mass, 6), ) except (ValueError, RuntimeError) as error: errors.update({k: str(error) for k in mass_keys}) if needed & analysis_keys: try: analysis = elemental_analysis(mol) values.update(analysis=analysis.line, mass_percent=analysis.mass_percent) except (ValueError, RuntimeError) as error: errors.update({k: str(error) for k in analysis_keys}) if needed & descriptor_keys: try: values.update(descriptors(mol).to_dict()) except (ValueError, RuntimeError) as error: errors.update({k: str(error) for k in descriptor_keys}) elif species.solid is not None: from vibesketcher.chem.formula import parse_formula mono = parse_formula(species.solid.text).monoisotopic_mass() values.update( formula=species.solid.text, average_mass=species.solid.molar_mass_g_mol, monoisotopic_mass=round(mono, 6) if mono is not None else None, ) elif species.nanostructure is not None: from vibesketcher.document.nanostructures import masses average, mono = masses(species.conformers[0].symbols) values.update( formula=species.nanostructure.formula, average_mass=average, monoisotopic_mass=mono ) return values, errors
[docs] def property_data( document: Document, *, columns: Sequence[str] | None = None, species: Sequence[str] | None = None, sort: str | None = None, descending: bool = False, offset: int = 0, limit: int | None = None, progress: Callable[[int, int], None] | None = None, cancelled: Callable[[], bool] | None = None, ) -> dict[str, Any]: """Compare stored species, preserving row failures and source order. Cancellation is checked between rows. A cancelled result is explicitly incomplete and contains only completed rows, before pagination. Native RDKit calls are not promised to be interruptible. Sorting precedes paging; each request's calculation is bounded by MAX_ROWS and MAX_ATOMS. """ from rdkit import rdBase from vibesketcher import __version__ from vibesketcher.chem.species import mol_from_smiles known = {c["key"] for c in COLUMNS} chosen = list(columns) if columns is not None else [c["key"] for c in COLUMNS] if not chosen or len(chosen) != len(set(chosen)) or set(chosen) - known: raise PropertiesRefused("choose distinct property columns from " + ", ".join(sorted(known))) if sort is not None and sort not in known | {"species"}: raise PropertiesRefused("sort must name a property column or species") if descending and sort is None: raise PropertiesRefused("descending requires a sort column") needed = set(chosen) | ({sort} if sort and sort != "species" else set()) if offset < 0 or (limit is not None and not 1 <= limit <= MAX_ROWS): raise PropertiesRefused(f"offset must be nonnegative; limit must be 1 to {MAX_ROWS}") snapshot = document.model_copy(deep=True) digest = snapshot_digest(snapshot) ids = [s.id for s in snapshot.species] wanted = list(species) if species is not None else ids if len(wanted) != len(set(wanted)) or set(wanted) - set(ids): raise PropertiesRefused("choose distinct species IDs from the document") wanted_set = set(wanted) selected = [s for s in snapshot.species if s.id in wanted_set] if len(selected) > MAX_ROWS: raise PropertiesRefused(f"property tables support at most {MAX_ROWS} species") # Parse and count before descriptor calculation, including atoms from # generated material conformers. Invalid graph rows get explicit errors. prepared: list[tuple[Species, Any, str | None]] = [] atoms = 0 was_cancelled = False for item in selected: if cancelled is not None and cancelled(): was_cancelled = True break mol: Any = None reason = None try: if item.smiles: mol = mol_from_smiles(item.smiles) atoms += int(mol.GetNumAtoms()) elif item.nanostructure is not None and item.conformers: atoms += len(item.conformers[0].symbols) except KeyboardInterrupt: was_cancelled = True break except (ValueError, RuntimeError) as error: reason = str(error) if atoms > MAX_ATOMS: raise PropertiesRefused(f"property tables support at most {MAX_ATOMS} explicit atoms") prepared.append((item, mol, reason)) rows: list[dict[str, Any]] = [] total = len(selected) try: for item, mol, reason in [] if was_cancelled else prepared: if cancelled is not None and cancelled(): was_cancelled = True break values: dict[str, Any] = {"label": item.label, "smiles": item.smiles} cell_errors: dict[str, str] = {} if reason is None: try: values, cell_errors = _values(item, mol, needed) except (ValueError, RuntimeError, IndexError) as error: reason = str(error) fields: dict[str, Any] = {} errors: dict[str, str] = {} for key in dict.fromkeys([*chosen, *([sort] if sort and sort != "species" else [])]): value = values.get(key) nonfinite = isinstance(value, float) and not math.isfinite(value) if isinstance(value, dict): nonfinite = any( isinstance(v, float) and not math.isfinite(v) for v in value.values() ) if nonfinite: value = None fields[key] = value if value is None and key not in {"label", "smiles"}: errors[key] = ( reason or cell_errors.get(key) or ("calculator returned a nonfinite value" if nonfinite else None) or ( "requires a molecular graph" if key in known and next(c for c in COLUMNS if c["key"] == key)["requires"] == "graph" else "unavailable for this composition" ) ) visible_errors = errors quantitative = set(chosen) - {"label", "smiles"} status = ( ("error" if quantitative and quantitative <= set(visible_errors) else "partial") if visible_errors else "ok" ) rows.append( {"species": item.id, "values": fields, "status": status, "errors": visible_errors} ) if progress is not None: progress(len(rows), total) except KeyboardInterrupt: was_cancelled = True if sort: def key(row: dict[str, Any]) -> Any: value = row["species"] if sort == "species" else row["values"].get(sort) return json.dumps(value, sort_keys=True) if isinstance(value, dict) else value available = [r for r in rows if key(r) is not None] missing = [r for r in rows if key(r) is None] rows = sorted(available, key=key, reverse=descending) + missing completed = len(rows) page = rows[offset : offset + limit if limit is not None else None] for row in page: row["values"] = {k: row["values"][k] for k in chosen} return { "schema": "vibesketcher.property-table/1", "source": {"revision": snapshot.revision, "sha256": digest}, "software": {"vibesketcher": __version__, "rdkit": rdBase.rdkitVersion}, "graph_source": "stored species SMILES; no geometry or layout generated", "selection": [item.id for item in selected], "sort": {"column": sort, "descending": descending}, "columns": [dict(next(c for c in COLUMNS if c["key"] == k)) for k in chosen], "total": total, "completed": completed, "cancelled": was_cancelled, "offset": offset, "rows": page, }
[docs] def render_property_data(data: dict[str, Any], format: str) -> bytes: """Encode a comparison; CSV stays machine-readable, provenance lives in JSON.""" from vibesketcher.document.tables import _latex, _markdown if format == "json": return (json.dumps(data, ensure_ascii=False, allow_nan=False, indent=2) + "\n").encode() if format not in MEDIA_TYPES: raise PropertiesRefused("table format must be csv, markdown, latex or json") columns = [c["key"] for c in data["columns"]] if format == "csv": headers = [ "species", *(c["key"] + ("_estimate" if c["estimate"] else "") for c in data["columns"]), "status", "errors_json", ] else: headers = [ "Species", *(c["label"] + (f" ({c['unit']})" if c["unit"] else "") for c in data["columns"]), "Status", "Unavailable/error reasons", ] rows = [headers] for row in data["rows"]: values = [ row["species"], *(row["values"].get(k) for k in columns), row["status"], row["errors"], ] rows.append( [ "" if v is None else json.dumps(v, ensure_ascii=False, sort_keys=True) if isinstance(v, dict) else str(v) for v in values ] ) if format == "csv": stream = io.StringIO(newline="") writer = csv.writer(stream, lineterminator="\n") writer.writerows(rows) return stream.getvalue().encode() if format == "markdown": lines = ["| " + " | ".join(_markdown(v) for v in row) + " |" for row in rows] lines.insert(1, "| " + " | ".join("---" for _ in headers) + " |") else: lines = [r"\begin{tabular}{" + "l" * len(headers) + "}"] lines += [" & ".join(_latex(v) for v in row) + r" \\" for row in rows] lines.append(r"\end{tabular}") lines.append( "Calculated descriptors are estimates; JSON includes calculator definitions, " "units and provenance." ) return ("\n".join(lines) + "\n").encode()