API Reference / evaluation / metrics /

regression.py

Regression evaluation metrics.

Scoring functions for models that predict a continuous target. The module covers two families:

Absolute-scale errors — mean_absolute_error, mean_squared_error and root_mean_squared_error report error in the units of the target, so they are directly interpretable but not comparable across datasets. Relative / normalized scores — relative_absolute_error, root_relative_squared_error, r2_score and correlation_coefficient divide the model error by the error of a trivial baseline (predicting the mean), which makes them comparable across datasets with different target scales.

The relative errors are reported as percentages, which makes them comparable across targets measured on different scales. Every function takes (y_true, y_pred) as 1-D arrays of equal length and returns a plain Python float.

python 
>>> import numpy as np
>>> from tuiml.evaluation.metrics import mean_absolute_error, r2_score
>>> y_true = np.array([3.0, -0.5, 2.0, 7.0])
>>> y_pred = np.array([2.5, 0.0, 2.0, 8.0])
>>> mean_absolute_error(y_true, y_pred)
0.5
>>> round(r2_score(y_true, y_pred), 4)
0.9486

Functions

Func

mean_absolute_error

Line 38
mean_absolute_error(y_true: np.ndarray, y_pred: np.ndarray) -> float

Compute the Mean Absolute Error (MAE).

MAE is the average magnitude of the residuals. Because the errors are not squared, it weights every mistake linearly and is therefore far less sensitive to outliers than mean_squared_error.

\text{MAE} = \frac{1}{n} \sum_{i=1}^{n} |y_i - \hat{y}_i|

Parameters

y_true
np.ndarray of shape (n_samples,)
Ground-truth target values.
y_pred
np.ndarray of shape (n_samples,)
Predicted target values.

Returns

error
float
Mean absolute error, in the units of the target. Non-negative; 0.0 means a perfect fit.

Notes

Complexity: O(n) time, O(n) memory.

When to use: report MAE when the cost of an error grows linearly with its size, or when the target contains outliers you do not want to dominate the score.

See Also

mean_squared_error

Squared-error analogue.
relative_absolute_error

MAE relative to a mean predictor.
python 
>>> import numpy as np
>>> from tuiml.evaluation.metrics import mean_absolute_error
>>> y_true = np.array([3.0, -0.5, 2.0, 7.0])
>>> y_pred = np.array([2.5, 0.0, 2.0, 8.0])
>>> mean_absolute_error(y_true, y_pred)
0.5
Func

mean_squared_error

Line 87
mean_squared_error(y_true: np.ndarray, y_pred: np.ndarray, squared: bool=True) -> float

Compute the Mean Squared Error (MSE), or its square root (RMSE).

Squaring the residuals penalises large mistakes quadratically, which makes MSE the natural loss for least-squares models but also makes it sensitive to outliers.

\text{MSE} = \frac{1}{n} \sum_{i=1}^{n} (y_i - \hat{y}_i)^2

Parameters

y_true
np.ndarray of shape (n_samples,)
Ground-truth target values.
y_pred
np.ndarray of shape (n_samples,)
Predicted target values.
squared
bool = True
If True return MSE. If False return the root mean squared error :math:`\sqrt{\text{MSE}}`, which is back on the scale of the target.

Returns

error
float
Mean squared error (or RMSE when squared=False). Non-negative; 0.0 means a perfect fit.

Notes

Complexity: O(n) time, O(n) memory.

When to use: MSE is the right choice when large errors are disproportionately costly, and it is the quantity linear regression actually minimises. Use squared=False (or root_mean_squared_error) when you want a number readers can compare against the target's own units.

See Also

root_mean_squared_error

Thin wrapper for squared=False.
mean_absolute_error

Outlier-robust alternative.
python 
>>> import numpy as np
>>> from tuiml.evaluation.metrics import mean_squared_error
>>> y_true = np.array([3.0, -0.5, 2.0, 7.0])
>>> y_pred = np.array([2.5, 0.0, 2.0, 8.0])
>>> mean_squared_error(y_true, y_pred)
0.375
>>> round(mean_squared_error(y_true, y_pred, squared=False), 4)
0.6124
Func

root_mean_squared_error

Line 144
root_mean_squared_error(y_true: np.ndarray, y_pred: np.ndarray) -> float

Compute the Root Mean Squared Error (RMSE).

RMSE is the square root of mean_squared_error, which puts the score back into the units of the target while keeping MSE's quadratic penalty on large residuals.

\text{RMSE} = \sqrt{\frac{1}{n} \sum_{i=1}^{n} (y_i - \hat{y}_i)^2}

Parameters

y_true
np.ndarray of shape (n_samples,)
Ground-truth target values.
y_pred
np.ndarray of shape (n_samples,)
Predicted target values.

Returns

error
float
Root mean squared error, in the units of the target. Non-negative; 0.0 means a perfect fit.

Notes

Complexity: O(n) time, O(n) memory.

When to use: the default headline number for a regression report — same ranking as MSE, but readable on the target's scale.

See Also

mean_squared_error

The underlying squared error.
root_relative_squared_error

RMSE expressed relative to a mean predictor.
python 
>>> import numpy as np
>>> from tuiml.evaluation.metrics import root_mean_squared_error
>>> y_true = np.array([3.0, -0.5, 2.0, 7.0])
>>> y_pred = np.array([2.5, 0.0, 2.0, 8.0])
>>> round(root_mean_squared_error(y_true, y_pred), 4)
0.6124
Func

r2_score

Line 190
r2_score(y_true: np.ndarray, y_pred: np.ndarray) -> float

Compute :math:`R^2`, the coefficient of determination.

R^2 is the fraction of the target's variance that the model explains, measured against the trivial baseline that always predicts \bar{y}.

R^2 = 1 - \frac{\sum_i (y_i - \hat{y}_i)^2}{\sum_i (y_i - \bar{y})^2}

Parameters

y_true
np.ndarray of shape (n_samples,)
Ground-truth target values.
y_pred
np.ndarray of shape (n_samples,)
Predicted target values.

Returns

score
float
Coefficient of determination. 1.0 is a perfect fit, 0.0 matches a constant mean predictor, and negative values mean the model is worse than predicting the mean. Unlike a correlation this is not bounded below by -1.

Notes

Complexity: O(n) time, O(n) memory.

When to use: the standard scale-free summary of regression quality. Note that R^2 equals the squared Pearson correlation only for an unbiased linear fit; for a general model the two can differ, because correlation_coefficient ignores systematic bias while R^2 does not.

See Also

correlation_coefficient

Pearson correlation between truth and prediction.
root_relative_squared_error

Related normalized error, reported as a percentage.
python 
>>> import numpy as np
>>> from tuiml.evaluation.metrics import r2_score
>>> y_true = np.array([3.0, -0.5, 2.0, 7.0])
>>> y_pred = np.array([2.5, 0.0, 2.0, 8.0])
>>> round(r2_score(y_true, y_pred), 4)
0.9486
Func

relative_absolute_error

Line 245
relative_absolute_error(y_true: np.ndarray, y_pred: np.ndarray) -> float

Compute the Relative Absolute Error (RAE), as a percentage.

RAE divides the model's total absolute error by the total absolute error of the trivial predictor that always outputs \bar{y}. Dividing out the target's scale makes the score comparable across datasets.

\text{RAE} = 100 \cdot \frac{\sum_i |y_i - \hat{y}_i|}{\sum_i |y_i - \bar{y}|}

Parameters

y_true
np.ndarray of shape (n_samples,)
Ground-truth target values.
y_pred
np.ndarray of shape (n_samples,)
Predicted target values.

Returns

error
float
Relative absolute error as a percentage. Below 100.0 means the model beats the mean predictor; 0.0 is a perfect fit.

Notes

Complexity: O(n) time, O(n) memory.

When to use: comparing a model across datasets whose targets have different units or magnitudes, where a raw MAE would be meaningless.

See Also

mean_absolute_error

The un-normalized absolute error.
root_relative_squared_error

Squared-error counterpart.
python 
>>> import numpy as np
>>> from tuiml.evaluation.metrics import relative_absolute_error
>>> y_true = np.array([3.0, -0.5, 2.0, 7.0])
>>> y_pred = np.array([2.5, 0.0, 2.0, 8.0])
>>> round(relative_absolute_error(y_true, y_pred), 4)
23.5294
Func

root_relative_squared_error

Line 295
root_relative_squared_error(y_true: np.ndarray, y_pred: np.ndarray) -> float

Compute the Root Relative Squared Error (RRSE), as a percentage.

RRSE is the model's squared error divided by the squared error of the mean predictor, square-rooted and expressed as a percentage. It is the squared-error counterpart of relative_absolute_error and is tied directly to R^2 by \text{RRSE} = 100\sqrt{1 - R^2}.

\text{RRSE} = 100 \cdot \sqrt{ \frac{\sum_i (y_i - \hat{y}_i)^2}{\sum_i (y_i - \bar{y})^2}}

Parameters

y_true
np.ndarray of shape (n_samples,)
Ground-truth target values.
y_pred
np.ndarray of shape (n_samples,)
Predicted target values.

Returns

error
float
Root relative squared error as a percentage. Below 100.0 means the model beats the mean predictor; 0.0 is a perfect fit.

Notes

Complexity: O(n) time, O(n) memory.

When to use: the scale-free companion to RMSE, for comparing error across targets whose units or magnitudes differ.

See Also

root_mean_squared_error

The un-normalized squared error.
r2_score

Equivalent information on a 1.0-is-best scale.
python 
>>> import numpy as np
>>> from tuiml.evaluation.metrics import root_relative_squared_error
>>> y_true = np.array([3.0, -0.5, 2.0, 7.0])
>>> y_pred = np.array([2.5, 0.0, 2.0, 8.0])
>>> round(root_relative_squared_error(y_true, y_pred), 4)
22.6698
Func

correlation_coefficient

Line 347
correlation_coefficient(y_true: np.ndarray, y_pred: np.ndarray) -> float

Compute the Pearson correlation coefficient between truth and prediction.

Measures how well the predictions track the targets up to an arbitrary linear rescaling: a model that predicts 2y + 5 still scores 1.0. That makes it a measure of ranking/shape agreement rather than of calibrated accuracy.

r = \frac{\sum_i (y_i - \bar{y})(\hat{y}_i - \bar{\hat{y}})} {\sqrt{\sum_i (y_i - \bar{y})^2}\; \sqrt{\sum_i (\hat{y}_i - \bar{\hat{y}})^2}}

Parameters

y_true
np.ndarray of shape (n_samples,)
Ground-truth target values.
y_pred
np.ndarray of shape (n_samples,)
Predicted target values.

Returns

score
float
Correlation in :math:`[-1, 1]`. 1.0 is perfect positive linear agreement, 0.0 no linear relationship, -1.0 perfect inversion. Returns 0.0 when the correlation is undefined, which happens when either input is constant.

Notes

Complexity: O(n) time, O(n) memory.

When to use: when only the ordering or shape of the predictions matters and a constant offset or scale factor is acceptable. Pair it with r2_score if calibration matters — a high correlation with a low R^2 is the signature of a systematically biased model.

See Also

r2_score

Penalizes bias and scale errors that this metric ignores.
python 
>>> import numpy as np
>>> from tuiml.evaluation.metrics import correlation_coefficient
>>> y_true = np.array([3.0, -0.5, 2.0, 7.0])
>>> y_pred = np.array([2.5, 0.0, 2.0, 8.0])
>>> round(correlation_coefficient(y_true, y_pred), 4)
0.9849