Skip to content

SVG Figures

For papers, reports and CI, viz/svg.hpp draws documents as standalone SVG files. It needs no GPU, display, font library or ImGui, and it is part of pulsatrix_core. Colors come from colormap.hpp, the same as the ImGui widgets: blue-white-red for signed values and Viridis for magnitudes.

Function Draws From
RenderBarChartSvg(doc, top_k) The top features by |attribution|, on an axis through zero AttributionDocument
RenderWaterfallSvg(doc, baseline) Each feature moving the output from the baseline to the prediction AttributionDocument
RenderHeatmapSvg(doc) The grid, with a color bar and any row and column labels HeatmapDocument
RenderTokenStripSvg(doc) The text's tokens, wrapped, each on a background colored by its relevance TokenRelevanceDocument
RenderBeeswarmSvg(docs, features) One row per feature, one point per input several AttributionDocuments
RenderCounterfactualSetSvg(docs) Several counterfactuals of one input side by side: a column each, a row per changed feature, cells colored by the change several CounterfactualDocuments
RenderMorrisSvg(doc) μ* against σ on one scale, a point per feature with μ's interval, and the line σ = μ MorrisDocument
RenderSobolSvg(doc, top_k) First- and total-order indices per feature, largest total first, with confidence whiskers SobolDocument
RenderCounterfactualSvg(doc, max_rows) Whether the target is reached, then each changed feature, costliest first, with its old and new value and its change in units of its scale CounterfactualDocument
RenderTornadoSvg(doc, top_k) One row per feature, largest swing first: bars from the unchanged output to the output at the feature's low and high values SensitivityDocument
RenderPartialDependenceSvg(doc, view) ICE curves under their average, raw, centered or as slopes, with a rug of the inputs' values PartialDependenceDocument
RenderMutationMapSvg(doc) Every substitution's score, a row per amino acid and a column per residue, the wild type dotted; long sequences wrap MutationMapDocument (protein views, viz/protein_views.hpp)
RenderSequenceLogoSvg(doc) A sequence logo: letters stacked to each position's information content SequenceLogoDocument
RenderContactMapSvg(doc) Predicted contacts above the diagonal; the structure's contacts and the top L predictions, right or wrong, below ContactMapDocument
RenderResidueTracksSvg(doc) Per-residue tracks and annotated features under the sequence ResidueTracksDocument
RenderPersistenceDiagramSvg(doc, view) Birth against death per feature, a band of the certified error along the diagonal, essential features on a ∞ line, significant ones filled PersistenceDiagramDocument (topology views, viz/topology_views.hpp)
RenderBarcodeSvg(doc, view) A bar per feature from birth to death, by dimension and longest first, with ±error-bound whiskers PersistenceDiagramDocument
RenderBettiCurveSvg(doc, view) The number of features alive at each scale, per dimension PersistenceDiagramDocument
RenderReliabilityDiagramSvg(series) Each confidence bin's accuracy against its mean confidence, one line per classifier, with the diagonal of perfect calibration, each classifier's ECE, and the share of inputs in each bin below ClassificationReports (performance views, viz/performance_views.hpp)
RenderSliceErrorSvg(report, view) Each slice's error with its interval, worst first, the whole dataset's error as a dashed line, an optional reference such as a target miss rate, and each slice's p-value; slices worse than the rest in red SliceErrorReport
RenderProjectionSvg(doc, x_axis, y_axis) Two axes of a projection, such as PC1 and PC2, on one scale: points colored by group (with a legend) or by value (with a color bar), each with its label on hover. UMAP and t-SNE plots get a note that their distances, cluster sizes and densities aren't meaningful ProjectionDocument
RenderSeriesSvg(doc, view) Lines of measured points, each with an interval whisker, on linear or log axes; panels stacked as small multiples with one legend, a series keeping its color in every panel, and each point's values on hover. view.shared_y gives every panel the same y range SeriesDocument (viz/series.hpp)
#include <fstream>

#include "pulsatrix/viz/svg.hpp"

SvgOptions options;
options.title = "Why the model said yes";
std::ofstream("bars.svg") << RenderBarChartSvg(ToAttributionDocument(attribution), 10, options);

A bar chart of six features' attributions

A waterfall from a baseline of 0.25 to a prediction of 0.188

SvgOptions sets the width (default 640 pixels), a title and the font size. The height follows from the content. Every figure has a title element for screen readers, and every bar, cell and token has a tooltip with its exact value.

From the command line. The pulsatrix_svg tool, built and installed with the library, turns documents into figures:

pulsatrix_svg explanation.json -o bars.svg                 # attribution: bar chart
pulsatrix_svg explanation.json --waterfall 0.12 -o wf.svg  # attribution: waterfall
pulsatrix_svg run*.json --beeswarm 0,3,7 -o swarm.svg      # many attributions: beeswarm
pulsatrix_svg saliency.json -o map.svg                     # heatmap
pulsatrix_svg tokens.json -o text.svg                      # token relevance
pulsatrix_svg pd.json --ice centered -o ice.svg            # partial dependence, centered ICE
pulsatrix_svg sens.json --top-k 8 -o tornado.svg           # sensitivity: tornado chart
pulsatrix_svg cf.json -o cf.svg                            # counterfactual: what changed
pulsatrix_svg cf1.json cf2.json cf3.json -o set.svg        # several counterfactuals side by side
pulsatrix_svg morris.json -o morris.svg                    # Morris screening scatter
pulsatrix_svg sobol.json -o sobol.svg                      # Sobol index bars
pulsatrix_svg pca.json --axes 1,3 -o pca13.svg             # projection: PC1 against PC3
pulsatrix_svg ph.json --view barcode --dims 1 -o h1.svg    # persistence: H1 as a barcode
pulsatrix_svg sweep.json -o sweep.svg                      # series: lines with intervals
pulsatrix_svg one.json five.json -o reliability.svg        # classification reports: one reliability diagram
pulsatrix_svg slices.json -o slices.svg                    # slice error: error by slice

Other options: --top-k N, --axes I,J (a projection's axes, from 1), --view diagram|barcode|betti and --dims D,... (a persistence diagram's view and dimensions), --width W, --font-size N, --title TEXT.

Details:

  • Deterministic. The same input gives the same bytes on every platform. Tests compare each chart with a stored file.
  • Large heatmaps. Grids up to 4,096 cells are one vector rectangle per cell. Larger grids, such as a 224 x 224 saliency map, are embedded as a lossless PNG with sharp pixel edges, which keeps the file small (about 45 KB for 224 x 224).
  • Non-finite values. A heatmap cell or token whose value is NaN or infinite is drawn gray and left out of the color scale. The bar, waterfall and beeswarm charts refuse non-finite values, because there's no honest bar length for them.
  • Text widths are estimated at 0.6 em per character, since there is no font library. Token strips use a monospace font, so their widths are exact. Long labels are shortened with an ellipsis. For exact layout of any script, use the HTML token view.