Visualization

The ns-viz Rust crate and nextstat.viz Python submodule produce 18 publication-quality plot types — full parity with every TRExFitter output. All plots are generated as serialisable JSON artifacts in Rust; Python convenience wrappers render them via matplotlib.

Installation

Complete Plot Catalogue (18 types)

Highlighted rows are the five newest modules added in v0.9.4.

CLs Brazil Band

import nextstat

scan = np.linspace(0.0, 5.0, 101)
cls_art = nextstat.viz.cls_curve(model, scan, alpha=0.05)
nextstat.viz.plot_cls_curve(cls_art, title="CLs Brazil band")

Significance Scan

Plots p₀ or Z (discovery significance) as a function of mass or signal-strength parameter. Supports single-workspace and multi-mass-point scans. Comparable to TRExFitter step s (GetSignificance).

sig_art = nextstat.viz.significance_scan(model, masses, workspaces)
nextstat.viz.plot_significance_scan(sig_art, title="Discovery significance")

2D Likelihood Contours

Two-POI Δ(2NLL) contours at 68% and 95% CL. Uses marching squares for smooth contour extraction from the profile likelihood grid. Comparable to TRExFitter GetContour.

contour_art = nextstat.viz.contour_2d(
    model, poi_x="mu_sig", poi_y="mu_bkg",
    x_range=(0.0, 3.0), y_range=(0.5, 1.5), grid=50,
)
nextstat.viz.plot_contour(contour_art, title="2D contour")

Unfolding Plots

Two artifact types: ResponseMatrixArtifact (migration matrix with purity/stability metrics, optional column normalisation) and UnfoldedSpectrumArtifact(unfolded differential distribution with stat/syst errors and truth overlay). Comparable to TRExFitter step x.

resp = nextstat.viz.response_matrix(truth_bins, reco_bins, migration)
nextstat.viz.plot_response_matrix(resp, title="Response matrix")

unf = nextstat.viz.unfolded_spectrum(bins, unfolded, stat_err, syst_err, truth)
nextstat.viz.plot_unfolded_spectrum(unf, title="Unfolded pT")

Morphing Validation

Visualises template interpolation between anchor points. Shows discrete anchor templates alongside the interpolated result at an arbitrary parameter value.

morph_art = nextstat.viz.morphing(anchors, interp_value=0.7)
nextstat.viz.plot_morphing(morph_art, title="Template morphing")

Signal Injection / Linearity

μ̂ vs μ_inj linearity test with per-point pull statistics and automatic least-squares slope/intercept fit. Validates that the analysis recovers injected signal strengths.

inj_art = nextstat.viz.signal_injection(
    model, mu_inj=[0.0, 0.5, 1.0, 1.5, 2.0], n_toys=200,
)
nextstat.viz.plot_injection(inj_art, title="Signal injection linearity")

Single-Artifact Renderer (viz render)

Render a single JSON viz artifact directly to an image file without generating a full report. Supports pulls, corr, and ranking artifact types.

# Render pulls plot
nextstat viz render --kind pulls --input pulls.json --output pulls.png

# Render correlation matrix with filters
nextstat viz render --kind corr --input corr.json --output corr.png \
  --corr-top-n 40 --corr-exclude "gamma_*"

# Render ranking with custom title and DPI
nextstat viz render --kind ranking --input ranking.json --output ranking.png \
  --title "NP Impact on mu" --dpi 220

Rust Artifact Architecture

Every plot type is backed by a serialisable Rust struct in the ns-viz crate. Artifacts are JSON-serialisable via serde, so you can consume them from any language or feed them into custom renderers. The Python nextstat.viz wrappers call into these Rust types and render via matplotlib.