Evaluation plots¶

hqnn_forge.evaluation.plots ¶

hqnn_forge.evaluation.plots¶

Figures for benchmarking hybrid models: confusion matrix, reliability diagram, per-fold metric distributions, and the score-versus-parameter-count frontier.

Every function returns the matplotlib.figure.Figure it drew on and never calls plt.show(), so the figures compose with notebooks and with fig.savefig pipelines. Pass ax to draw into an existing axes; the returned figure is then that axes' root figure, the top-level Figure even when the axes sits on a fig.subfigures() sub-figure.

matplotlib is an optional dependency (the examples extra); it is imported when a plotting function is first called, and a missing install raises an ImportError that says how to add it. pareto_frontier needs no matplotlib.

confusion_matrix ¶

confusion_matrix(y_true: ArrayLike, y_pred: ArrayLike) -> npt.NDArray[np.int64]

2×2 count matrix, rows = true class (0, 1), columns = predicted class.

[[tn, fp], [fn, tp]], the scikit-learn layout.

plot_confusion_matrix ¶

plot_confusion_matrix(y_true: ArrayLike, y_pred: ArrayLike, *, labels: tuple[str, str] = ('negative', 'positive'), normalize: bool = False, title: str | None = None, ax: Axes | None = None) -> Figure

Heat-map of the binary confusion matrix with the value in every cell.

Parameters:

Name	Type	Description	Default
`y_true`	`ArrayLike`	Binary labels, e.g. `model.predict(X)`.	required
`y_pred`	`ArrayLike`	Binary labels, e.g. `model.predict(X)`.	required
`labels`	`tuple[str, str]`	Names for class 0 and class 1.	`('negative', 'positive')`
`normalize`	`bool`	Show each row as fractions of its true class (recall per class) instead of counts. Rows with no samples show 0.	`False`
`title`	`str \| None`	Axes title. Default: `"Confusion matrix"`.	`None`
`ax`	`Axes \| None`	Draw into this axes.	`None`

plot_reliability_diagram ¶

plot_reliability_diagram(y_true: ArrayLike, prob: ArrayLike, *, n_bins: int = 10, strategy: BinStrategy = 'uniform', title: str | None = None, ax: Axes | None = None) -> Figure

Reliability diagram: observed positive frequency against mean predicted probability per bin, with the diagonal of perfect calibration and the expected calibration error in the legend.

Parameters:

Name	Type	Description	Default
`y_true`	`ArrayLike`	Binary labels and positive-class probabilities.	required
`prob`	`ArrayLike`	Binary labels and positive-class probabilities.	required
`n_bins`	`int`	As for `hqnn_forge.evaluation.calibration.reliability_curve`; `"quantile"` suits imbalanced data.	`10`
`strategy`	`int`	As for `hqnn_forge.evaluation.calibration.reliability_curve`; `"quantile"` suits imbalanced data.	`10`
`title`	`str \| None`	Axes title. Default: `"Reliability diagram"`.	`None`
`ax`	`Axes \| None`	Draw into this axes.	`None`

plot_fold_metric_boxplot ¶

plot_fold_metric_boxplot(model_scores: Mapping[str, Sequence[float]], *, metric_name: str = 'MCC', show_points: bool = True, ax: Axes | None = None) -> Figure

One box per model over its per-fold scores, in the mapping's order.

With a handful of folds a box hides how few points it summarises, so the individual fold scores are overlaid by default.

Parameters:

Name	Type	Description	Default
`model_scores`	`Mapping[str, Sequence[float]]`	`{model_name: [score_fold_1, ...]}`.	required
`metric_name`	`str`	Y-axis label.	`'MCC'`
`show_points`	`bool`	Overlay each fold's score.	`True`
`ax`	`Axes \| None`	Draw into this axes.	`None`

pareto_frontier ¶

pareto_frontier(models: Mapping[str, tuple[float, int]]) -> list[str]

Names of the models no other model beats on both axes.

A model is dominated if another has at most as many parameters and at least as high a score, and is strictly better on one of the two. The result is ordered by increasing parameter count.

plot_efficiency_frontier ¶

plot_efficiency_frontier(models: Mapping[str, tuple[float, int]], *, metric_name: str = 'MCC', ax: Axes | None = None) -> Figure

Score against trainable-parameter count (log x), with the Pareto frontier.

Parameters:

Name	Type	Description	Default
`models`	`Mapping[str, tuple[float, int]]`	`{model_name: (score, n_parameters)}`, e.g. `{"SHNN": (0.576, 122), "SNN": (0.563, 3201)}`.	required
`metric_name`	`str`	Y-axis label.	`'MCC'`
`ax`	`Axes \| None`	Draw into this axes.	`None`

Notes

Points on the frontier are joined by a step line: moving right along it, each additional parameter buys a higher score. Points below the line are dominated.