shap

SHAP (SHapley Additive exPlanations)

概要

SHAP は、協力ゲーム理論の Shapley 値を用いて機械学習モデルの出力を説明するための統一的なアプローチです。このスキルは以下について包括的なガイダンスを提供します:

• あらゆるモデルタイプに対する SHAP 値の計算
• 特徴量の重要度を理解するための可視化の作成
• モデルの挙動のデバッグと検証
• 公平性とバイアスの分析
• 本番環境での説明可能な AI の実装

SHAP はすべてのモデルタイプで利用できます。対象は、ツリーベースのモデル (XGBoost、LightGBM、CatBoost、Random Forest)、ディープラーニングモデル (TensorFlow、PyTorch、Keras)、線形モデル、ブラックボックスモデルです。

このスキルを使うタイミング

次のようなユーザーの質問があった場合にこのスキルを起動します:

• 「モデルで最も重要な特徴量を説明して」
• 「SHAP プロットを生成して」(waterfall、beeswarm、bar、scatter、force、heatmap など)
• 「なぜモデルはこの予測をしたのか?」
• 「モデルの SHAP 値を計算して」
• 「SHAP を使って特徴量の重要度を可視化して」
• 「モデルの挙動をデバッグして」または「モデルを検証して」
• 「モデルのバイアスを確認して」または「公平性を分析して」
• 「複数のモデル間で特徴量の重要度を比較して」
• 「説明可能な AI を実装して」または「モデルに説明機能を追加して」
• 「特徴量間の相互作用を理解して」
• 「モデル解釈ダッシュボードを作成して」

クイックスタートガイド

ステップ 1: 適切な Explainer を選択する

意思決定ツリー:

1. ツリーベースのモデルですか? (XGBoost、LightGBM、CatBoost、Random Forest、Gradient Boosting)

   • shap.TreeExplainer を使用します (高速かつ厳密)

2. ディープニューラルネットワークですか? (TensorFlow、PyTorch、Keras、CNN、RNN、Transformer)

   • shap.DeepExplainer または shap.GradientExplainer を使用します

3. 線形モデルですか? (線形回帰/ロジスティック回帰、GLM)

   • shap.LinearExplainer を使用します (非常に高速)

4. その他のモデルですか? (SVM、カスタム関数、ブラックボックスモデル)

   • shap.KernelExplainer を使用します (モデル非依存だが低速)

5. 判断がつかない場合

   • shap.Explainer を使用します (最適なアルゴリズムを自動で選択します)

すべての Explainer タイプの詳細は references/explainers.md を参照してください。

ステップ 2: SHAP 値を計算する

import shap

# Example with tree-based model (XGBoost)
import xgboost as xgb

# Train model
model = xgb.XGBClassifier().fit(X_train, y_train)

# Create explainer
explainer = shap.TreeExplainer(model)

# Compute SHAP values
shap_values = explainer(X_test)

# The shap_values object contains:
# - values: SHAP values (feature attributions)
# - base_values: Expected model output (baseline)
# - data: Original feature values

ステップ 3: 結果を可視化する

全体的な理解のため (データセット全体):

# Beeswarm plot - shows feature importance with value distributions
shap.plots.beeswarm(shap_values, max_display=15)

# Bar plot - clean summary of feature importance
shap.plots.bar(shap_values)

個々の予測のため:

# Waterfall plot - detailed breakdown of single prediction
shap.plots.waterfall(shap_values[0])

# Force plot - additive force visualization
shap.plots.force(shap_values[0])

特徴量同士の関係のため:

# Scatter plot - feature-prediction relationship
shap.plots.scatter(shap_values[:, "Feature_Name"])

# Colored by another feature to show interactions
shap.plots.scatter(shap_values[:, "Age"], color=shap_values[:, "Education"])

すべてのプロットタイプの包括的なガイドは references/plots.md を参照してください。

主要なワークフロー

このスキルはいくつかの一般的なワークフローをサポートします。現在のタスクに合ったワークフローを選択してください。

ワークフロー 1: 基本的なモデルの説明

目標: モデルの予測を左右する要因を理解する

手順:

1. モデルを学習し、適切な Explainer を作成する
2. テストセットの SHAP 値を計算する
3. 全体的な重要度プロットを生成する (beeswarm または bar)
4. 上位の特徴量の関係を調べる (scatter プロット)
5. 特定の予測を説明する (waterfall プロット)

例:

# Step 1-2: Setup
explainer = shap.TreeExplainer(model)
shap_values = explainer(X_test)

# Step 3: Global importance
shap.plots.beeswarm(shap_values)

# Step 4: Feature relationships
shap.plots.scatter(shap_values[:, "Most_Important_Feature"])

# Step 5: Individual explanation
shap.plots.waterfall(shap_values[0])

ワークフロー 2: モデルのデバッグ

目標: モデルの問題を特定して修正する

手順:

1. SHAP 値を計算する
2. 予測誤差を特定する
3. 誤分類されたサンプルを説明する
4. 想定外の特徴量の重要度を確認する (データリーケージ)
5. 特徴量の関係が妥当かを検証する
6. 特徴量の相互作用を確認する

詳細なデバッグのワークフローは references/workflows.md を参照してください。

ワークフロー 3: 特徴量エンジニアリング

目標: SHAP の知見を使って特徴量を改善する

手順:

1. ベースラインモデルの SHAP 値を計算する
2. 非線形な関係を特定する (変換の候補)
3. 特徴量の相互作用を特定する (交互作用項の候補)
4. 新しい特徴量を作成する
5. 再学習して SHAP 値を比較する
6. 改善を検証する

詳細な特徴量エンジニアリングのワークフローは references/workflows.md を参照してください。

Workflow 4: モデル比較

目標: 複数のモデルを比較し、最も解釈しやすい選択肢を選ぶ

手順:

1. 複数のモデルを学習させる
2. それぞれについて SHAP 値を計算する
3. グローバルな特徴量重要度を比較する
4. 特徴量ランキングの一貫性を確認する
5. 複数のモデルにわたって特定の予測を分析する
6. 精度、解釈可能性、一貫性に基づいて選択する

詳細なモデル比較ワークフローについては references/workflows.md を参照してください。

Workflow 5: 公平性とバイアス分析

目標: 人口統計学的グループ間でのモデルのバイアスを検出and分析する

手順:

1. 保護属性（性別、人種、年齢など）を特定する
2. SHAP 値を計算する
3. グループ間で特徴量重要度を比較する
4. 保護属性の SHAP 重要度を確認する
5. プロキシ特徴量を特定する
6. バイアスが見つかった場合は緩和策を実装する

詳細な公平性分析ワークフローについては references/workflows.md を参照してください。

Workflow 6: 本番環境へのデプロイ

目標: SHAP による説明を本番システムに統合する

手順:

1. モデルを学習させて保存する
2. Explainer を作成して保存する
3. 説明サービスを構築する
4. 予測と説明を返す API エンドポイントを作成する
5. キャッシュと最適化を実装する
6. 説明の品質を監視する

詳細な本番デプロイワークフローについては references/workflows.md を参照してください。

主要な概念

SHAP 値

定義: SHAP 値は、モデルの期待出力（ベースライン）からの偏差として測定され、各特徴量が予測にどれだけ寄与したかを定量化します。

特性:

• 加法性: SHAP 値の合計は、予測値とベースラインの差に等しい
• 公平性: ゲーム理論のシャープレイ値に基づく
• 一貫性: ある特徴量の重要度が高まると、その SHAP 値も大きくなる

解釈:

• SHAP 値が正 → 特徴量が予測値を押し上げる
• SHAP 値が負 → 特徴量が予測値を押し下げる
• 絶対値 → 特徴量の影響の強さ
• SHAP 値の合計 → ベースラインからの予測値の総変化量

例:

Baseline (expected value): 0.30
Feature contributions (SHAP values):
  Age: +0.15
  Income: +0.10
  Education: -0.05
Final prediction: 0.30 + 0.15 + 0.10 - 0.05 = 0.50

背景データ / ベースライン

目的: 基準となる期待値を設定するための「典型的な」入力を表す

選択方法:

• 学習データからランダムにサンプリングする（50〜1000 サンプル）
• もしくは k-means を使って代表的なサンプルを選択する
• DeepExplainer / KernelExplainer の場合、100〜1000 サンプルが精度と速度のバランスに優れる

影響: ベースラインは SHAP 値の大きさに影響しますが、相対的な重要度には影響しません

モデル出力の種類

重要な注意点: モデルが何を出力しているかを理解してください

• 生の出力: 回帰またはツリーのマージン向け
• 確率: 分類の確率向け
• 対数オッズ: ロジスティック回帰向け（シグモイド適用前）

例: XGBoost の分類器は、デフォルトでマージン出力（対数オッズ）を説明します。確率を説明するには、TreeExplainer で model_output="probability" を使用してください。

よくあるパターン

パターン 1: 完全なモデル分析

# 1. Setup
explainer = shap.TreeExplainer(model)
shap_values = explainer(X_test)

# 2. Global importance
shap.plots.beeswarm(shap_values)
shap.plots.bar(shap_values)

# 3. Top feature relationships
top_features = X_test.columns[np.abs(shap_values.values).mean(0).argsort()[-5:]]
for feature in top_features:
    shap.plots.scatter(shap_values[:, feature])

# 4. Example predictions
for i in range(5):
    shap.plots.waterfall(shap_values[i])

パターン 2: コホート比較

# Define cohorts
cohort1_mask = X_test['Group'] == 'A'
cohort2_mask = X_test['Group'] == 'B'

# Compare feature importance
shap.plots.bar({
    "Group A": shap_values[cohort1_mask],
    "Group B": shap_values[cohort2_mask]
})

パターン 3: エラーのデバッグ

# Find errors
errors = model.predict(X_test) != y_test
error_indices = np.where(errors)[0]

# Explain errors
for idx in error_indices[:5]:
    print(f"Sample {idx}:")
    shap.plots.waterfall(shap_values[idx])

    # Investigate key features
    shap.plots.scatter(shap_values[:, "Suspicious_Feature"])

パフォーマンスの最適化

速度に関する考慮事項

Explainer の速度（速い順）:

1. LinearExplainer - ほぼ瞬時
2. TreeExplainer - 非常に高速
3. DeepExplainer - ニューラルネットワーク向けに高速
4. GradientExplainer - ニューラルネットワーク向けに高速
5. KernelExplainer - 低速（必要な場合のみ使用）
6. PermutationExplainer - 非常に低速だが正確

最適化戦略

大規模データセットの場合:

# Compute SHAP for subset
shap_values = explainer(X_test[:1000])

# Or use batching
batch_size = 100
all_shap_values = []
for i in range(0, len(X_test), batch_size):
    batch_shap = explainer(X_test[i:i+batch_size])
    all_shap_values.append(batch_shap)

可視化の場合:

# Sample subset for plots
shap.plots.beeswarm(shap_values[:1000])

# Adjust transparency for dense plots
shap.plots.scatter(shap_values[:, "Feature"], alpha=0.3)

本番環境の場合:

# Cache explainer
import joblib
joblib.dump(explainer, 'explainer.pkl')
explainer = joblib.load('explainer.pkl')

# Pre-compute for batch predictions
# Only compute top N features for API responses

トラブルシューティング

問題: Explainer の選択ミス

問題: ツリーモデルに KernelExplainer を使用している（低速で不要） 解決策: ツリーベースのモデルには、必ず TreeExplainer を使用してください

問題: 背景データが不足している

問題: DeepExplainer / KernelExplainer に対して背景サンプルが少なすぎる 解決策: 100〜1000 の代表的なサンプルを使用してください

問題: 単位の混同

問題: 対数オッズを確率として解釈している 解決策: モデルの出力の種類を確認し、値が確率、対数オッズ、生の出力のいずれであるかを理解してください

問題：プロットが表示されない

問題：Matplotlib のバックエンドに関する問題 解決策：バックエンドが正しく設定されていることを確認します。必要に応じて plt.show() を使用します

問題：プロットが多くの特徴量でごちゃつく

問題：デフォルトの max_display=10 は多すぎる場合も、少なすぎる場合もあります 解決策：max_display パラメーターを調整するか、特徴量のクラスタリングを使用します

問題：計算が遅い

問題：非常に大きなデータセットに対して SHAP を計算しています 解決策：サブセットをサンプリングする、バッチ処理を使用する、または専用の Explainer（KernelExplainer ではないもの）が使われていることを確認します

他のツールとの連携

Jupyter ノートブック

• インタラクティブな force プロットがシームレスに動作します
• show=True（デフォルト）でインライン表示できます
• 説明文には Markdown を組み合わせます

MLflow／実験のトラッキング

import mlflow

with mlflow.start_run():
    # Train model
    model = train_model(X_train, y_train)

    # Compute SHAP
    explainer = shap.TreeExplainer(model)
    shap_values = explainer(X_test)

    # Log plots
    shap.plots.beeswarm(shap_values, show=False)
    mlflow.log_figure(plt.gcf(), "shap_beeswarm.png")
    plt.close()

    # Log feature importance metrics
    mean_abs_shap = np.abs(shap_values.values).mean(axis=0)
    for feature, importance in zip(X_test.columns, mean_abs_shap):
        mlflow.log_metric(f"shap_{feature}", importance)

本番環境の API

class ExplanationService:
    def __init__(self, model_path, explainer_path):
        self.model = joblib.load(model_path)
        self.explainer = joblib.load(explainer_path)

    def predict_with_explanation(self, X):
        prediction = self.model.predict(X)
        shap_values = self.explainer(X)

        return {
            'prediction': prediction[0],
            'base_value': shap_values.base_values[0],
            'feature_contributions': dict(zip(X.columns, shap_values.values[0]))
        }

リファレンスドキュメント

このスキルには、トピック別に整理された包括的なリファレンスドキュメントが含まれています。

references/explainers.md

すべての Explainer クラスを網羅したガイドです。

• TreeExplainer - 木ベースのモデルに対する高速で正確な説明
• DeepExplainer - ディープラーニングモデル（TensorFlow、PyTorch）
• KernelExplainer - モデルに依存しない説明（あらゆるモデルで動作）
• LinearExplainer - 線形モデルに対する高速な説明
• GradientExplainer - ニューラルネットワーク向けの勾配ベースの説明
• PermutationExplainer - あらゆるモデルに対して正確ですが、処理が遅い説明

内容：コンストラクターのパラメーター、メソッド、対応モデル、使用する場面、例、パフォーマンスに関する考慮事項。

references/plots.md

包括的な可視化ガイドです。

• ウォーターフォールプロット - 個々の予測の内訳
• ビースウォームプロット - 値の分布を含む全体的な重要度
• 棒グラフ - 特徴量の重要度を明瞭に要約
• 散布図 - 特徴量と予測の関係、および相互作用
• フォースプロット - インタラクティブな加算型フォース可視化
• ヒートマップ - 複数サンプルの比較グリッド
• バイオリンプロット - 分布に焦点を当てた代替手段
• 決定プロット - 多クラス予測の経路

内容：パラメーター、ユースケース、例、ベストプラクティス、プロットの選択ガイド。

references/workflows.md

詳細なワークフローとベストプラクティスです。

• 基本的なモデル説明のワークフロー
• モデルのデバッグと検証
• 特徴量エンジニアリングのガイダンス
• モデルの比較と選択
• 公平性とバイアスの分析
• ディープラーニングモデルの説明
• 本番環境へのデプロイ
• 時系列モデルの説明
• よくある落とし穴と解決策
• 高度な手法
• MLOps との連携

内容：手順、コード例、判断基準、トラブルシューティング。

references/theory.md

理論的基礎：

• ゲーム理論における Shapley 値
• 数式と特性
• 他の説明手法（LIME、DeepLIFT など）との関連
• SHAP の計算アルゴリズム（Tree SHAP、Kernel SHAP など）
• 条件付き期待値とベースラインの選択
• SHAP 値の解釈
• 相互作用値
• 理論的な制約と考慮事項

内容：数学的基礎、証明、比較、高度なトピック。

使用ガイドライン

リファレンスファイルを読み込むタイミング：

• 特定の Explainer の種類やパラメーターについて詳しい情報が必要な場合は、explainers.md を読み込みます
• 詳細な可視化ガイダンスが必要な場合や、プロットの選択肢を確認する場合は、plots.md を読み込みます
• 複雑な複数手順のタスク（デバッグ、公平性の分析、本番環境へのデプロイなど）がある場合は、workflows.md を読み込みます
• 理論的基礎、Shapley 値、または数学的な詳細について質問された場合は、theory.md を読み込みます

デフォルトの進め方（リファレンスを読み込まない場合）：

• 基本的な説明やクイックスタートには、この SKILL.md を使用します
• 標準的なワークフローと一般的なパターンを提示します
• さらに詳しい情報が必要な場合は、リファレンスファイルを利用できます

リファレンスの読み込み：

# To load reference files, use the Read tool with appropriate file path:
# /path/to/shap/references/explainers.md
# /path/to/shap/references/plots.md
# /path/to/shap/references/workflows.md
# /path/to/shap/references/theory.md

ベストプラクティスの概要

1. 適切な explainer を選ぶ: 可能な場合は専用の explainer（TreeExplainer、DeepExplainer、LinearExplainer）を使用し、必要がない限り KernelExplainer は避けてください

2. まず全体を見てから、個別に見る: 全体像の把握には beeswarm / bar プロットから始め、詳細は waterfall / scatter プロットで掘り下げてください

3. 複数の可視化を使う: プロットごとに得られる洞察は異なります。全体（beeswarm）、個別（waterfall）、関係性（scatter）のビューを組み合わせてください

4. 適切な背景データを選ぶ: 学習データから代表的なサンプルを 50〜1000 件使用してください

5. モデル出力の単位を理解する: 確率、対数オッズ、生の出力のいずれを説明しているのかを把握してください

6. ドメイン知識で検証する: SHAP が示すのはモデルの振る舞いです。解釈と検証にはドメインの専門知識を活用してください

7. パフォーマンスを最適化する: 可視化にはサブセットをサンプリングし、大規模データはバッチ処理し、本番環境では explainer をキャッシュしてください

8. データリークを確認する: 想定外に高い特徴量重要度は、データ品質の問題を示している可能性があります

9. 特徴量の相関を考慮する: 冗長な特徴量には、TreeExplainer の相関を考慮したオプションや特徴量クラスタリングを使用してください

10. SHAP が示すのは関連性であり、因果関係ではないことを覚えておく: 因果的な解釈にはドメイン知識を活用してください

インストール

# Basic installation
uv pip install shap

# With visualization dependencies
uv pip install shap matplotlib

# Latest version
uv pip install -U shap

依存関係: numpy、pandas、scikit-learn、matplotlib、scipy

オプション: xgboost、lightgbm、tensorflow、torch（モデルの種類に応じて）

追加リソース

• 公式ドキュメント: https://shap.readthedocs.io/
• GitHub リポジトリ: https://github.com/slundberg/shap
• 原論文: Lundberg & Lee (2017) - "A Unified Approach to Interpreting Model Predictions"
• Nature MI 論文: Lundberg et al. (2020) - "From local explanations to global understanding with explainable AI for trees"

このスキルは、あらゆるユースケースとモデルの種類を対象とした SHAP によるモデルの解釈可能性について、包括的な内容を提供します。