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: bool = True, save_dir: str = "", names: tuple = (), on_plot=None):
    """
    Plot the confusion matrix using matplotlib and save it to a file.

    Args:
        normalize (bool, optional): Whether to normalize the confusion matrix.
        save_dir (str, optional): Directory where the plot will be saved.
        names (tuple, optional): Names of classes, used as labels on the plot.
        on_plot (callable, optional): An optional callback to pass plots path and data when they are rendered.
    """
    import matplotlib.pyplot as plt  # 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)

    names = list(names)
    fig, ax = plt.subplots(1, 1, figsize=(12, 9))
    if self.nc >= 100:  # downsample for large class count
        k = max(2, self.nc // 60)  # step size for downsampling, always > 1
        keep_idx = slice(None, None, k)  # create slice instead of array
        names = names[keep_idx]  # slice class names
        array = array[keep_idx, :][:, keep_idx]  # slice matrix rows and cols
        n = (self.nc + k - 1) // k  # number of retained classes
        nc = nn = n if self.task == "classify" else n + 1  # adjust for background if needed
    else:
        nc = nn = self.nc if self.task == "classify" else self.nc + 1
    ticklabels = (names + ["background"]) if (0 < nn < 99) and (nn == nc) else "auto"
    xy_ticks = np.arange(len(ticklabels))
    tick_fontsize = max(6, 15 - 0.1 * nc)  # Minimum size is 6
    label_fontsize = max(6, 12 - 0.1 * nc)
    title_fontsize = max(6, 12 - 0.1 * nc)
    btm = max(0.1, 0.25 - 0.001 * nc)  # Minimum value is 0.1
    with warnings.catch_warnings():
        warnings.simplefilter("ignore")  # suppress empty matrix RuntimeWarning: All-NaN slice encountered
        im = ax.imshow(array, cmap="Blues", vmin=0.0, interpolation="none")
        ax.xaxis.set_label_position("bottom")
        if nc < 30:  # Add score for each cell of confusion matrix
            for i, row in enumerate(array[:nc]):
                for j, val in enumerate(row[:nc]):
                    val = array[i, j]
                    if np.isnan(val):
                        continue
                    ax.text(
                        j,
                        i,
                        f"{val:.2f}" if normalize else f"{int(val)}",
                        ha="center",
                        va="center",
                        fontsize=10,
                        color="white" if val > (0.7 if normalize else 2) else "black",
                    )
        cbar = fig.colorbar(im, ax=ax, fraction=0.046, pad=0.05)
    title = "Confusion Matrix" + " Normalized" * normalize
    ax.set_xlabel("True", fontsize=label_fontsize, labelpad=10)
    ax.set_ylabel("Predicted", fontsize=label_fontsize, labelpad=10)
    ax.set_title(title, fontsize=title_fontsize, pad=20)
    ax.set_xticks(xy_ticks)
    ax.set_yticks(xy_ticks)
    ax.tick_params(axis="x", bottom=True, top=False, labelbottom=True, labeltop=False)
    ax.tick_params(axis="y", left=True, right=False, labelleft=True, labelright=False)
    if ticklabels != "auto":
        ax.set_xticklabels(ticklabels, fontsize=tick_fontsize, rotation=90, ha="center")
        ax.set_yticklabels(ticklabels, fontsize=tick_fontsize)
    for s in ["left", "right", "bottom", "top", "outline"]:
        if s != "outline":
            ax.spines[s].set_visible(False)  # Confusion matrix plot don't have outline
        cbar.ax.spines[s].set_visible(False)
    fig.subplots_adjust(left=0, right=0.84, top=0.94, bottom=btm)  # Adjust layout to ensure equal margins
    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) -> Tuple[np.ndarray, np.ndarray]:
    """
    Return true positives and false positives.

    Returns:
        tp (np.ndarray): True positives.
        fp (np.ndarray): 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: int) -> Tuple[float, float, float, float]:
    """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) -> float:
    """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.nan_to_num(np.array(self.mean_results())) * w).sum()

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

def update(self, results: tuple):
    """
    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: int) -> Tuple[float, float, float, float]:
    """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) -> List[float]:
    """Calculate mean of detected objects & return precision, recall, mAP50, and mAP50-95."""
    return self.box.mean_results()

def process(self, tp: np.ndarray, conf: np.ndarray, pred_cls: np.ndarray, target_cls: np.ndarray, 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 summary(self, **kwargs) -> List[Dict[str, Union[str, float]]]:
    """Return per-class detection metrics with shared scalar values included."""
    scalars = {
        "box-map": self.box.map,
        "box-map50": self.box.map50,
        "box-map75": self.box.map75,
    }
    per_class = {
        "box-p": self.box.p,
        "box-r": self.box.r,
        "box-f1": self.box.f1,
    }
    return [
        {
            "class_name": self.names[i] if hasattr(self, "names") and i in self.names else str(i),
            **{k: v[i] for k, v in per_class.items()},
            **scalars,
        }
        for i in range(len(next(iter(per_class.values()), [])))
    ]

def class_result(self, i: int) -> List[float]:
    """Return classification results for a specified class index."""
    return self.box.class_result(i) + self.seg.class_result(i)

def mean_results(self) -> List[float]:
    """Return the mean metrics for bounding box and segmentation results."""
    return self.box.mean_results() + self.seg.mean_results()

def process(
    self,
    tp: np.ndarray,
    tp_m: np.ndarray,
    conf: np.ndarray,
    pred_cls: np.ndarray,
    target_cls: np.ndarray,
    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 summary(self, **kwargs) -> List[Dict[str, Union[str, float]]]:
    """Return per-class segmentation metrics with shared scalar values included (box + mask)."""
    scalars = {
        "box-map": self.box.map,
        "box-map50": self.box.map50,
        "box-map75": self.box.map75,
        "mask-map": self.seg.map,
        "mask-map50": self.seg.map50,
        "mask-map75": self.seg.map75,
    }
    per_class = {
        "box-p": self.box.p,
        "box-r": self.box.r,
        "box-f1": self.box.f1,
        "mask-p": self.seg.p,
        "mask-r": self.seg.r,
        "mask-f1": self.seg.f1,
    }
    return [
        {"class_name": self.names[i], **{k: v[i] for k, v in per_class.items()}, **scalars}
        for i in range(len(next(iter(per_class.values()), [])))
    ]

def class_result(self, i: int) -> List[float]:
    """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) -> List[float]:
    """Return the mean results of box and pose."""
    return self.box.mean_results() + self.pose.mean_results()

def process(
    self,
    tp: np.ndarray,
    tp_p: np.ndarray,
    conf: np.ndarray,
    pred_cls: np.ndarray,
    target_cls: np.ndarray,
    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 summary(self, **kwargs) -> List[Dict[str, Union[str, float]]]:
    """Return per-class pose metrics with shared scalar values included (box + pose)."""
    scalars = {
        "box-map": self.box.map,
        "box-map50": self.box.map50,
        "box-map75": self.box.map75,
        "pose-map": self.pose.map,
        "pose-map50": self.pose.map50,
        "pose-map75": self.pose.map75,
    }
    per_class = {
        "box-p": self.box.p,
        "box-r": self.box.r,
        "box-f1": self.box.f1,
        "pose-p": self.pose.p,
        "pose-r": self.pose.r,
        "pose-f1": self.pose.f1,
    }
    return [
        {"class_name": self.names[i], **{k: v[i] for k, v in per_class.items()}, **scalars}
        for i in range(len(next(iter(per_class.values()), [])))
    ]

def process(self, targets: torch.Tensor, pred: torch.Tensor):
    """
    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 summary(self, **kwargs) -> List[Dict[str, float]]:
    """Return a single-row summary for classification metrics (top1/top5)."""
    return [{"classify-top1": self.top1, "classify-top5": self.top5}]