Reference for ultralytics/utils/metrics.py

def matrix(self):
    """Return the confusion matrix."""
    return self.matrix

@TryExcept(msg="ConfusionMatrix plot failure")
@plt_settings()
def plot(self, normalize=True, save_dir="", names=(), on_plot=None):
    """
    Plot the confusion matrix using seaborn and save it to a file.

    Args:
        normalize (bool): Whether to normalize the confusion matrix.
        save_dir (str): Directory where the plot will be saved.
        names (tuple): Names of classes, used as labels on the plot.
        on_plot (func): An optional callback to pass plots path and data when they are rendered.
    """
    import seaborn  # scope for faster 'import ultralytics'

    array = self.matrix / ((self.matrix.sum(0).reshape(1, -1) + 1e-9) if normalize else 1)  # normalize columns
    array[array < 0.005] = np.nan  # don't annotate (would appear as 0.00)

    fig, ax = plt.subplots(1, 1, figsize=(12, 9), tight_layout=True)
    nc, nn = self.nc, len(names)  # number of classes, names
    seaborn.set_theme(font_scale=1.0 if nc < 50 else 0.8)  # for label size
    labels = (0 < nn < 99) and (nn == nc)  # apply names to ticklabels
    ticklabels = (list(names) + ["background"]) if labels else "auto"
    with warnings.catch_warnings():
        warnings.simplefilter("ignore")  # suppress empty matrix RuntimeWarning: All-NaN slice encountered
        seaborn.heatmap(
            array,
            ax=ax,
            annot=nc < 30,
            annot_kws={"size": 8},
            cmap="Blues",
            fmt=".2f" if normalize else ".0f",
            square=True,
            vmin=0.0,
            xticklabels=ticklabels,
            yticklabels=ticklabels,
        ).set_facecolor((1, 1, 1))
    title = "Confusion Matrix" + " Normalized" * normalize
    ax.set_xlabel("True")
    ax.set_ylabel("Predicted")
    ax.set_title(title)
    plot_fname = Path(save_dir) / f"{title.lower().replace(' ', '_')}.png"
    fig.savefig(plot_fname, dpi=250)
    plt.close(fig)
    if on_plot:
        on_plot(plot_fname)

def print(self):
    """Print the confusion matrix to the console."""
    for i in range(self.matrix.shape[0]):
        LOGGER.info(" ".join(map(str, self.matrix[i])))

def process_batch(self, detections, gt_bboxes, gt_cls):
    """
    Update confusion matrix for object detection task.

    Args:
        detections (Array[N, 6] | Array[N, 7]): Detected bounding boxes and their associated information.
                                  Each row should contain (x1, y1, x2, y2, conf, class)
                                  or with an additional element `angle` when it's obb.
        gt_bboxes (Array[M, 4]| Array[N, 5]): Ground truth bounding boxes with xyxy/xyxyr format.
        gt_cls (Array[M]): The class labels.
    """
    if gt_cls.shape[0] == 0:  # Check if labels is empty
        if detections is not None:
            detections = detections[detections[:, 4] > self.conf]
            detection_classes = detections[:, 5].int()
            for dc in detection_classes:
                self.matrix[dc, self.nc] += 1  # false positives
        return
    if detections is None:
        gt_classes = gt_cls.int()
        for gc in gt_classes:
            self.matrix[self.nc, gc] += 1  # background FN
        return

    detections = detections[detections[:, 4] > self.conf]
    gt_classes = gt_cls.int()
    detection_classes = detections[:, 5].int()
    is_obb = detections.shape[1] == 7 and gt_bboxes.shape[1] == 5  # with additional `angle` dimension
    iou = (
        batch_probiou(gt_bboxes, torch.cat([detections[:, :4], detections[:, -1:]], dim=-1))
        if is_obb
        else box_iou(gt_bboxes, detections[:, :4])
    )

    x = torch.where(iou > self.iou_thres)
    if x[0].shape[0]:
        matches = torch.cat((torch.stack(x, 1), iou[x[0], x[1]][:, None]), 1).cpu().numpy()
        if x[0].shape[0] > 1:
            matches = matches[matches[:, 2].argsort()[::-1]]
            matches = matches[np.unique(matches[:, 1], return_index=True)[1]]
            matches = matches[matches[:, 2].argsort()[::-1]]
            matches = matches[np.unique(matches[:, 0], return_index=True)[1]]
    else:
        matches = np.zeros((0, 3))

    n = matches.shape[0] > 0
    m0, m1, _ = matches.transpose().astype(int)
    for i, gc in enumerate(gt_classes):
        j = m0 == i
        if n and sum(j) == 1:
            self.matrix[detection_classes[m1[j]], gc] += 1  # correct
        else:
            self.matrix[self.nc, gc] += 1  # true background

    for i, dc in enumerate(detection_classes):
        if not any(m1 == i):
            self.matrix[dc, self.nc] += 1  # predicted background

def process_cls_preds(self, preds, targets):
    """
    Update confusion matrix for classification task.

    Args:
        preds (Array[N, min(nc,5)]): Predicted class labels.
        targets (Array[N, 1]): Ground truth class labels.
    """
    preds, targets = torch.cat(preds)[:, 0], torch.cat(targets)
    for p, t in zip(preds.cpu().numpy(), targets.cpu().numpy()):
        self.matrix[p][t] += 1

def tp_fp(self):
    """
    Return true positives and false positives.

    Returns:
        (tuple): True positives and false positives.
    """
    tp = self.matrix.diagonal()  # true positives
    fp = self.matrix.sum(1) - tp  # false positives
    # fn = self.matrix.sum(0) - tp  # false negatives (missed detections)
    return (tp[:-1], fp[:-1]) if self.task == "detect" else (tp, fp)  # remove background class if task=detect

def class_result(self, i):
    """Return class-aware result, p[i], r[i], ap50[i], ap[i]."""
    return self.p[i], self.r[i], self.ap50[i], self.ap[i]

def fitness(self):
    """Return model fitness as a weighted combination of metrics."""
    w = [0.0, 0.0, 0.1, 0.9]  # weights for [P, R, mAP@0.5, mAP@0.5:0.95]
    return (np.array(self.mean_results()) * w).sum()

def mean_results(self):
    """Return mean of results, mp, mr, map50, map."""
    return [self.mp, self.mr, self.map50, self.map]

def update(self, results):
    """
    Update the evaluation metrics with a new set of results.

    Args:
        results (tuple): A tuple containing evaluation metrics:
            - p (list): Precision for each class.
            - r (list): Recall for each class.
            - f1 (list): F1 score for each class.
            - all_ap (list): AP scores for all classes and all IoU thresholds.
            - ap_class_index (list): Index of class for each AP score.
            - p_curve (list): Precision curve for each class.
            - r_curve (list): Recall curve for each class.
            - f1_curve (list): F1 curve for each class.
            - px (list): X values for the curves.
            - prec_values (list): Precision values for each class.
    """
    (
        self.p,
        self.r,
        self.f1,
        self.all_ap,
        self.ap_class_index,
        self.p_curve,
        self.r_curve,
        self.f1_curve,
        self.px,
        self.prec_values,
    ) = results

def class_result(self, i):
    """Return the result of evaluating the performance of an object detection model on a specific class."""
    return self.box.class_result(i)

def mean_results(self):
    """Calculate mean of detected objects & return precision, recall, mAP50, and mAP50-95."""
    return self.box.mean_results()

def process(self, tp, conf, pred_cls, target_cls, on_plot=None):
    """
    Process predicted results for object detection and update metrics.

    Args:
        tp (np.ndarray): True positive array.
        conf (np.ndarray): Confidence array.
        pred_cls (np.ndarray): Predicted class indices array.
        target_cls (np.ndarray): Target class indices array.
        on_plot (callable, optional): Function to call after plots are generated.
    """
    results = ap_per_class(
        tp,
        conf,
        pred_cls,
        target_cls,
        plot=self.plot,
        save_dir=self.save_dir,
        names=self.names,
        on_plot=on_plot,
    )[2:]
    self.box.nc = len(self.names)
    self.box.update(results)

def class_result(self, i):
    """Return classification results for a specified class index."""
    return self.box.class_result(i) + self.seg.class_result(i)

def mean_results(self):
    """Return the mean metrics for bounding box and segmentation results."""
    return self.box.mean_results() + self.seg.mean_results()

def process(self, tp, tp_m, conf, pred_cls, target_cls, on_plot=None):
    """
    Process the detection and segmentation metrics over the given set of predictions.

    Args:
        tp (np.ndarray): True positive array for boxes.
        tp_m (np.ndarray): True positive array for masks.
        conf (np.ndarray): Confidence array.
        pred_cls (np.ndarray): Predicted class indices array.
        target_cls (np.ndarray): Target class indices array.
        on_plot (callable, optional): Function to call after plots are generated.
    """
    results_mask = ap_per_class(
        tp_m,
        conf,
        pred_cls,
        target_cls,
        plot=self.plot,
        on_plot=on_plot,
        save_dir=self.save_dir,
        names=self.names,
        prefix="Mask",
    )[2:]
    self.seg.nc = len(self.names)
    self.seg.update(results_mask)
    results_box = ap_per_class(
        tp,
        conf,
        pred_cls,
        target_cls,
        plot=self.plot,
        on_plot=on_plot,
        save_dir=self.save_dir,
        names=self.names,
        prefix="Box",
    )[2:]
    self.box.nc = len(self.names)
    self.box.update(results_box)

def class_result(self, i):
    """Return the class-wise detection results for a specific class i."""
    return self.box.class_result(i) + self.pose.class_result(i)

def mean_results(self):
    """Return the mean results of box and pose."""
    return self.box.mean_results() + self.pose.mean_results()

def process(self, tp, tp_p, conf, pred_cls, target_cls, on_plot=None):
    """
    Process the detection and pose metrics over the given set of predictions.

    Args:
        tp (np.ndarray): True positive array for boxes.
        tp_p (np.ndarray): True positive array for keypoints.
        conf (np.ndarray): Confidence array.
        pred_cls (np.ndarray): Predicted class indices array.
        target_cls (np.ndarray): Target class indices array.
        on_plot (callable, optional): Function to call after plots are generated.
    """
    results_pose = ap_per_class(
        tp_p,
        conf,
        pred_cls,
        target_cls,
        plot=self.plot,
        on_plot=on_plot,
        save_dir=self.save_dir,
        names=self.names,
        prefix="Pose",
    )[2:]
    self.pose.nc = len(self.names)
    self.pose.update(results_pose)
    results_box = ap_per_class(
        tp,
        conf,
        pred_cls,
        target_cls,
        plot=self.plot,
        on_plot=on_plot,
        save_dir=self.save_dir,
        names=self.names,
        prefix="Box",
    )[2:]
    self.box.nc = len(self.names)
    self.box.update(results_box)

def process(self, targets, pred):
    """
    Process target classes and predicted classes to compute metrics.

    Args:
        targets (torch.Tensor): Target classes.
        pred (torch.Tensor): Predicted classes.
    """
    pred, targets = torch.cat(pred), torch.cat(targets)
    correct = (targets[:, None] == pred).float()
    acc = torch.stack((correct[:, 0], correct.max(1).values), dim=1)  # (top1, top5) accuracy
    self.top1, self.top5 = acc.mean(0).tolist()

def class_result(self, i):
    """Return the result of evaluating the performance of an object detection model on a specific class."""
    return self.box.class_result(i)

def mean_results(self):
    """Calculate mean of detected objects & return precision, recall, mAP50, and mAP50-95."""
    return self.box.mean_results()

def process(self, tp, conf, pred_cls, target_cls, on_plot=None):
    """
    Process predicted results for object detection and update metrics.

    Args:
        tp (np.ndarray): True positive array.
        conf (np.ndarray): Confidence array.
        pred_cls (np.ndarray): Predicted class indices array.
        target_cls (np.ndarray): Target class indices array.
        on_plot (callable, optional): Function to call after plots are generated.
    """
    results = ap_per_class(
        tp,
        conf,
        pred_cls,
        target_cls,
        plot=self.plot,
        save_dir=self.save_dir,
        names=self.names,
        on_plot=on_plot,
    )[2:]
    self.box.nc = len(self.names)
    self.box.update(results)