Skip to content

Register now for

# Reference for `ultralytics/models/yolo/classify/val.py`

Note

This file is available at https://github.com/ultralytics/ultralytics/blob/main/ultralytics/models/yolo/classify/val.py. If you spot a problem please help fix it by contributing a Pull Request 🛠️. Thank you 🙏!

## `` ultralytics.models.yolo.classify.val.ClassificationValidator

    ClassificationValidator(
        dataloader=None, save_dir=None, args=None, _callbacks=None
    )

Bases: `BaseValidator`

A class extending the BaseValidator class for validation based on a classification model.

This validator handles the validation process for classification models, including metrics calculation, confusion matrix generation, and visualization of results.

Attributes:

Name | Type | Description
--- | --- | ---
`targets` | `list[Tensor]` | Ground truth class labels.
`pred` | `list[Tensor]` | Model predictions.
`metrics` | `ClassifyMetrics` | Object to calculate and store classification metrics.
`names` | `dict` | Mapping of class indices to class names.
`nc` | `int` | Number of classes.
`confusion_matrix` | `ConfusionMatrix` | Matrix to evaluate model performance across classes.

Methods:

Name | Description
--- | ---
`get_desc` | Return a formatted string summarizing classification metrics.
`init_metrics` | Initialize confusion matrix, class names, and tracking containers.
`preprocess` | Preprocess input batch by moving data to device.
`update_metrics` | Update running metrics with model predictions and batch targets.
`finalize_metrics` | Finalize metrics including confusion matrix and processing speed.
`postprocess` | Extract the primary prediction from model output.
`get_stats` | Calculate and return a dictionary of metrics.
`build_dataset` | Create a ClassificationDataset instance for validation.
`get_dataloader` | Build and return a data loader for classification validation.
`print_results` | Print evaluation metrics for the classification model.
`plot_val_samples` | Plot validation image samples with their ground truth labels.
`plot_predictions` | Plot images with their predicted class labels.

Examples:

    >>> from ultralytics.models.yolo.classify import ClassificationValidator
    >>> args = dict(model="yolo11n-cls.pt", data="imagenet10")
    >>> validator = ClassificationValidator(args=args)
    >>> validator()

Notes

Torchvision classification models can also be passed to the 'model' argument, i.e. model='resnet18'.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`dataloader` | `DataLoader` | Dataloader to use for validation. | `None`
`save_dir` | `str | Path` | Directory to save results. | `None`
`args` | `dict` | Arguments containing model and validation configuration. | `None`
`_callbacks` | `list` | List of callback functions to be called during validation. | `None`

Examples:

    >>> from ultralytics.models.yolo.classify import ClassificationValidator
    >>> args = dict(model="yolo11n-cls.pt", data="imagenet10")
    >>> validator = ClassificationValidator(args=args)
    >>> validator()

Source code in `ultralytics/models/yolo/classify/val.py`

    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    def __init__(self, dataloader=None, save_dir=None, args=None, _callbacks=None) -> None:
        """
        Initialize ClassificationValidator with dataloader, save directory, and other parameters.

        Args:
            dataloader (torch.utils.data.DataLoader, optional): Dataloader to use for validation.
            save_dir (str | Path, optional): Directory to save results.
            args (dict, optional): Arguments containing model and validation configuration.
            _callbacks (list, optional): List of callback functions to be called during validation.

        Examples:
            >>> from ultralytics.models.yolo.classify import ClassificationValidator
            >>> args = dict(model="yolo11n-cls.pt", data="imagenet10")
            >>> validator = ClassificationValidator(args=args)
            >>> validator()
        """
        super().__init__(dataloader, save_dir, args, _callbacks)
        self.targets = None
        self.pred = None
        self.args.task = "classify"
        self.metrics = ClassifyMetrics()

### `` build_dataset

    build_dataset(img_path: str) -> ClassificationDataset

Create a ClassificationDataset instance for validation.

Source code in `ultralytics/models/yolo/classify/val.py`

    145
    146
    147
    def build_dataset(self, img_path: str) -> ClassificationDataset:
        """Create a ClassificationDataset instance for validation."""
        return ClassificationDataset(root=img_path, args=self.args, augment=False, prefix=self.args.split)

### `` finalize_metrics

    finalize_metrics() -> None

Finalize metrics including confusion matrix and processing speed.

Notes

This method processes the accumulated predictions and targets to generate the confusion matrix, optionally plots it, and updates the metrics object with speed information.

Examples:

    >>> validator = ClassificationValidator()
    >>> validator.pred = [torch.tensor([[0, 1, 2]])]  # Top-3 predictions for one sample
    >>> validator.targets = [torch.tensor([0])]  # Ground truth class
    >>> validator.finalize_metrics()
    >>> print(validator.metrics.confusion_matrix)  # Access the confusion matrix

Source code in `ultralytics/models/yolo/classify/val.py`

    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    def finalize_metrics(self) -> None:
        """
        Finalize metrics including confusion matrix and processing speed.

        Notes:
            This method processes the accumulated predictions and targets to generate the confusion matrix,
            optionally plots it, and updates the metrics object with speed information.

        Examples:
            >>> validator = ClassificationValidator()
            >>> validator.pred = [torch.tensor([[0, 1, 2]])]  # Top-3 predictions for one sample
            >>> validator.targets = [torch.tensor([0])]  # Ground truth class
            >>> validator.finalize_metrics()
            >>> print(validator.metrics.confusion_matrix)  # Access the confusion matrix
        """
        self.confusion_matrix.process_cls_preds(self.pred, self.targets)
        if self.args.plots:
            for normalize in True, False:
                self.confusion_matrix.plot(save_dir=self.save_dir, normalize=normalize, on_plot=self.on_plot)
        self.metrics.speed = self.speed
        self.metrics.save_dir = self.save_dir
        self.metrics.confusion_matrix = self.confusion_matrix

### `` get_dataloader

    get_dataloader(
        dataset_path: Path | str, batch_size: int
    ) -> torch.utils.data.DataLoader

Build and return a data loader for classification validation.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`dataset_path` | `str | Path` | Path to the dataset directory. | required
`batch_size` | `int` | Number of samples per batch. | required

Returns:

Type | Description
--- | ---
`DataLoader` | DataLoader object for the classification validation dataset.

Source code in `ultralytics/models/yolo/classify/val.py`

    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    def get_dataloader(self, dataset_path: Path | str, batch_size: int) -> torch.utils.data.DataLoader:
        """
        Build and return a data loader for classification validation.

        Args:
            dataset_path (str | Path): Path to the dataset directory.
            batch_size (int): Number of samples per batch.

        Returns:
            (torch.utils.data.DataLoader): DataLoader object for the classification validation dataset.
        """
        dataset = self.build_dataset(dataset_path)
        return build_dataloader(dataset, batch_size, self.args.workers, rank=-1)

### `` get_desc

    get_desc() -> str

Return a formatted string summarizing classification metrics.

Source code in `ultralytics/models/yolo/classify/val.py`

    78
    79
    80
    def get_desc(self) -> str:
        """Return a formatted string summarizing classification metrics."""
        return ("%22s" + "%11s" * 2) % ("classes", "top1_acc", "top5_acc")

### `` get_stats

    get_stats() -> dict[str, float]

Calculate and return a dictionary of metrics by processing targets and predictions.

Source code in `ultralytics/models/yolo/classify/val.py`

    140
    141
    142
    143
    def get_stats(self) -> dict[str, float]:
        """Calculate and return a dictionary of metrics by processing targets and predictions."""
        self.metrics.process(self.targets, self.pred)
        return self.metrics.results_dict

### `` init_metrics

    init_metrics(model: Module) -> None

Initialize confusion matrix, class names, and tracking containers for predictions and targets.

Source code in `ultralytics/models/yolo/classify/val.py`

    82
    83
    84
    85
    86
    87
    88
    def init_metrics(self, model: torch.nn.Module) -> None:
        """Initialize confusion matrix, class names, and tracking containers for predictions and targets."""
        self.names = model.names
        self.nc = len(model.names)
        self.pred = []
        self.targets = []
        self.confusion_matrix = ConfusionMatrix(names=model.names)

### `` plot_predictions

    plot_predictions(batch: dict[str, Any], preds: Tensor, ni: int) -> None

Plot images with their predicted class labels and save the visualization.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`batch` | `dict[str, Any]` | Batch data containing images and other information. | required
`preds` | `Tensor` | Model predictions with shape (batch_size, num_classes). | required
`ni` | `int` | Batch index used for naming the output file. | required

Examples:

    >>> validator = ClassificationValidator()
    >>> batch = {"img": torch.rand(16, 3, 224, 224)}
    >>> preds = torch.rand(16, 10)  # 16 images, 10 classes
    >>> validator.plot_predictions(batch, preds, 0)

Source code in `ultralytics/models/yolo/classify/val.py`

    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214
    def plot_predictions(self, batch: dict[str, Any], preds: torch.Tensor, ni: int) -> None:
        """
        Plot images with their predicted class labels and save the visualization.

        Args:
            batch (dict[str, Any]): Batch data containing images and other information.
            preds (torch.Tensor): Model predictions with shape (batch_size, num_classes).
            ni (int): Batch index used for naming the output file.

        Examples:
            >>> validator = ClassificationValidator()
            >>> batch = {"img": torch.rand(16, 3, 224, 224)}
            >>> preds = torch.rand(16, 10)  # 16 images, 10 classes
            >>> validator.plot_predictions(batch, preds, 0)
        """
        batched_preds = dict(
            img=batch["img"],
            batch_idx=torch.arange(batch["img"].shape[0]),
            cls=torch.argmax(preds, dim=1),
        )
        plot_images(
            batched_preds,
            fname=self.save_dir / f"val_batch{ni}_pred.jpg",
            names=self.names,
            on_plot=self.on_plot,
        )  # pred

### `` plot_val_samples

    plot_val_samples(batch: dict[str, Any], ni: int) -> None

Plot validation image samples with their ground truth labels.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`batch` | `dict[str, Any]` | Dictionary containing batch data with 'img' (images) and 'cls' (class labels). | required
`ni` | `int` | Batch index used for naming the output file. | required

Examples:

    >>> validator = ClassificationValidator()
    >>> batch = {"img": torch.rand(16, 3, 224, 224), "cls": torch.randint(0, 10, (16,))}
    >>> validator.plot_val_samples(batch, 0)

Source code in `ultralytics/models/yolo/classify/val.py`

    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    def plot_val_samples(self, batch: dict[str, Any], ni: int) -> None:
        """
        Plot validation image samples with their ground truth labels.

        Args:
            batch (dict[str, Any]): Dictionary containing batch data with 'img' (images) and 'cls' (class labels).
            ni (int): Batch index used for naming the output file.

        Examples:
            >>> validator = ClassificationValidator()
            >>> batch = {"img": torch.rand(16, 3, 224, 224), "cls": torch.randint(0, 10, (16,))}
            >>> validator.plot_val_samples(batch, 0)
        """
        batch["batch_idx"] = torch.arange(batch["img"].shape[0])  # add batch index for plotting
        plot_images(
            labels=batch,
            fname=self.save_dir / f"val_batch{ni}_labels.jpg",
            names=self.names,
            on_plot=self.on_plot,
        )

### `` postprocess

    postprocess(preds: Tensor | list[Tensor] | tuple[Tensor]) -> torch.Tensor

Extract the primary prediction from model output if it's in a list or tuple format.

Source code in `ultralytics/models/yolo/classify/val.py`

    136
    137
    138
    def postprocess(self, preds: torch.Tensor | list[torch.Tensor] | tuple[torch.Tensor]) -> torch.Tensor:
        """Extract the primary prediction from model output if it's in a list or tuple format."""
        return preds[0] if isinstance(preds, (list, tuple)) else preds

### `` preprocess

    preprocess(batch: dict[str, Any]) -> dict[str, Any]

Preprocess input batch by moving data to device and converting to appropriate dtype.

Source code in `ultralytics/models/yolo/classify/val.py`

    90
    91
    92
    93
    94
    95
    def preprocess(self, batch: dict[str, Any]) -> dict[str, Any]:
        """Preprocess input batch by moving data to device and converting to appropriate dtype."""
        batch["img"] = batch["img"].to(self.device, non_blocking=True)
        batch["img"] = batch["img"].half() if self.args.half else batch["img"].float()
        batch["cls"] = batch["cls"].to(self.device, non_blocking=True)
        return batch

### `` print_results

    print_results() -> None

Print evaluation metrics for the classification model.

Source code in `ultralytics/models/yolo/classify/val.py`

    163
    164
    165
    166
    def print_results(self) -> None:
        """Print evaluation metrics for the classification model."""
        pf = "%22s" + "%11.3g" * len(self.metrics.keys)  # print format
        LOGGER.info(pf % ("all", self.metrics.top1, self.metrics.top5))

### `` update_metrics

    update_metrics(preds: Tensor, batch: dict[str, Any]) -> None

Update running metrics with model predictions and batch targets.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`preds` | `Tensor` | Model predictions, typically logits or probabilities for each class. | required
`batch` | `dict` | Batch data containing images and class labels. | required

Notes

This method appends the top-N predictions (sorted by confidence in descending order) to the prediction list for later evaluation. N is limited to the minimum of 5 and the number of classes.

Source code in `ultralytics/models/yolo/classify/val.py`

     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    def update_metrics(self, preds: torch.Tensor, batch: dict[str, Any]) -> None:
        """
        Update running metrics with model predictions and batch targets.

        Args:
            preds (torch.Tensor): Model predictions, typically logits or probabilities for each class.
            batch (dict): Batch data containing images and class labels.

        Notes:
            This method appends the top-N predictions (sorted by confidence in descending order) to the
            prediction list for later evaluation. N is limited to the minimum of 5 and the number of classes.
        """
        n5 = min(len(self.names), 5)
        self.pred.append(preds.argsort(1, descending=True)[:, :n5].type(torch.int32).cpu())
        self.targets.append(batch["cls"].type(torch.int32).cpu())

📅 Created 1 year ago ✏️ Updated 1 year ago