Implementation:Obss Sahi Analyse

Knowledge Sources	SAHI SAHI Docs
Domains	Object_Detection, Evaluation, Error_Analysis
Last Updated	2026-02-08 12:00 GMT

Overview

Concrete tool for performing TIDE-style error analysis on COCO detection results with visual precision-recall curve output provided by the SAHI library.

Description

analyse() is the high-level entry point for COCO error analysis in SAHI. It:

1. Validates that pycocotools and matplotlib are installed
2. Delegates to _analyse_results() which performs the core analysis
3. _analyse_results() loads ground truth and predictions using pycocotools
4. For each category, _analyze_individual_category() computes precision at multiple confusion levels (C75, C50, Loc, Sim, Oth, BG, FN)
5. Categories are analyzed in parallel using multiprocessing.Pool(processes=48)
6. _makeplot() generates precision-recall curve plots for each category and overall
7. Results are exported as PNG plots to the output directory

The analysis generates both per-category precision-recall curves and an overall summary. Optional extra plots (bar charts, histograms) can be included.

Usage

Use this function after generating COCO-format predictions to diagnose detection errors. Can be invoked programmatically or via CLI: sahi coco analyse.

Code Reference

Source Location

• Repository: sahi
• File: sahi/scripts/coco_error_analysis.py
• Lines: L444-482 (analyse), L298-441 (_analyse_results), L234-295 (_analyze_individual_category), L43-92 (_makeplot)

Signature

def analyse(
    dataset_json_path: str,
    result_json_path: str,
    out_dir: str | None = None,
    type: str = "bbox",
    no_extraplots: bool = False,
    areas: list[int] = [1024, 9216, 10000000000],
    max_detections: int = 500,
    return_dict: bool = False,
) -> dict | None:
    """Perform TIDE-style error analysis on detection results.

    Args:
        dataset_json_path: Path to COCO ground truth JSON
        result_json_path: Path to COCO prediction results JSON
        out_dir: Output directory for analysis plots
        type: "bbox" or "segm"
        no_extraplots: Skip extra bar/stat plots
        areas: Area boundaries [small, medium, large]
        max_detections: Max detections per image (default 500)
        return_dict: Return results dict if True
    """

Import

from sahi.scripts.coco_error_analysis import analyse

I/O Contract

Inputs

Name	Type	Required	Description
dataset_json_path	str	Yes	Path to COCO ground truth annotation JSON
result_json_path	str	Yes	Path to COCO prediction results JSON
out_dir	str	No	Output directory for analysis plots
type	str	No	"bbox" or "segm" (default "bbox")
no_extraplots	bool	No	Skip extra bar and histogram plots (default False)
areas	list[int]	No	Area boundaries [small, medium, large] (default [1024, 9216, 10^10])
max_detections	int	No	Max detections per image (default 500)
return_dict	bool	No	Return export paths dict (default False)

Outputs

Name	Type	Description
return	dict or None	If return_dict=True: dict mapping result types to export file paths
PNG plots	files	Per-category and overall precision-recall curves in out_dir/bbox/ or out_dir/segm/

Usage Examples

Basic Error Analysis

from sahi.scripts.coco_error_analysis import analyse

result = analyse(
    dataset_json_path="ground_truth.json",
    result_json_path="predictions.json",
    out_dir="./error_analysis/",
    type="bbox",
    return_dict=True,
)

# Result contains paths to generated plots
for result_type, paths in result.items():
    print(f"{result_type}: {paths}")

CLI Usage

sahi coco analyse \
    --dataset_json_path ground_truth.json \
    --result_json_path predictions.json \
    --out_dir ./error_analysis/ \
    --type bbox

Minimal Analysis (No Extra Plots)

from sahi.scripts.coco_error_analysis import analyse

# Fast analysis without bar charts and histograms
analyse(
    dataset_json_path="ground_truth.json",
    result_json_path="predictions.json",
    out_dir="./quick_analysis/",
    no_extraplots=True,
)

Related Pages

Implements Principle

• Principle:Obss_Sahi_COCO_Error_Analysis

Requires Environment

• Environment:Obss_Sahi_Python_Pycocotools