Implementation:Cleanlab Cleanlab Segmentation Display Issues

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

Overview

The display_issues, common_label_issues, and filter_by_class functions provide visualization and summary tools for pixel-level label issues in semantic segmentation datasets.

Description

This module in cleanlab.segmentation.summary provides three public functions for inspecting and summarizing segmentation label issues:

• display_issues: Renders images with problematic pixels highlighted in red using matplotlib. For each flagged image, it can display up to three panels: (1) the given labels color-coded by class, (2) the argmaxed model prediction probabilities color-coded by class, and (3) the detected pixel-level errors in red. Images are sorted by total number of issue pixels (most problematic first) and limited by a configurable top parameter. Optionally displays a color legend when class names are provided. Supports excluding specific classes from the error visualization.

• common_label_issues: Tabulates the frequency of label swaps across the entire dataset. For each pixel flagged as an issue, it records which class the pixel was labeled as (given label) and which class the model predicts it should be (predicted label). Returns a DataFrame sorted by swap frequency, revealing systematic annotation patterns such as classes that are commonly confused.

• filter_by_class: Returns a subset of the issue mask involving a specific class of interest. This includes pixels where the given label is the target class (but should be something else) and pixels where the predicted label is the target class (but were labeled as something else).

The module also contains a private helper _generate_colormap that creates visually distinct colors for class visualization by distributing hues across HSV space.

Usage

Import these functions after running segmentation label issue detection (via cleanlab.segmentation.filter.find_label_issues or cleanlab.segmentation.rank.issues_from_scores). Use display_issues for visual inspection of the most problematic images, common_label_issues to understand systematic annotation error patterns, and filter_by_class to drill down into issues involving a specific class.

Code Reference

Source Location

• Repository: Cleanlab
• File: cleanlab/segmentation/summary.py
• Lines: 1-357

Signature

def display_issues(
    issues: np.ndarray,
    *,
    labels: Optional[np.ndarray] = None,
    pred_probs: Optional[np.ndarray] = None,
    class_names: Optional[List[str]] = None,
    exclude: Optional[List[int]] = None,
    top: Optional[int] = None,
    **kwargs,
) -> None

def common_label_issues(
    issues: np.ndarray,
    labels: np.ndarray,
    pred_probs: np.ndarray,
    *,
    class_names: Optional[List[str]] = None,
    exclude: Optional[List[int]] = None,
    top: Optional[int] = None,
    verbose: bool = True,
) -> pd.DataFrame

def filter_by_class(
    class_index: int,
    issues: np.ndarray,
    labels: np.ndarray,
    pred_probs: np.ndarray,
) -> np.ndarray

Import

from cleanlab.segmentation.summary import display_issues
from cleanlab.segmentation.summary import common_label_issues
from cleanlab.segmentation.summary import filter_by_class

I/O Contract

Inputs (display_issues)

Name	Type	Required	Description
issues	np.ndarray (N, H, W)	Yes	Boolean mask where True represents a pixel with a label issue. Output from find_label_issues or issues_from_scores.
labels	np.ndarray (N, H, W)	No	Integer array of given labels for each pixel (values in 0..K-1). If provided, the given label panel is displayed.
pred_probs	np.ndarray (N, K, H, W)	No	Model-predicted class probabilities. If provided, the predicted label panel is displayed.
class_names	List[str]	No	Length-K list of class name strings. If provided, a color legend is shown.
exclude	List[int]	No	Class indices to exclude from the error overlay. Requires labels to be provided.
top	int	No	Maximum number of images to display. Uses a sensible default if not specified.
**kwargs	dict	No	Additional keyword arguments passed to matplotlib's plt.show().

Outputs (display_issues)

Name	Type	Description
return	None	Displays matplotlib plots as a side effect. No return value.

Inputs (common_label_issues)

Name	Type	Required	Description
issues	np.ndarray (N, H, W)	Yes	Boolean pixel-level issue mask.
labels	np.ndarray (N, H, W)	Yes	Integer array of given labels for each pixel.
pred_probs	np.ndarray (N, K, H, W)	Yes	Model-predicted class probabilities.
class_names	List[str]	No	Class name strings. If None, integer indices are used.
exclude	List[int]	No	Class indices to exclude from the summary.
top	int	No	Maximum number of label swap rows to return.
verbose	bool	No	If True (default), prints each swap type to stdout.

Outputs (common_label_issues)

Name	Type	Description
issues_df	pd.DataFrame	DataFrame with columns: given_label (str), predicted_label (str), num_pixel_issues (int). Rows sorted by num_pixel_issues descending.

Inputs (filter_by_class)

Name	Type	Required	Description
class_index	int	Yes	The class of interest (0..K-1).
issues	np.ndarray (N, H, W)	Yes	Boolean pixel-level issue mask.
labels	np.ndarray (N, H, W)	Yes	Integer array of given labels.
pred_probs	np.ndarray (N, K, H, W)	Yes	Model-predicted class probabilities.

Outputs (filter_by_class)

Name	Type	Description
issues_subset	np.ndarray (N, H, W)	Boolean mask showing only issues involving the specified class (as either given or predicted label).

Usage Examples

Display Segmentation Issues

from cleanlab.segmentation.summary import display_issues
import numpy as np

# issues: boolean mask of shape (N, H, W) from find_label_issues
# labels: integer label array of shape (N, H, W)
# pred_probs: model predictions of shape (N, K, H, W)

display_issues(
    issues,
    labels=labels,
    pred_probs=pred_probs,
    class_names=["background", "road", "car", "pedestrian"],
    top=10,
)

Summarize Common Label Swaps

from cleanlab.segmentation.summary import common_label_issues

swap_df = common_label_issues(
    issues,
    labels=labels,
    pred_probs=pred_probs,
    class_names=["background", "road", "car", "pedestrian"],
    verbose=True,
)
print(swap_df)
# Output:
#   given_label predicted_label  num_pixel_issues
# 0        road      background              1523
# 1         car      pedestrian               847
# ...

Filter Issues for a Specific Class

from cleanlab.segmentation.summary import filter_by_class

# Get all issues involving class 2 ("car")
car_issues = filter_by_class(class_index=2, issues=issues, labels=labels, pred_probs=pred_probs)
print(f"Total car-related issue pixels: {car_issues.sum()}")

Related Pages

• Principle:Cleanlab_Cleanlab_Segmentation_Issue_Visualization