alterlab-shap

SHAP（SHapley Additive exPlanations）

概要

SHAPは、協力ゲーム理論のシャープレイ値を用いて、機械学習モデルの出力を説明する統一的な手法です。このスキルでは、次の項目について包括的なガイダンスを提供します。

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

SHAPは、ツリーベースのモデル（XGBoost、LightGBM、CatBoost、Random Forest）、ディープラーニングモデル（TensorFlow、PyTorch、Keras）、線形モデル、ブラックボックスモデルなど、すべての種類のモデルに対応します。

このスキルを使用するタイミング

ユーザーから次のような質問があった場合に、このスキルを使用します。

• 「モデルで最も重要な特徴量を説明してください」
• 「SHAPプロット（ウォーターフォール、ビーズウォーム、棒グラフ、散布図、フォース、ヒートマップなど）を生成してください」
• 「モデルがこの予測をした理由は何ですか？」
• 「モデルのSHAP値を計算してください」
• 「SHAPを使って特徴量の重要度を可視化してください」
• 「モデルの動作をデバッグしてください」または「モデルを検証してください」
• 「モデルにバイアスがないか確認してください」または「公平性を分析してください」
• 「モデル間で特徴量の重要度を比較してください」
• 「説明可能なAIを実装してください」または「モデルに説明機能を追加してください」
• 「特徴量間の相互作用を理解してください」
• 「モデル解釈ダッシュボードを作成してください」

このスキルを使用しないケース

ケース	代わりに使用するもの
モデルを作成する前に、生データセットのプロファイリング（分布、欠損状況、相関）を行う	alterlab-eda
モデル自体を構築、交差検証、または調整する	alterlab-scikit-learn
介入の因果効果を推定する（SHAPが説明するのはモデルの関連性であり、因果関係ではありません）	alterlab-causal-inference

クイックスタートガイド

ステップ 1：適切な説明器を選択する

判断フロー：

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を使用します（最適なアルゴリズムを自動的に選択します）

すべての説明器の種類について詳しくは、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. モデルを学習させ、適切な説明器を作成する
2. テストセットのSHAP値を計算する
3. 全体的な重要度のプロット（ビーズウォームまたは棒グラフ）を生成する
4. 上位の特徴量間の関係を調べる（散布図）
5. 特定の予測を説明する（ウォーターフォールプロット）

例：

# 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 を参照してください。

ワークフロー 4：モデルの比較

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

手順：

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

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

ワークフロー 5：公平性とバイアスの分析

目標：人口統計グループ間のモデルバイアスを検出し、分析します

手順：

1. 保護対象の属性（性別、人種、年齢など）を特定します
2. SHAP 値を計算します
3. グループ間で特徴量重要度を比較します
4. 保護対象の属性に対する SHAP 重要度を確認します
5. 代理特徴量を特定します
6. バイアスが見つかった場合は、軽減策を実施します

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

ワークフロー 6：本番環境へのデプロイ

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

手順：

1. モデルを学習させ、保存します
2. 説明器を作成し、保存します
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 個）
• または、kmeans を使用して代表的なサンプルを選択します
• 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"])

パフォーマンスの最適化

速度に関する考慮事項

説明器の速度（速い順）：

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（デフォルト）で表示されます。ファイルに保存するには、show=False を渡してから plt.savefig(...) を実行してください。
• MLflow／実験追跡：mlflow.log_figure(plt.gcf(), "shap_beeswarm.png") でプロットを記録し、特徴量ごとの np.abs(shap_values.values).mean(0) をメトリクスとして記録します。完全なスニペットは references/workflows.md（MLOps 連携）を参照してください。
• 本番環境の API：モデルと Explainer を joblib で永続化し、リクエスト時に SHAP を再計算して、ベース値と特徴量ごとの寄与度を返します。ExplanationService クラスの完全なコードは references/workflows.md（ワークフロー 7）を参照してください。

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

この SKILL.md だけでは把握できない詳細については、必要に応じて（Read 経由で）以下を読み込んでください。

• references/explainers.md — すべての Explainer クラス（コンストラクターのパラメーター、対応モデル、メソッド、パフォーマンス）。Explainer を選ぶときや、正確なパラメーターが必要なときに読み込みます。
• references/plots.md — すべてのプロット関数（パラメーター、用途、プロット選択ガイド）。可視化を選ぶときや調整するときに読み込みます。
• references/workflows.md — 詳細なステップごとのワークフロー（デバッグ、特徴量エンジニアリング、モデル比較、公平性、ディープラーニング、本番環境、時系列、MLOps）。複数のステップを伴うタスクで読み込みます。
• references/theory.md — シャープレイ値の数学的理論、公理、計算アルゴリズム、条件付き期待値、LIME／置換重要度／Gini 重要度との比較。理論に関する質問で読み込みます。

ベストプラクティスのまとめ

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 が示すのは相関であり、因果関係ではないことを忘れない：因果関係の解釈にはドメイン知識を活用してください

インストール

このスキル全体で使用する最新の API — 呼び出し可能な explainer(X) が Explanation オブジェクトを返す仕組みと、shap.plots.* 名前空間 — には shap >= 0.41 が必要です。現行リリースは 0.52（2026年5月。Python ≥ 3.12、NumPy ≥ 2 が必要）で、2026年9月時点では 0.53 がリリース候補版です。uv プロジェクトでバージョンを固定してください：

# In a uv project (adds to pyproject.toml + uv.lock):
uv add "shap>=0.41" matplotlib

# Scratch / one-off run (ephemeral env, nothing persisted):
uv run --with "shap>=0.41" --with matplotlib python explain.py

（uv pip install は、すでに有効化された venv 内でのみ動作します。依存関係を記録するため、uv add / uv run --with を使用してください。）

依存関係：numpy、pandas、scikit-learn、scipy、numba は自動的にインストールされます。matplotlib はオプション（shap[plots] エクストラ）なので、shap.plots.* を呼び出す前に、上記のとおり明示的にインストールしてください。

オプション：xgboost、lightgbm、catboost、tensorflow、torch（モデルの種類によって異なります）。

追加リソース

• 公式ドキュメント：https://shap.readthedocs.io/
• GitHub リポジトリ：https://github.com/shap/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 を幅広く解説します。