F1 Score

f1-score

Metric f1_score from scikit-learn (sklearn.metrics.f1_score)

When to invoke this skill

The user has predictions + ground truth and asks to evaluate with f1_score, or mentions sklearn.metrics.f1_score directly, or wants the standard scikit-learn implementation.

Reference signature

from sklearn.metrics import f1_score

# f1_score(y_true, y_pred, *, labels=None, pos_label=1, average='binary', sample_weight=None, zero_division='warn')

Library docstring

Compute the F1 score, also known as balanced F-score or F-measure.

The F1 score can be interpreted as a harmonic mean of the precision and
recall, where an F1 score reaches its best value at 1 and worst score at 0.
The relative contribution of precision and recall to the F1 score are
equal. The formula for the F1 score is:

.. math::
    \text{F1} = \frac{2 * \text{TP}}{2 * \text{TP} + \text{FP} + \text{FN}}

Where :math:`\text{TP}` is the number of true positives, :math:`\text{FN}` is the
number of false negatives, and :math:`\text{FP}` is the number of false positives.
F1 is by default
calculated as 0.0 when there are no true positives, false negatives, or
false positives.

Support beyond :term:`binary` targets is achieved by treating :term:`multiclass`
and :term:`multilabel` data as a collection of binary problems, one for each
label. For the :term:`binary` case, setting `average='binary'` will return
F1 score for `pos_label`. If `average` is not `'binary'`, `pos_label` is ignored
and F1 score for both classes are computed, then averaged or both returned (when
`average=None`). Similarly, for :term:`multiclass` and :term:`multilabel` targets,
F1 score for all `labels` are either returned or averaged depending on the
`average` parameter. Use `labels` specify the set of labels to calculate F1 score
for.

Read more in the :ref:`User Guide <precision_recall_f_measure_metrics>`.

Parameters
----------
y_true : 1d array-like, or label indicator array / sparse matrix
    Ground truth (correct) target values. Sparse matrix is only supported when
    targets are of :term:`multilabel` type.

y_pred : 1d array-like, or label indicator array / sparse matrix
    Estimated targets as returned by a classifier. Sparse matrix is only
    supported when targets are of :term:`multilabel` type.

labels : array-like, default=None
    The set of labels to include when `average != 'binary'`, and their
    order if `average is None`. Labels present in the data can be
    excluded, for example in multiclass classification to exclude a "negative
    class". Labels not present in the data can be included and will be
    "assigned" 0 samples. For multilabel targets, labels are column in

Quick recipe

import sklearn.metrics as _m
score = _m.f1_score(y_true, y_pred)

Don'ts

• Don't reimplement when the library version handles edge cases (NaN, ties, empty inputs) better than a hand-rolled formula.
• Always check the library version's argument order — sklearn is (y_true, y_pred) while torchmetrics is (preds, target).