Gradient Histogram Viz

A frequency histogram of a flat gradient array with the running mean drawn as a vertical accent-coloured line and the count / mean / std / min / max summarised above the chart. Use it to diagnose the two failure modes of backprop in one glance: vanishing gradients collapse the distribution onto zero with vanishingly small variance, while exploding gradients smear the tails across many orders of magnitude.

Installation

npx shadcn@latest add https://craftbits.dev/r/gradient-histogram-viz.json

Usage

import { GradientHistogramViz } from "@craft-bits/core";
 
<GradientHistogramViz gradients={layer.grad.flat()} />

Switch to a log frequency axis when a healthy distribution has a fat tail:

<GradientHistogramViz gradients={grads} logScale />

Tune the bucket count for the underlying sample size — more bins for a high-resolution shape, fewer to denoise tiny tensors:

<GradientHistogramViz gradients={grads} bins={64} />

Hide the stat readouts in dense layouts:

<GradientHistogramViz gradients={grads} showStats={false} />

Understanding the component

1. Two passes over the array. The first pass computes count, sum, min, max, and the mean. The second computes the variance against that mean, then buckets every finite value into one of bins equal-width buckets between min and max. Non-finite values (NaN, ±Infinity) are silently dropped — they would otherwise destroy the histogram range.
2. The mean line uses --cb-accent. Drawn over the bars so it stays visible against any bucket height. The line is dashed and labelled mean, springs to its new position when gradients changes, and hides when the input has zero variance (min === max) since the line would be meaningless.
3. logScale is a frequency transform, not a value transform. Bar heights become log10(count + 1) / log10(maxCount + 1). The + 1 keeps the 0/1 transition smooth and avoids -Infinity. The x-axis still spans the raw [min, max] linearly.
4. SPRINGS.smooth on every bar. Each bar's y and height springs independently when gradients changes — the animation feels like a wave settling into the new distribution. prefers-reduced-motion: reduce collapses every spring to an instant snap.
5. Empty-state is graceful. If gradients contains no finite values, the chart renders an empty grid with the text "no finite gradients" centred in the plot area, and the stats grid shows 0 and — instead of NaN.
6. Bin clamping. bins is clamped to [4, 128] — too few and the distribution shape is meaningless; too many and individual buckets become single-sample noise.

Props

Accessibility

• The figure is role="figure" with an aria-labelledby that names the chart "Gradient distribution."
• An aria-live="polite" summary announces the sample count, mean, standard deviation, and value range whenever the input changes.
• The stat readouts use a semantic <dl> / <dt> / <dd> structure so the label / value relationship is preserved for assistive tech.
• The mean line carries aria-hidden because its meaning is already in the summary; redundant narration would clutter the live region.
• Color is never the only signal — the mean line is labelled mean, and every stat appears as text.
• prefers-reduced-motion: reduce snaps every bar transition; no per-bar easing is shown.

Credits

• Extracted from: craftingattention (app/src/lessons/primitives/viz/GradientHistogramViz.tsx). The source paired a fixed pedagogical log-scale gradient distribution with a movable fp16-representable-range overlay and a LabeledSlider-driven loss-scale picker — a single-purpose teaching artefact for the mixed-precision lesson. Reframed as a generic histogram primitive: accepts arbitrary gradients: number[], computes its own bucket counts, draws a mean overlay, and exposes the bins / showStats / logScale axes that any backprop diagnostic needs. Stripped the fp16-window simulation, scale-step slider, safe-zone overlay, "outside %" narration, and bell-curve pre-computation.