---

name: metrics description: "Use supervision metrics for detection evaluation, benchmarking, and result interpretation." disable-model-invocation: true metadata: disco-role: operating license: MIT

Metrics

Use this sub-skill when a task asks to evaluate object detection, instance segmentation, or oriented-box predictions with supervision metrics in version 0.31.0.dev0 on Python >=3.10.

Route here for

• MeanAveragePrecision, MeanAverageRecall, Precision, Recall, F1Score, result objects, .update(...), .compute(), .reset(), .to_pandas(), or .plot().
• MetricTarget.BOXES, MetricTarget.MASKS, MetricTarget.ORIENTED_BOUNDING_BOXES, and AveragingMethod choices.
• sv.ConfusionMatrix, confusion-matrix plots, confidence/IoU thresholds, and per-image validation grids from ConfusionMatrix.benchmark(...).
• Dataset-backed benchmark loops that already have or can obtain pairs of prediction and target Detections.
• Diagnosing mAP, mAR, precision, recall, F1, per-class rows, weighted versus macro/micro averaging, empty inputs, class-id mapping, masks, OBB metrics, COCO-style area, iscrowd, and ignore behavior.

Route away

• Dataset loading, splitting, merging, or format conversion: use datasets, then return here with DetectionDataset samples or Detections target lists.
• Model inference, framework adapters, VLM parsing, detection filtering, NMS, masks/OBB container construction, zones, slicers, or sinks: use detection-and-zones, then return here with prediction Detections.
• High-level false-positive/false-negative drawing or side-by-side visual style: use annotators after metrics identify the detections to display.
• Low-level image/video I/O, plotting grids, or OpenCV backend diagnosis: use media-utils when the task is not metric-specific.

Start with these references

• Metrics reference for metric classes, required Detections fields, result attributes, targets, averaging, and COCO-style metadata.
• Workflows for update/compute patterns, dataset-backed benchmark loops, class remapping, mask/OBB evaluation, confusion matrices, pandas export, and plotting.
• Troubleshooting for metrics extra/pandas, missing confidence or class_id, wrong MetricTarget, mask/OBB metadata, class mappings, empty inputs, and visualization issues.

Operating defaults

1. Install the metrics extra before metric work: pip install "supervision[metrics]". The base install is pip install supervision, but .to_pandas() needs pandas from the metrics extra.
2. Prefer the newer metrics package imports: from supervision.metrics import MeanAveragePrecision, MeanAverageRecall, Precision, Recall, F1Score, MetricTarget, AveragingMethod. Do not use the legacy top-level sv.MeanAveragePrecision for new mAP code.
3. Predictions must normally include xyxy, class_id, and confidence. Targets must include xyxy and class_id; target confidence is not required.
4. Choose the metric target deliberately. BOXES uses detections.xyxy, MASKS uses detections.mask, and ORIENTED_BOUNDING_BOXES uses detections.data[ORIENTED_BOX_COORDINATES].
5. Keep class ids aligned with the dataset class list before computing metrics. ConfusionMatrix requires ids in [0, len(classes) - 1]; new metric result rows are keyed by matched_classes rather than by row position alone.
6. Do not promise network/model benchmark execution unless the user already provides a runnable model and local dataset. This skill owns evaluation logic, not model acquisition or data download.