Reference / API reference / dorothy / dorothy.visualization / dorothy.visualization.evaluation_plots

dorothy.visualization.evaluation_plots¶

Test-set evaluation plots.

All functions take arrays in physical units, shaped (n_samples, n_params): predictions, true labels, predicted model scatter, label errors and a validity mask (label valid where > 0). Grids are sized to the number of parameters, and axis ranges default to percentiles of the data. A plot function writes a PNG into a directory and returns its path, or None when matplotlib is not installed.

Adapted from evaluation plots by Diego (d5martin).

Functions

`generate_evaluation_plots`(output_dir, preds, ...)	Write the four evaluation plots for one label source.
`plot_histograms`(output_path, preds, true, ...)	Overlaid histograms of true and predicted values per parameter.
`plot_pred_vs_truth`(output_path, preds, true, ...)	Predicted vs. true value per parameter, coloured by predicted uncertainty.
`plot_residuals`(output_path, preds, true, ...)	Residual (true - predicted) density vs. true value with running quartiles.
`plot_zscore_histograms`(output_path, preds, ...)	Per-parameter z-score histograms against a unit Gaussian.

dorothy.visualization.evaluation_plots.plot_pred_vs_truth(output_path, preds, true, pred_unc, mask, parameter_names, label_source=None, ranges=None, filename='pred_vs_truth.png')[source]¶

Predicted vs. true value per parameter, coloured by predicted uncertainty.

Parameters:

output_path (str | Path) – Directory to save the plot.
preds (NDArray) – Predicted values, shape (n_samples, n_params).
true (NDArray) – True label values, same shape.
pred_unc (NDArray) – Predicted uncertainties, same shape.
mask (NDArray) – Label validity mask (valid where > 0), same shape.
parameter_names (list[str]) – Parameter names (length n_params).
label_source (str | None) – Label source name, used in axis labels and titles.
ranges (dict[str, tuple[float, float]] | None) – Optional per-parameter (min, max) axis ranges, keyed by name.
filename (str) – Output file name.

Returns:

Path of the plot, or None if matplotlib is missing.

Raises:

ValueError – If the arrays differ in shape.

Return type:

Path | None

dorothy.visualization.evaluation_plots.plot_residuals(output_path, preds, true, mask, parameter_names, label_source=None, ranges=None, n_bins=50, filename='residuals.png')[source]¶

Residual (true - predicted) density vs. true value with running quartiles.

Parameters:

output_path (str | Path) – Directory to save the plot.
preds (NDArray) – Predicted values, shape (n_samples, n_params).
true (NDArray) – True label values, same shape.
mask (NDArray) – Label validity mask (valid where > 0), same shape.
parameter_names (list[str]) – Parameter names (length n_params).
label_source (str | None) – Label source name, used in axis labels and titles.
ranges (dict[str, tuple[float, float]] | None) – Optional per-parameter (min, max) ranges for the true value.
n_bins (int) – Number of bins along each axis.
filename (str) – Output file name.

Returns:

Path of the plot, or None if matplotlib is missing.

Raises:

ValueError – If the arrays differ in shape.

Return type:

Path | None

dorothy.visualization.evaluation_plots.plot_histograms(output_path, preds, true, mask, parameter_names, label_source=None, ranges=None, n_bins=60, filename='histograms.png')[source]¶

Overlaid histograms of true and predicted values per parameter.

Parameters:

output_path (str | Path) – Directory to save the plot.
preds (NDArray) – Predicted values, shape (n_samples, n_params).
true (NDArray) – True label values, same shape.
mask (NDArray) – Label validity mask (valid where > 0), same shape.
parameter_names (list[str]) – Parameter names (length n_params).
label_source (str | None) – Label source name, used in the legend.
ranges (dict[str, tuple[float, float]] | None) – Optional per-parameter (min, max) histogram ranges.
n_bins (int) – Number of histogram bins.
filename (str) – Output file name.

Returns:

Path of the plot, or None if matplotlib is missing.

Raises:

ValueError – If the arrays differ in shape.

Return type:

Path | None

dorothy.visualization.evaluation_plots.plot_zscore_histograms(output_path, preds, true, pred_unc, label_err, mask, parameter_names, label_source=None, z_max=5.0, filename='zscore_histograms.png')[source]¶

Per-parameter z-score histograms against a unit Gaussian.

z = (predicted - true) / sqrt(pred_unc^2 + label_err^2), as in Evaluator. Each panel reports the median and the robust scatter (P84 - P16) / 2. A calibrated parameter has median 0 and scatter 1. Scatter above 1 means overconfident, below 1 underconfident. Values outside [-z_max, z_max] fall in the end bins.

Parameters:

output_path (str | Path) – Directory to save the plot.
preds (NDArray) – Predicted values, shape (n_samples, n_params).
true (NDArray) – True label values, same shape.
pred_unc (NDArray) – Predicted model scatter, same shape.
label_err (NDArray | None) – Label errors, same shape, or None to use pred_unc only.
mask (NDArray) – Label validity mask (valid where > 0), same shape.
parameter_names (list[str]) – Parameter names (length n_params).
label_source (str | None) – Label source name, used in the title.
z_max (float) – Histogram range is [-z_max, z_max].
filename (str) – Output file name.

Returns:

Path of the plot, or None if matplotlib is missing.

Raises:

ValueError – If the arrays differ in shape.

Return type:

Path | None

dorothy.visualization.evaluation_plots.generate_evaluation_plots(output_dir, preds, true, pred_unc, label_err, mask, parameter_names, label_source=None, ranges=None)[source]¶

Write the four evaluation plots for one label source.

The files are pred_vs_truth.png, residuals.png, histograms.png and zscore_histograms.png, each prefixed with <label_source>_ when a label source is given.

Parameters:

output_dir (str | Path) – Directory of the plots, created if missing.
preds (NDArray) – Predicted values, shape (n_samples, n_params).
true (NDArray) – True label values, same shape.
pred_unc (NDArray) – Predicted model scatter, same shape.
label_err (NDArray | None) – Label errors, same shape, or None to use pred_unc only.
mask (NDArray) – Label validity mask (valid where > 0), same shape.
parameter_names (list[str]) – Parameter names (length n_params).
label_source (str | None) – Label source name, used in titles and file names.
ranges (dict[str, tuple[float, float]] | None) – Optional per-parameter (min, max) ranges for the first three plots, keyed by name.

Returns:

Paths of the plots written; empty if matplotlib is missing.

Raises:

ValueError – If the arrays differ in shape.

Return type:

list[Path]