Visualization¶
Use this section to see your model's explanations and training progress as figures instead of
numbers: standalone SVG files, interactive HTML pages, Jupyter notebooks and reports, and native
desktop windows. Everything except the desktop windows is part of pulsatrix_core and needs no
GUI, display or extra dependency.
The explainers, LRP rules and interpretability tools elsewhere in pulsatrix return plain data
(Attribution, CircuitGraph, ActivationSnapshot) and never draw anything. This section turns
that data into figures. Only the desktop windows add dependencies (GLFW, Dear ImGui, ImPlot), in
the separate pulsatrix_viz library.
Which output do you want?¶
| You want | Use | Page |
|---|---|---|
| A figure for a paper or a slide | SVG files (RenderBarChartSvg, RenderHeatmapSvg, ...) or the pulsatrix_svg tool |
SVG Figures |
| A page to explore, with hover, zoom and export | Interactive HTML pages (Vega-Lite) | Interactive HTML |
| A notebook or a shareable report with text, code and figures | Report, written as .ipynb or HTML |
Notebooks and Reports |
| Text colored by relevance, from a language model | Token and word relevance documents, pulsatrix_explain_text |
JSON Documents |
| A language model's attribution graph in Neuronpedia or circuit-tracer | ToNeuronpediaJson |
Attribution Graph Viewers |
| Live training curves or an interactive explanation dashboard | Dear ImGui windows (-DPULSATRIX_ENABLE_VIZ=ON) |
Desktop Windows |
| To save an explanation and draw it later, or elsewhere | Versioned JSON documents | JSON Documents |
Every option draws from the same versioned JSON documents, so one explanation can be saved once and shown in any of these forms.
Data transforms¶
The data transforms (viz/plot_data.hpp, viz/colormap.hpp) turn explanations into what a
figure plots. They are plain, unit-tested functions in pulsatrix_core, with no ImGui or ImPlot
code:
ToFeatureImportanceBars/ToWaterfallSteps/ToWaterfallBars: turn anAttributioninto sorted bars, or into a waterfall from the baseline to the prediction.CircuitNodeDisplayLabel: a readable label for aCircuitGraphnode.ToSaliencyHeatmap/ComputeHeatmapColorScale: turn anAttributioninto a 2D grid and choose its color scale. The scale is symmetric around zero when any value is negative, and[0, max]otherwise.ToBeeswarmPoints: spread one feature's values across manyAttributions into non-overlapping points. The jitter is deterministic.ToFieldHistogramBins: bin aDatasetfield's values into an equal-width histogram.ToRgbImageBuffer: convert an imageTensorinto bytes ready for a GPU texture.ViridisColormap/DivergingColormap: colorblind-safe colormaps for unsigned and signed values.
Metrics sink (viz/implot_metrics_sink.hpp). ImPlotMetricsSink is a MetricsSink that
stores every logged scalar and histogram as a per-tag series. Its logging methods
(log_scalar(), log_histogram()) are compiled into pulsatrix_core and need no flag. Only
Draw() needs pulsatrix_viz. To write your own sink, see
Adding a new metrics sink.
The desktop chart widgets are thin ImGui/ImPlot drawing calls over these transforms; see Desktop Windows.
Full API reference: Doxygen: Visualization