Track detection of positive examples during training and evaluation.
Binary classification
Keras · Class
metrics.Recall
keras.metrics.Recall measures the fraction of actual positives that are detected. It supports threshold-based classification, top-k ranking, optional class selection, and sample weighting.
How it works
Recall accumulates true-positive and false-negative counts across updates, then returns their ratio: true positives divided by true positives plus false negatives. Predictions are classified using the configured threshold, or ranked when top_k is supplied; sample weights can include zero to mask entries.
Syntax
keras.metrics.Recall(thresholds=None, top_k=None, class_id=None, name=None, dtype=None)Parameters
| Name | Type | Description |
|---|---|---|
thresholds | float or list of floats, default None | Optional decision thresholds for treating predictions as positive. |
top_k | int, default None | Optional number of highest-ranked predictions to consider. |
class_id | int, default None | Optional class index on which to compute binary metrics. |
name | string, default None | Optional metric name. |
dtype | string or dtype, default None | Optional data type for the metric state and result. |
Returns
A scalar recall result computed from the accumulated true-positive and false-negative state.
Key points
- The metric evaluates how many labeled positives are successfully predicted as positive.
- Its accumulated state consists of true-positive and false-negative counts.
- The reported scalar is the true-positive count divided by all actual positives represented by both counts.
- Without explicit weights, every supplied value contributes equally.
- top_k accepts an integer that limits the ranked predictions considered by recall.
- class_id selects one class for a binary-style recall calculation.
Common mistakes
- A zero sample weight excludes selected values from the metric calculation.
- Setting top_k changes recall from threshold-based classification to a top-k ranking measure.
- When class_id is used, it must identify a valid class index.
Example: Compute recall for one batch
import keras
metric = keras.metrics.Recall(thresholds=0.5)
metric.update_state([1, 0, 1], [0.9, 0.6, 0.2])
print(float(metric.result())) # 0.5Creates a recall metric with a 0.5 classification threshold, updates its accumulated counts for one batch, and reads the resulting scalar.
When to use it
Measure whether relevant classes appear among the top-k predictions.
Multiclass ranking
Inspect recall for one class by supplying class_id.
Per-class monitoring
Interview questions
QHow does Keras Recall calculate its value?
Recall measures the fraction of actual positive labels that the metric identifies as positive. Keras maintains true_positives and false_negatives, and computes true_positives divided by their sum.
Follow-up: How does the metric behave across batches? It accumulates state in local variables, so result() reflects all updates until the metric state is reset.
QWhat is the difference between thresholds and top_k?
thresholds controls whether prediction values count as positive. top_k instead evaluates whether relevant classes appear among the highest-k predictions.
Follow-up: When would top_k be useful? It is appropriate when ranking quality matters more than applying one fixed probability cutoff, especially for multiclass outputs.
QWhat does class_id change in Recall?
class_id restricts the calculation to batch entries whose labels contain that class, then measures whether that class passes the threshold or appears in the selected top-k predictions. The class identifier must be valid for the prediction dimension.
Follow-up: How can individual examples be excluded? Pass sample_weight with zero for those examples or values.
Related
keras.metrics.Precisionkeras.metrics.TruePositiveskeras.metrics.FalseNegativeskeras.metrics.PrecisionAtRecallkeras.metrics.RecallAtPrecision