Implementation:Cleanlab Cleanlab Segmentation Find Label Issues

Knowledge Sources	Cleanlab
Domains	Data Quality, Machine Learning, Computer Vision, Semantic Segmentation
Last Updated	2026-02-09 00:00 GMT

Overview

Identifies mislabeled pixels in semantic segmentation datasets by returning a per-pixel boolean mask indicating which pixels likely have label errors.

Description

find_label_issues is the core filtering function for semantic segmentation label quality. It takes per-pixel ground-truth labels and model-predicted class probabilities, then uses Confident Learning (via cleanlab's LabelInspector) to detect which pixels are likely mislabeled. The function processes data in mini-batches for memory efficiency, since segmentation datasets can contain millions of pixels per image. It supports optional downsampling to further reduce computational cost, with automatic upsampling of results back to the original resolution. A final cross-check ensures that a pixel is only flagged as an issue if the model's top predicted class disagrees with the given label at that location.

Usage

Import this function when you want to find specific pixel-level label errors in a semantic segmentation dataset. It is appropriate when you need a binary determination (issue or not) for each pixel, as opposed to continuous quality scores. This function is also called internally by the get_label_quality_scores function when using the "num_pixel_issues" method.

Code Reference

Source Location

• Repository: Cleanlab
• File: cleanlab/segmentation/filter.py
• Lines: 14-208

Signature

def find_label_issues(
    labels: np.ndarray,
    pred_probs: np.ndarray,
    *,
    batch_size: Optional[int] = None,
    n_jobs: Optional[int] = None,
    verbose: bool = True,
    **kwargs,
) -> np.ndarray:

Import

from cleanlab.segmentation.filter import find_label_issues

I/O Contract

Inputs

Name	Type	Required	Description
labels	np.ndarray	Yes	Discrete array of shape (N, H, W) containing integer class labels for each pixel, where values are in 0, 1, ..., K-1. N is the number of images, H is height, W is width.
pred_probs	np.ndarray	Yes	x) for each pixel. The 2nd dimension must be ordered to correspond to classes 0, 1, ..., K-1.
batch_size	Optional[int]	No	Size of image mini-batches for streaming computation. Larger values improve throughput; if not provided, a suitable default is used.
n_jobs	Optional[int]	No	Number of processes for multiprocessing (Linux only). Default is 1. Set to None to auto-detect based on available cores.
verbose	bool	No	If True (default), displays progress bars via tqdm.
downsample	int (via kwargs)	No	Factor to shrink labels and pred_probs by. Default is 1 (no downsampling). Must evenly divide both H and W. Larger values produce faster runtimes but potentially less accurate results.

Outputs

Name	Type	Description
label_issues	np.ndarray	Boolean mask of shape (N, H, W) where True indicates a pixel identified as having a label issue and False indicates a correctly labeled pixel.

Processing Pipeline

The function follows a multi-stage pipeline:

1. Input validation: Checks that labels and pred_probs have compatible shapes and valid values.
2. Optional downsampling: If the downsample parameter is greater than 1, both labels and pred_probs are resized by averaging over downsample-sized blocks. Pred_probs are renormalized after downsampling to ensure they sum to 1 across classes.
3. Threshold estimation (Pass 1): Iterates over all images in batches, flattening each batch of pixel data and passing it to LabelInspector.update_confident_thresholds to estimate per-class confident thresholds.
4. Label quality scoring (Pass 2): Iterates again in batches, calling LabelInspector.score_label_quality to score each pixel against the estimated thresholds.
5. Issue extraction: Calls LabelInspector.get_label_issues to obtain the ranked list of pixel indices identified as issues.
6. Coordinate mapping: Converts flat pixel indices back to (image, row, col) coordinates using modular arithmetic and np.unravel_index.
7. Cross-check filtering: For each flagged pixel, verifies that the model's argmax prediction disagrees with the given label. Pixels where the model agrees with the label are unflagged, reducing false positives.
8. Upsampling (if downsampled): If downsampling was used, the issue mask is expanded back to original resolution using np.ndarray.repeat, with per-pixel cross-checking applied at the original resolution.

Usage Examples

Basic Usage

import numpy as np
from cleanlab.segmentation.filter import find_label_issues

# N=2 images, K=3 classes, H=4, W=4
labels = np.random.randint(0, 3, size=(2, 4, 4))
pred_probs = np.random.dirichlet([1, 1, 1], size=(2, 4, 4))
# Reshape pred_probs to (N, K, H, W) format
pred_probs = np.transpose(pred_probs, (0, 3, 1, 2))

label_issues = find_label_issues(labels, pred_probs, verbose=False)
# label_issues is a boolean array of shape (2, 4, 4)
print(f"Number of pixel issues found: {label_issues.sum()}")

With Downsampling

import numpy as np
from cleanlab.segmentation.filter import find_label_issues

# For large images, use downsampling to reduce computation
labels = np.random.randint(0, 5, size=(10, 256, 256))
pred_probs = np.random.dirichlet([1]*5, size=(10, 256, 256))
pred_probs = np.transpose(pred_probs, (0, 3, 1, 2))

# Downsample by factor of 4 (H and W must be divisible by 4)
label_issues = find_label_issues(
    labels, pred_probs, downsample=4, verbose=False
)
# Result is still shape (10, 256, 256) after automatic upsampling

Related Pages

• Principle:Cleanlab_Cleanlab_Segmentation_Label_Issue_Filtering