Evaluation と Result

このページでは、EvaluatorクラスとResultクラスの詳細な使い方を説明します。

Evaluator

Evaluatorは、収集したデータに対して評価を実行し、過去の評価結果を管理するためのクラスです。

初期化

from ml_debugger.evaluator import Evaluator

evaluator = Evaluator(
    model_name="resnet18",
    version_name="v1",
)

評価の実行

result = evaluator.request_evaluation()

オプションパラメータ

result = evaluator.request_evaluation(
    result_name="my_evaluation",    # 評価結果の識別子（省略可）
    n_epoch="latest",               # 対象エポック（省略可）
)

パラメータ	説明	デフォルト
`result_name`	評価結果の識別子。省略時は自動生成	自動生成
`n_epoch`	評価対象のエポック。`"latest"`で最新エポック	全エポック

n_epochの明示的な指定を推奨

n_epoch はデフォルトでは全エポックが対象ですが、意図しないデータの混在を避けるために明示的に値を指定することを推奨します。 "latest" はtimestampに基づいて最新エポックを判定するため、同じ version_name でエポックをやり直した場合に意図しないデータが使用される可能性があります。詳細は model_name / version_name を参照してください。

評価結果一覧の取得

results_df = evaluator.list_results()

オプションパラメータ

results_df = evaluator.list_results(
    result_name="my_evaluation",    # 特定のresult_nameでフィルター（省略可）
    method_name="default",          # 評価方法名でフィルター（省略可）
    n_epoch="latest",               # 対象エポックでフィルター（省略可）
)

パラメータ	型	デフォルト	説明
`result_name`	`Optional[str]`	`None`	特定のresult_nameでフィルター。`None`で全結果を取得
`method_name`	`Optional[str]`	`None`	評価方法名でフィルター。`"default"`エイリアス利用可能
`n_epoch`	`Union[str, int, None]`	`"latest"`	対象エポックでフィルター。`"latest"`で最新、`"all"`で全エポック、整数で特定エポック

出力例

                                    result_name        method_name n_epoch  \
0  resnet18_v1_classification_v1_20251219  classification_v1    None

                    created_at                 completed_at options     status
0  2025-12-19T07:49:28.706773Z  2025-12-19T07:49:30.994131Z      {}  Completed

特定の評価結果の取得

result = evaluator.get_result(result_name="resnet18_v1_classification_v1_20251219")

Result

Resultは、単一の評価結果を表すクラスです。メトリクスやエラーコードの詳細を取得できます。

基本情報

print(result.result_name)   # 評価結果の識別子
print(result.model_name)    # モデル名
print(result.version_name)  # バージョン名

メトリクスサマリー

print(result.metrics_summary())

# 特定のdataset_typeのみ表示
print(result.metrics_summary(dataset_type="train"))

パラメータ	型	デフォルト	説明
`dataset_type`	`Optional[str]`	`None`	出力をフィルタリングするdataset_type。`None`で全dataset_typeを表示

出力例（Classification task）：

dataset  counts  accuracy  auroc  auprc  net_entropy_loss  net_entropy  error_proba_auroc  error_proba_auprc
train    5000    0.098     0.457  0.094  12875.500         10480.190    0.857              0.453

出力されるメトリクスはタスクによって異なります。

ClassificationObject Detection3D Object Detection

メトリクス	説明
`counts`	データポイント数
`accuracy`	正解率
`auroc`	ROC曲線下面積
`auprc`	PR曲線下面積
`net_entropy_loss`	エントロピー損失の合計
`net_entropy`	エントロピーの合計
`error_proba_auroc`	エラー確率推定のAUROC
`error_proba_auprc`	エラー確率推定のAUPRC

AP / AR系の指標は、max detections = [1, 10, 100] の COCOeval に基づいて算出されます。

メトリクス	説明
`counts`	検出数（予測 + GT）
`counts_pred_boxes` / `counts_gt_boxes`	予測BBox / Ground Truth BBox総数
`counts_img`	画像数
`matched_ratio`	マッチした検出の割合
`AP` / `AP_50` / `AP_75`	Average Precision（全体 / IoU=0.50 / IoU=0.75）
`AP_small` / `AP_medium` / `AP_large`	オブジェクトサイズ別のAP
`AR_1` / `AR_10` / `AR_100`	最大検出数別のAverage Recall
`AR_small` / `AR_medium` / `AR_large`	オブジェクトサイズ別のAR
`average_iou_matched` / `average_iou`	マッチした検出 / 全体の平均IoU
`average_score`	予測スコアの平均
`accuracy`	分類正解率
`net_entropy` / `net_entropy_loss`	エントロピー / エントロピー損失の合計
`net_focal_loss`	Focal Lossの合計
`average_logit_margin`	ロジットマージンの平均
`error_proba_auroc` / `error_proba_auprc`	エラー確率推定のAUROC / AUPRC

2D ODの共通メトリクス（counts, matched_ratio, accuracy, entropy, focal loss, logit margin, error_proba等）に加え、AP/AR系が以下の3D固有メトリクスに置き換わります。

メトリクス	説明
`mAP_3D` / `mAP_BEV`	3D / BEV mean Average Precision
`AP_3D_025` / `AP_3D_05` / `AP_3D_07`	3D AP（IoU閾値 0.25 / 0.50 / 0.70）
`AP_BEV_025` / `AP_BEV_05` / `AP_BEV_07`	BEV AP（IoU閾値 0.25 / 0.50 / 0.70）
`average_iou_3d` / `average_iou_bev`	平均3D IoU / 平均BEV IoU

Issue Categoryサマリー

print(result.issue_category_summary())

# 特定のdataset_typeのみ表示
print(result.issue_category_summary(dataset_type="train"))

パラメータ	型	デフォルト	説明
`dataset_type`	`Optional[str]`	`None`	出力をフィルタリングするdataset_type。`None`で全dataset_typeを表示

出力例：

dataset  stable_coverage_ratio  operational_coverage_ratio  hotspot_ratio  recessive_hotspot_ratio  critical_hotspot_ratio  aleatoric_hotspot_ratio
train    0.000                  0.001                       0.753          0.226                    0.019                   0.006

Issue Categoryの説明

MLdebuggerは、データポイントを内部特徴量の安定性とエラー確率に基づいて6つのカテゴリに分類します。

カテゴリ	説明	推奨アクション
`stable_coverage` (Highly Stable)	内部特徴量が安定しており、予測の信頼性が高い領域	対応不要
`operational_coverage` (Stable)	モデルの確信度は高くないが、内部特徴量が安定しており運用上許容される領域	データ追加（低優先度）、継続モニタリング
`hotspot` (Unstable)	内部特徴量が不安定で、予測の信頼性を保証することが困難な領域	データ追加、再学習、Data Augmentation
`recessive_hotspot` (Under-Confidence)	モデルの確信度が低く、エラーを予測しやすい領域	確信度フィルタリング、Human-in-the-loop、別モデル分岐
`critical_hotspot` (Over-Confidence)	内部特徴量からエラーが頻発する可能性が高い領域	最優先でデータ追加、Hard Negative Mining、アンサンブル検討
`aleatoric_hotspot` (Outlier)	特徴量が不十分で、モデルが学習困難な領域	アノテーション修正、タスク定義見直し、OOD検出で除外

詳細サマリー

result.get_summary()

# 特定のdataset_typeのみ表示
result.get_summary(dataset_type="train")

パラメータ	型	デフォルト	説明
`dataset_type`	`Optional[str]`	`None`	出力をフィルタリングするdataset_type。`None`で全dataset_typeを表示

このメソッドは以下を含む詳細なサマリーを表示します：

評価情報（model, version, result_name）
メトリクスサマリー
Issue Categoryサマリー
各カテゴリの詳細なエラーコード分布

Issue一覧の取得

issues_df = result.get_issues()

DataFrameとして全てのIssue（エラーコード）の一覧を取得できます。

カラム

カラム	説明
`issue_id`	Issue ID
`dataset_type`	データセット種別
`category`	Issue Category
`error_code`	エラーコード
`debug_code`	デバッグコード（epistemic/aleatoric）
`counts_ratio`	全体に対する割合
`counts`	データポイント数
その他	タスク固有のメトリクス

Object Detection（2D / 3D）では、上記に加えて diagnosis（診断結果）、counts_pred_boxes / counts_gt_boxes（予測/GT BBox数）、average_iou、average_score が含まれます。 3D ODではさらに average_iou_3d、average_iou_bev が追加されます。

タスク別のエラーコード

error_codeとdebug_codeの形式はタスクによって異なります。詳細はError Codes - ClassificationおよびError Codes - Object Detectionを参照してください。

カスタムビューの取得

任意の条件別にIssueの状況を可視化するための機能です。 Tracerでデータ収集時にカスタムメタデータ（追加カラム）を記録していた場合、そのメタデータごとのIssue分布の違いを可視化できます。

view_df = result.get_view(
    groupby=["category", "error_code"],
    adjustby="category",
)

パラメータ

パラメータ	型	説明
`groupby`	`List[str]`	グループ化するカラムのリスト
`adjustby`	`Optional[str]`	比率を調整する基準カラム
`query`	`Optional[str]`	フィルタリング条件（pandas query形式）

基本的な使用例

# Hotspotカテゴリのみを取得
hotspot_view = result.get_view(
    query="category == 'hotspot'",
    groupby=["error_code"],
)

# dataset_type別に集計
dataset_view = result.get_view(
    groupby=["dataset_type", "category"],
)

カスタムメタデータを使った分析

Tracerでデータ収集時に追加カラムを定義していた場合、そのカラムでグループ化してIssue分布を分析できます。

# Object Detection: オブジェクトサイズ別のエラー分布を確認
size_view = result.get_view(
    groupby=["object_size", "category"],
    adjustby="object_size",
)

# Classification: 撮影条件別のエラー分布を確認
condition_view = result.get_view(
    groupby=["lighting_condition", "category"],
    adjustby="lighting_condition",
)

カスタムメタデータの活用

Tracerでデータ収集時にadditional_columnsを定義することで、任意のメタデータを記録できます。これにより、以下のような分析が可能になります：

Object Detection: オブジェクトサイズ別、オクルージョン有無別のエラー発生状況
Classification: 撮影環境別、データソース別のエラー分布
共通: 時間帯別、デバイス別、地域別などの条件別分析

エラーコードについて

エラーコードの形式と読み方はタスクによって異なります。

完全なサンプルコード

from ml_debugger.evaluator import Evaluator

# Evaluatorの初期化
evaluator = Evaluator(
    model_name="resnet18",
    version_name="v1",
)

# 評価の実行
result = evaluator.request_evaluation(
    result_name="experiment_20251219",
    n_epoch="latest",
)

# 結果の確認
print("=== Metrics Summary ===")
print(result.metrics_summary())

print("\n=== Issue Category Summary ===")
print(result.issue_category_summary())

print("\n=== Detailed Summary ===")
result.get_summary()

# Issue一覧をDataFrameで取得
issues_df = result.get_issues()
print(f"\nTotal issues: {len(issues_df)}")

# Hotspotの詳細を確認
hotspot_issues = issues_df[issues_df["category"] == "hotspot"]
print(f"Hotspot issues: {len(hotspot_issues)}")

# カスタムビューの取得
view = result.get_view(
    groupby=["category"],
    adjustby=None,
)
print("\n=== Category Distribution ===")
print(view)

次のステップ

Error Codes - Classification - Classificationエラーコードの定義
Error Codes - Object Detection - Object Detectionエラーコードの定義