alchemy-viz

Browser-based visualizations for OpenFE and gufe objects: ligands, proteins, atom mappings, ligand networks and alchemical campaigns.

Install

conda activate my-openfe-env
pip install "alchemy-viz[notebook]"   # the notebook extra is optional

gufe must be installed from conda-forge, not pip.

Use

From the shell, alchemy-viz accepts as inputs anything from openfe plan-rbfe-network:

alchemy-viz network_setup/network_setup.json -o campaign.html
alchemy-viz network_setup/ligand_network.graphml     # writes <input>.html beside it
alchemy-viz ligand.json -o -                         # or stdout

One self-contained HTML file is created.

From Python, on the object itself:

from alchemy_viz import view, to_html

view(network)        # a LigandNetwork, drawn in a notebook cell
view(ligand)         # a SmallMoleculeComponent, ProteinComponent, ChemicalSystem...
html = to_html(obj)  # the same page as a string; writes nothing

view() takes a live gufe object or an alchemy-viz payload dict.

Embedding into a webpage

Embed the visualization module directly into your own websites:

npm install alchemy-viz

import "alchemy-viz";
// Or from a CDN with no build step:
// import "https://cdn.jsdelivr.net/gh/omsf-eco-infra/alchemy-viz@main/python/alchemy_viz/_assets/alchemy-viz.js";
import type { AlchemyVizPayload } from "alchemy-viz";

const payload: AlchemyVizPayload = await (await fetch("payload.json")).json();

const view = document.createElement("alchemy-view");
document.body.append(view);
view.payload = payload;

Documentation

Two notebooks: demo is basic usage while gallery shows the examples as images so you can see the outputs in github

Development

Requires pixi.

git clone https://github.com/omsf-eco-infra/alchemy-viz.git
cd alchemy-viz
pixi install
pixi run dev     # vite: /gallery.html, /gallery-all.html, /parity.html, / (dropzone)
pixi run test    # both suites
pixi run ci      # what CI runs: lint, tests, generated-artifact freshness

Adding a view

1. Add a $def to schema/alchemy-viz.schema.json, named exactly for the type const it declares - both validators find a branch by that name.
2. Build the payload in python/alchemy_viz/ (components.py, networks.py or alchemical.py) and add it to the isinstance dispatch. Ask the gufe object to serialize itself; never reach into its JSON.
3. pixi run types.
4. Write ts/src/views/<type>.ts: a class extending AlchemyElement<Payload> with one renderView(host, payload), returning { onResize, cleanup } if it owns anything that must be released.
5. Add the tag to VIEW_TAGS in ts/src/alchemy-view.ts and an import in ts/src/index.ts.
6. pixi run examples, add mutation rows, then pixi run build && pixi run test.
7. Add a row to the table in docs/views.md and a NOTES entry in scripts/make_gallery.py, then pixi run gallery. Neither is checked by CI, so a new view is invisible in the docs until this step.

A declared type with no view renders as "no visualization for X yet", which is correct behaviour; a view whose type the schema does not declare fails the tests.

Releasing

setuptools-scm derives the version from the git tag, so tagging is the release:

git tag -a v0.1.0 -m "v0.1.0" && git push origin v0.1.0

Support

This work was supported by the National Science Foundation under Grant No. 2303740, via the Open Molecular Science Foundation.

Licence

MIT.