chromasurr.error_analysis module

Diagnostic tools for surrogate or calibrated model.

This module collects lightweight helpers that assess how well a surrogate (e.g., a Gaussian-process emulator) reproduces reference data. In addition to the classic RMSE, MAE and coefficient of determination (R²), we provide

  • NRMSE – Normalised root-mean-square error (normalised by either the data range, mean or standard deviation)

  • MAPE – Mean absolute percentage error

A convenience wrapper evaluate() prints a traffic-light style report so users can immediately gauge surrogate quality in notebooks or scripts.

chromasurr.error_analysis.basic_stats(y_true, y_pred)[source]

Return basic point-wise error statistics.

Parameters:

  • y_true (numpy.ndarray) – Arrays of equal length containing reference and predicted values.

  • y_pred (numpy.ndarray) – Arrays of equal length containing reference and predicted values.

Returns:

dict – RMSE, MAE and R² in a dictionary.

chromasurr.error_analysis.evaluate(y_true, y_pred, *, nrmse_threshold=0.1, mape_threshold=0.05, norm='range')[source]

Comprehensive error report with traffic-light flags.

Any metric that meets the respective threshold is marked ✅ (good), others ❌ (poor). The verdict is the conjunction of all individual flags.

Parameters:

  • y_true (numpy.ndarray) – Arrays with reference and predicted values.

  • y_pred (numpy.ndarray) – Arrays with reference and predicted values.

  • nrmse_threshold (float, default=0.10) – Acceptable NRMSE (relative units).

  • mape_threshold (float, default=0.05) – Acceptable MAPE (fractional).

  • norm ({'range', 'mean', 'std'}, default='range') – Scaling used for NRMSE.

Returns:

dict – Mapping from metric name to (value, flag) where flag is True if the surrogate passes the criterion. An additional key "verdict" holds a human-readable string.

chromasurr.error_analysis.mape(y_true, y_pred)[source]

Mean absolute percentage error.

MAPE = mean(|y_true − y_pred| / |y_true|) expressed as a fraction.

Returns nan if any true value is zero, as the percentage error would be undefined.

Return type:

float

chromasurr.error_analysis.nrmse(y_true, y_pred, *, norm='range')[source]

Compute the normalised RMSE.

The RMSE is divided by one of three scale factors:

  • "range" – max(y_true) − min(y_true)

  • "mean" – mean(y_true)

  • "std" – population standard deviation of y_true

Normalising puts error into perspective and enables comparison across metrics with different units.

Parameters:

  • y_true (numpy.ndarray) – Reference and predicted data.

  • y_pred (numpy.ndarray) – Reference and predicted data.

  • norm ({'range', 'mean', 'std'}, default='range') – Scaling to use.

Returns:

float – NRMSE in relative units (0 ⟹ perfect fit, higher is worse).

chromasurr.error_analysis.parity_plot(y_true, y_pred, *, ax=None, label=None)[source]

Scatter plot of predicted vs. observed values.

Parameters:

  • y_true (numpy.ndarray) – Reference and predicted data.

  • y_pred (numpy.ndarray) – Reference and predicted data.

  • ax (matplotlib.axes.Axes, optional) – Existing axes to plot on. If None, a new figure/axes is created.

  • label (str, optional) – Legend label for the scatter points.

Returns:

matplotlib.axes.Axes – The axis the data was plotted on.