retro-tree-visual

retro-tree-visual renders retrosynthesis search trees from SynPlanner, AiZynthFinder, and Syntheseus into the same neutral artifact schema and standalone interactive HTML reports.

The project keeps search navigation separate from successful route normalization:

• search_trace.json.gz: all created/search nodes, edges, metadata, and node timeline.
• routes.json.gz: successful routes in the RetroCast/Procrustes-compatible route layer.
• strategic_bonds.json.gz: optional SynPlanner RouteCGR/SB-CGR strategic-bond clusters.
• run_manifest.json: source tool, target, stock/config, algorithm, budgets, output paths, and warnings.

SynPlanner is used directly for CGR enrichment and strategic-bond clustering. Do not use TreeWrapper; SynPlanner input is a direct synplan.mcts.tree.Tree pickle.

Install

Use the project development environment for renderer, ingestion, and validation work:

conda env create -f environment-dev.yml
conda run -n retro_tree_visual_dev python -m pip install -e 'SynPlanner[cpu]' -e project-procrustes
conda run -n retro_tree_visual_dev python -m pip install --no-deps -e .
conda run -n retro_tree_visual_dev python -m pip install playwright
conda run -n retro_tree_visual_dev python -m playwright install chromium

Ruff is the default formatter and linter:

conda run -n retro_tree_visual_dev python -m ruff format retro_tree_visual tests
conda run -n retro_tree_visual_dev python -m ruff check retro_tree_visual tests

AiZynthFinder is intentionally not installed into retro_tree_visual_dev: the local AiZynthFinder checkout requires numpy <2, while SynPlanner requires numpy >=2. Use a separate fresh AiZynthFinder-only environment when rerunning raw AiZynthFinder searches.

CLI

Render from canonical artifacts:

retro-tree-visual render \
  --trace search_trace.json.gz \
  --routes routes.json.gz \
  --strategic-bonds strategic_bonds.json.gz \
  --target-id apatinib \
  --output index.html

Reports are compact by default and omit embedded node molecule depictions and route SVG previews. Use --depiction-mode full --route-depiction-mode full when you need rich single-file media. Canvas geometry, routes, filters, and target depiction are unchanged.

Export neutral traces from raw planner outputs:

retro-tree-visual export-trace synplanner \
  --tree tree.pkl \
  --output search_trace.json.gz

retro-tree-visual export-trace aizynthfinder \
  --tree full_search_tree.json.gz \
  --algorithm MCTS \
  --output search_trace.json.gz

retro-tree-visual export-trace syntheseus \
  --graph graph.pkl \
  --algorithm MCTS \
  --output search_trace.json.gz

Run the full ingestion pipeline when both trace and successful-route artifacts are available:

retro-tree-visual ingest synplanner \
  --tree tree.pkl \
  --out-dir out/synplanner \
  --html out/synplanner/index.html

retro-tree-visual ingest aizynthfinder \
  --tree full_search_tree.json.gz \
  --routes routes.json.gz \
  --target-id apatinib \
  --out-dir out/aizynthfinder \
  --html out/aizynthfinder/index.html

retro-tree-visual ingest syntheseus \
  --graph graph.pkl \
  --routes routes.json.gz \
  --target-id apatinib \
  --out-dir out/syntheseus \
  --html out/syntheseus/index.html

Apatinib MCTS Run

The canonical Apatinib comparison suite uses 500 search iterations and lives under runs/apatinib_mcts_500/. Older runs/apatinib_mcts_200/ artifacts are historical and should not be treated as the current comparison target.

Target:

N#CC1(c2ccc(NC(=O)c3cccnc3NCc3ccncc3)cc2)CCCC1

Shared search settings:

max_depth = 6
algorithm = MCTS/UCT
iterations = 500

Canonical raw planner outputs, once each source has been regenerated:

runs/apatinib_mcts_500/synplanner/tree.pkl
runs/apatinib_mcts_500/aizynthfinder/full_search_tree.json.gz
runs/apatinib_mcts_500/syntheseus/graph.pkl

Per-engine configs are stored next to each output:

runs/apatinib_mcts_500/synplanner/planning_config.yaml
runs/apatinib_mcts_500/aizynthfinder/config.yml
runs/apatinib_mcts_500/syntheseus/config.yml

Regeneration status:

Engine	Environment	Raw artifact	Result
SynPlanner	retro_tree_visual_dev	synplanner/tree.pkl	regenerated at 500 iterations
AiZynthFinder	fresh AZ-only env	aizynthfinder/full_search_tree.json.gz	regenerate from aizynthfinder/config.yml; do not copy historical 400-iteration artifacts
Syntheseus LocalRetro	source model env	syntheseus/graph.pkl	regenerate from syntheseus/config.yml; do not copy historical 200/3000-iteration artifacts

Notes:

• SynPlanner used the direct Tree API and then pickled the Tree object.
• AiZynthFinder was serialized as plain JSON and then gzipped explicitly, because its native serialize() method writes uncompressed JSON regardless of filename suffix.
• Syntheseus writes native outputs under a model-name subdirectory (syntheseus/LocalRetro/graph.pkl). A convenience copy is stored at syntheseus/graph.pkl.
• The ASKOS stock contains the target molecule, so Syntheseus needed expand_purchasable_target: true to avoid a root-only no-op graph. The original no-op historical run remains under runs/apatinib_mcts_200/.

Architecture

The detailed project documentation starts at docs/README.md.

The ingestion code is split into four testable steps:

1. Source trace extraction from all created/search nodes.
2. Successful-route normalization through RetroCast/Procrustes adapters where available.
3. CGR/SB-CGR enrichment and route-to-trace provenance.
4. Artifact and HTML writing.

The current package layout follows these domains:

• sources/: SynPlanner, AiZynthFinder, and Syntheseus trace extraction.
• routes/: route traversal, statistics, and route-to-trace provenance.
• chemistry/: atom mapping, RouteCGR/SB-CGR composition, depiction, and strategic bonds.
• render/: payload building, radial layout, HTML template, and renderer entrypoints.
• artifacts/: JSON/gzip I/O and HTML suite comparison.
• ingest/: thin orchestration for the four ingestion steps.

Use the domain packages directly. Legacy flat shim imports such as retro_tree_visual.render_html have been removed.