Visualization

2D depiction of a transformation’s common core and soft-core regions.

Ported from BuildEdges.draw_softcore / _draw_molecule. Renders SVG rather than raster images so the output embeds directly in an HTML report with no image encoding, no Pillow dependency, and no loss of legibility when a reader zooms in on a crowded ring.

rbfenetmap.viz.depict.CORE_COLOR = (0.55, 0.75, 0.92)

cool, meaning “this is held fixed”.

Type:

Common-core highlight

rbfenetmap.viz.depict.SOFTCORE_COLOR = (0.96, 0.55, 0.32)

warm, meaning “this changes”.

Type:

Soft-core highlight

rbfenetmap.viz.depict.render_edge_svg(edge, ligands, *, width=520, height=420, show_indices=False, show_hydrogens=True)[source]

Return the (source_svg, target_svg) depictions for one transformation.

Parameters:
Return type:

tuple[str, str]

rbfenetmap.viz.depict.render_molecule_svg(mol, *, softcore=(), core=(), width=520, height=420, title='', show_indices=False, show_hydrogens=True)[source]

Return an SVG string of mol with its soft-core and core atoms highlighted.

Parameters:

  • mol (rdkit.Chem.Mol)

  • softcore (Sequence[int], optional) – Atom indices to highlight.

  • core (Sequence[int], optional) – Atom indices to highlight.

  • width (int, optional) – Canvas size in pixels.

  • height (int, optional) – Canvas size in pixels.

  • title (str, optional) – Caption drawn under the structure.

  • show_indices (bool, optional) – Label atoms with their indices, which is what makes a depiction usable for debugging a mapping rather than merely looking at it.

  • show_hydrogens (bool, optional) – Draw the explicit hydrogens. On by default because mappings are stated over every atom index including hydrogens, so a hydrogen-suppressed picture cannot show what the mapping actually did.

Returns:

A standalone <svg> document.

Return type:

str

Notes

The depiction is of the molecule exactly as loaded. Nothing here re-sanitizes or re-perceives it, because doing so adds atoms that are not in the input: dropping the explicit hydrogens frees up valence, and the next SanitizeMol fills it back in with implicit hydrogens. Where the input’s bond orders are already wrong – an all-single-bond mol2, say – that invention is silent and large, turning carbonyls into alcohols and aromatic rings into saturated ones. Drawing the molecule untouched means a wrong picture is always the input’s fault and never this function’s.

Inline SVG rendering of the selected network graph.

Hand-rolled rather than delegated to matplotlib or plotly: the output has to embed in a self-contained HTML report with no external assets, and a spring layout plus a few hundred bytes of SVG does that without adding a plotting dependency.

rbfenetmap.viz.network_svg.render_network_svg(network, *, width=None, height=None, seed=7, margin=60, edge_links=None)[source]

Return a standalone SVG of the selected network.

Edge stroke width encodes cost: cheap, high-confidence transformations are drawn heavier, so the reliable backbone of the network reads at a glance. Nodes not touched by any selected edge are drawn hollow, which makes an unconnected ligand visible rather than something the reader has to notice by counting.

Counterpoised edges are drawn violet, because they are a different experiment rather than a more expensive version of the same one.

The particular violet is chosen, not decorative. It is the one hue region the report’s palette does not already spend on something else – blue is nodes, orange is soft-core and warnings, red is an unconnected ligand – so it cannot be misread as any of those. It is also the darkest of the candidates considered, at roughly half the relative luminance of the #7f8fa6 edge grey, which is what lets colour carry the distinction on its own where the lighter violet this started as could not: that one sat within 10% of the grey’s luminance and needed a dash pattern to be separable at all.

Colour is still never the only signal. Every counterpoised edge says CBFE in its tooltip, and its card in the report carries a badge.

A ligand this package invented is drawn with a dashed outline and its on-canvas label ends in SYN. Two signals rather than one, and neither of them colour: the node palette is already spent on connected-versus-isolated, and a reader who cannot resolve a 2.5px dash pattern – in print, on a small screen, in a screenshot – still reads the three letters. Mistaking an invented vertex for a ligand somebody supplied is the one error in this whole feature that costs a real simulation.

Parameters:
Return type:

str

Self-contained HTML report for a planned network.

Everything is inlined – SVG, CSS, no scripts, no external assets – so the file can be emailed, attached to a ticket, or opened from a scratch directory years later and still render. That constraint is why the depictions are SVG rather than linked images.

The report includes the rejected candidates, and draws them. A reviewer’s first question about a planned network is almost always “why isn’t ligand X connected to Y”, and the answer only exists in the rejections – where a reason string alone rarely settles it. The mapping that provoked the rejection is already on the candidate, so the same two-pane depiction the selected edges get is available at no extra computation, and shows the oversized soft-core or the split ring directly.

rbfenetmap.viz.gallery.render_report(network, *, title='RBFE network', show_indices=False, reject_depictions=True, max_reject_depictions=24, repair_comparison=True, max_repair_comparisons=24)[source]

Return a complete, self-contained HTML document describing network.

Parameters:

  • network (Network)

  • title (str, optional)

  • show_indices (bool, optional) – Label atoms with indices in the depictions.

  • reject_depictions (bool, optional) – Draw each rejected candidate as well as tabulating it. On by default: the picture is the reason the section exists. Turn it off for a small report.

  • max_reject_depictions (int, optional) – Stop after this many rejected depictions. A tightened threshold can reject every pair in the pool – 120 of them on a 16-ligand set – and two SVGs each would take the report from under 2 MB to over 10. The number omitted is always stated; a report that silently drew some of the rejections would be worse than one that drew none. Zero or negative means no limit.

  • repair_comparison (bool, optional) – On a repaired edge, offer a toggle between the repaired soft-core and the one the mapper proposed. On by default. The repaired view is what shows without touching it, so the default output is unchanged from a reader’s point of view.

  • max_repair_comparisons (int, optional) – Stop offering the toggle after this many repaired edges, cheapest first. Each one costs two more inlined depictions, and a dense network repairs 30 of its edges. Zero or negative means no limit.

Return type:

str