Visualization Utilities

---
name: visualization-utilities
description: "Guides agents using datamol visualization, molecule image
  rendering, lasso highlighting, dataframe display, parallel utilities,
  filesystem helpers, RDKit log controls, and environment diagnostics."
disable-model-invocation: true
metadata:
  disco-role: operating
license: Apache 2.0
---

# Visualization Utilities

Use this sub-skill when the task asks to render molecules, save SVG/PNG depictions, highlight substructures, display molecule dataframes, visualize existing conformers, run small datamol utility jobs, inspect fsspec paths, silence RDKit logs, or diagnose datamol/RDKit runtime behavior.

## Route First

- For molecule parsing, cleanup, dataframe construction, SDF/CSV/XLSX IO, or property preservation before rendering, use `../molecule-io-prep/` first.
- For conformer generation, 3D coordinate creation, SASA, alignment, scaffolds, fragments, reactions, tautomers, or isomers, use `../structure-generation/` first.
- For fingerprints, clustering, distance matrices, MCS, graph comparisons, or diversity selection before visualization, use `../fingerprints-similarity/` first.

## What This Covers

- 2D grids with `dm.viz.to_image()` or top-level `dm.to_image()` from SMILES or RDKit molecules.
- SMARTS, query-molecule, and explicit atom-index highlighting with `dm.viz.lasso_highlight_image()` and `dm.viz.match_substructure()`.
- File and notebook output choices, including SVG strings, Pillow PNG objects, and `outfile` paths handled through fsspec.
- Existing-conformer display with `dm.viz.conformers()` when optional notebook widgets are installed and conformers already exist.
- Utility helpers: `dm.parallelized()`, `dm.parallelized_with_batches()`, `dm.JobRunner`, `dm.utils.fs`, `dm.utils.perf.watch_duration`, `dm.utils.decorators.disable_on_os`, and RDKit log/version helpers.

## Reference Map

- Use `references/api-reference.md` for signatures, parameters, return types, utility helper notes, and ownership boundaries.
- Use `references/workflows.md` for SVG/PNG rendering, lasso highlights, dataframe rendering, parallel jobs, fsspec checks, RDKit log control, and diagnostics recipes.
- Use `references/troubleshooting.md` for headless rendering, invalid highlight indices, SVG/PNG/Pillow issues, notebook assumptions, fsspec URI errors, and joblib pickling failures.
- Run `scripts/visualization_utility_smoke.py --help` for a safe executable smoke test, or run it with `--output-dir <dir>` to render a tiny SVG and exercise utility helpers.

## Decision Checklist

1. Normalize input molecules with the root skill or `../molecule-io-prep/` if the task starts from mixed files, tables, or potentially invalid SMILES.
2. Choose `use_svg=True` for deterministic text artifacts and `use_svg=False` only when the caller explicitly needs PNG/Pillow output.
3. Prefer `lasso_highlight_image()` for publication-style outline highlights and `to_image(highlight_atom=..., highlight_bond=...)` or `match_substructure()` for simple RDKit grid highlights.
4. Keep parallel helper callables top-level or otherwise picklable when using process workers; use `scheduler="threads"` or `n_jobs=0/1` for closures and notebook workflows.
5. Wrap noisy parsing or rendering probes in `dm.without_rdkit_log()` and restore global logs with `dm.enable_rdkit_log()` after temporary global muting.