Metrics

ffTRF scores predictions column-wise. In other words, each metric function expects observed and predicted arrays with shape (n_samples, n_outputs) and returns one score per output column before any optional averaging.

These metrics are used for:

predict(..., response=...) and score(...)
choosing the best regularization value during cross-validation

They are not alternative fitting objectives. The TRF itself is always fitted with the same ridge-regularized spectral solver.

Built-In Metrics

pearsonr: default correlation-based score
r2_score: fraction of squared error removed relative to predicting the observed mean
explained_variance_score: fraction of target variance not left in the residual
neg_mse: mTRF-compatible negative MSE where larger values are better
available_metrics(): list built-in metric names accepted by TRF(metric=...)

R² and Explained Variance Are Not Interchangeable

The two scores are equal when the residual y_true - y_pred has zero mean. They differ when a model has a constant prediction bias:

import numpy as np

from fftrf import explained_variance_score, r2_score

y_true = np.arange(5.0)
y_pred = y_true + 1.0

print(explained_variance_score(y_true, y_pred))  # [1.]
print(r2_score(y_true, y_pred))                  # [0.5]

Explained variance is perfect here because the residual is constant and therefore has zero variance. R² is lower because the predictions are displaced from the observations. Use R² when absolute calibration matters. Explained variance is useful when the scientific question concerns whether the model captures fluctuations after disregarding a constant offset.

Custom Metrics

You can also pass your own callable to TRF(metric=...). A custom metric must:

accept (y_true, y_pred)
return one score per output column
use "larger is better" semantics if you want cross-validation to pick the best value sensibly

For compatibility with mTRF, ffTRF.neg_mse follows the same "negative MSE" convention: larger values are still better during cross-validation, even though the underlying quantity is the mean squared error.

`fftrf.available_metrics()`

Return the names of built-in scoring metrics.

Returns:

Type	Description
`tuple of str`	Sorted metric names that can be passed to `TRF(metric=...)` or used when reconstructing a saved configuration.

Notes

Some metrics intentionally expose both a short alias and a more explicit function-style name, for example "r2" and "r2_score". They resolve to the same scoring function.

`fftrf.pearsonr(y_true, y_pred)`

Compute column-wise Pearson correlation.

Parameters:

Name	Type	Description	Default
`y_true`	`ndarray`	Observed samples arranged as `(n_samples, n_outputs)`.	required
`y_pred`	`ndarray`	Predicted samples with the same shape as `y_true`.	required

Returns:

Type	Description
`ndarray`	One correlation coefficient per output channel / feature.

Notes

This is the default scoring metric used by :class:TRF. It is intentionally lightweight and does not return p-values.

`fftrf.r2_score(y_true, y_pred)`

Compute column-wise coefficient of determination.

Parameters:

Name	Type	Description	Default
`y_true`	`ndarray`	Observed samples arranged as `(n_samples, n_outputs)`.	required
`y_pred`	`ndarray`	Predicted samples with the same shape as `y_true`.	required

Returns:

Type	Description
`ndarray`	One :math:`R^2` value per output column.

Notes

Scores can become negative when predictions are worse than a constant mean predictor. This makes the metric suitable for model comparison and cross-validation because larger values remain better.

Unlike :func:explained_variance_score, :math:R^2 penalizes a constant offset between prediction and observation. The two scores are equal only when the prediction residual has zero mean.

`fftrf.explained_variance_score(y_true, y_pred)`

Compute column-wise explained variance.

Parameters:

Name	Type	Description	Default
`y_true`	`ndarray`	Observed samples arranged as `(n_samples, n_outputs)`.	required
`y_pred`	`ndarray`	Predicted samples with the same shape as `y_true`.	required

Returns:

Type	Description
`ndarray`	One explained-variance score per output column.

Notes

Explained variance focuses on residual variance rather than absolute error magnitude. Like :func:r2_score, larger values are better. A prediction that has the correct fluctuations but a constant offset can therefore have perfect explained variance while its :math:R^2 is below one.

`fftrf.neg_mse(y_true, y_pred)`

Compute column-wise negative mean squared error.

Parameters:

Name	Type	Description	Default
`y_true`	`ndarray`	Observed samples arranged as `(n_samples, n_outputs)`.	required
`y_pred`	`ndarray`	Predicted samples with the same shape as `y_true`.	required

Returns:

Type	Description
`ndarray`	One negative-MSE score per output column.

Notes

The sign convention matches :func:mtrf.stats.neg_mse: larger values are better because the underlying MSE is multiplied by -1. Despite the name, this function is therefore directly suitable for cross-validation model selection in :class:TRF.