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()