shap

SHAP

SHAP を使用して、学習済みの予測モデルが入力を出力にどのように対応付けるかを説明します。最新の shap.Explanation API を使用し、説明対象の出力と背景分布を明示したうえで、解釈する前にすべての説明を検証してください。

このスキルは SHAP 0.52.0（2026-05-28 リリース）に準拠しています。このリリースには Python 3.12 以降が必要です。

運用ルール

1. 固定済みの評価済みモデルを説明してください。予測の検証の代わりに SHAP を使用してはいけません。
2. 説明には、ホールドアウトデータまたは明確にラベル付けされた分析用の行を使用してください。背景行は、適切な学習用または参照用の母集団からのみ選択してください。
3. 説明する出力を明記してください。回帰値、raw margin、確率、対数損失、ロジット、または別のモデルメソッドのいずれかです。
4. 説明は shap.Explanation オブジェクトのまま保持してください。explainer(X) を呼び出し、.shap_values(X) はレガシーコードを維持する場合にのみ使用してください。
5. マルチ出力モデルでは、表形式のプロットを使用する前に出力を 1 つ選択してください。explanation[..., output_index]
6. base_values + values.sum(...) が、説明対象のモデル出力と正確に一致することを確認してください。
7. SHAP は、マスキング方法と背景の選択に基づくモデルの挙動の説明として扱ってください。因果関係、公平性、救済策、または科学的メカニズムを立証するものではありません。
8. 入力形状、前処理、モデルのバージョン、出力空間、行の順序を確認するまでは、加法性の不一致を決して無視しないでください。
9. 信頼できない pickle、joblib、モデル、または explainer のアーティファクトを読み込まないでください。これらの形式は、デシリアライズ時にコードを実行する可能性があります。

インストール

分離された環境を作成し、ドキュメントに記載されたリリースを固定します。

uv venv --python 3.12
source .venv/bin/activate
uv pip install "shap[plots]==0.52.0"

shap[plots] はプロットの依存関係をインストールします。プロジェクトと互換性のあるバージョンで、学習済みモデルのパッケージを追加してください。古い Python との互換性については、別の SHAP リリースを黙ってインストールするのではなく、references/migration.md を参照してください。

API の不一致をデバッグする前に、環境を確認してください。

import platform
import shap

print("Python:", platform.python_version())
print("SHAP:", shap.__version__)

標準的なワークフロー

1. 説明対象を定義する

次の項目を記録します。

• モデルおよび前処理のバージョン；
• 説明対象となる正確な呼び出し可能オブジェクトまたはモデルメソッド；
• 出力名／インデックスおよび単位；
• 評価用の行；
• 背景／参照母集団；
• マスカーおよび explainer のアルゴリズム；
• SHAP およびモデルライブラリのバージョン。

分類器では、raw margin と確率のどちらがタスクに必要かを判断してください。デフォルトはモデルの種類によって異なります。プロットの色や符号から単位を推測してはいけません。

2. Explainer とマスカーを選択する

自動選択で十分な場合は、shap.Explainer(model, masker) から始めてください。前提条件や出力制御が重要な場合は、特化型の explainer をインスタンス化してください。

状況	推奨される選択肢	重要な制約
サポート対象のツリーアンサンブル	TreeExplainer	model_output="probability" と "log_loss" には、介入型マスキングと背景データが必要です
線形モデル	LinearExplainer	マスカーによって介入型の挙動になるか、相関を考慮した挙動になるかが決まります
特徴量空間が小さい場合	ExactExplainer	制約のない特徴量の数が増えると、コストも急速に増加します
汎用の表形式呼び出し可能オブジェクト	PermutationExplainer	少なくとも順方向／逆方向の完全な順列を 1 回実行できる予算を確保してください
階層的な特徴量グループ、テキスト、または画像	PartitionExplainer	分割ツリーによって協力ゲームが変わります
微分可能なニューラルネットワーク	DeepExplainer または GradientExplainer	フレームワークのサポート、出力形状、背景の選択をテストする必要があります
レガシーな Kernel SHAP ワークフロー	KernelExplainer	通常、モデル固有の手法より大幅に低速です

詳しい選択ガイドは references/explainers.md を参照してください。特徴量に相関がある場合、構造化されている場合、疎な場合、または意味的にグループ化されている場合は、references/data-maskers.md を参照してください。

3. 最新の Explanation を計算する

この完全な二値分類の例では、明示的な背景データを使用し、正例クラスの出力を選択します。

import numpy as np
import shap
from sklearn.datasets import load_breast_cancer
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import train_test_split

X, y = load_breast_cancer(as_frame=True, return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(
    X,
    y,
    test_size=0.2,
    stratify=y,
    random_state=7,
)

model = RandomForestClassifier(
    n_estimators=200,
    min_samples_leaf=3,
    random_state=7,
    n_jobs=-1,
).fit(X_train, y_train)

background = shap.sample(X_train, 100, random_state=7)
explainer = shap.Explainer(model, background, algorithm="tree")
all_outputs = explainer(X_test)

# sklearn tree classifiers expose one output per class.
positive = all_outputs[..., 1]
assert positive.values.shape == X_test.shape

reconstructed = np.asarray(positive.base_values) + positive.values.sum(axis=1)
expected = model.predict_proba(X_test)[:, 1]
np.testing.assert_allclose(reconstructed, expected, rtol=1e-5, atol=1e-6)

shap.plots.beeswarm(positive, max_display=15)
shap.plots.waterfall(positive[0], max_display=15)

出力の形状はモデルによって異なります。

• 単一の表形式出力：(samples, features)；
• 複数の表形式出力：(samples, features, outputs)；
• 複数のモデル入力：多くの場合、配列または説明のリスト；
• 画像／テキストの説明：特徴軸は入力表現に従い、出力がある場合は最後の軸で出力を選択します。

最新の複数出力配列に、バージョン 0.45 より前のパターンである values[class_index] を使用しないでください。values[..., class_index] を使用するか、Explanation 自体をスライスしてください。

4. 必要に応じて、ツリー出力の意味論を制御する

サポート対象のツリー分類器では、確率空間での説明を明示する必要があります。

background = shap.sample(X_train, 200, random_state=7)

explainer = shap.TreeExplainer(
    model,
    data=background,
    feature_perturbation="interventional",
    model_output="probability",
)
probability_exp = explainer(X_test)

SHAP 0.52 では：

• feature_perturbation="auto" は、背景データが指定されていれば介入的意味論を、それ以外の場合はツリーパス依存の意味論を使用します；
• 確率および対数損失の出力モードは、介入的意味論でのみサポートされます；
• 精度の低いツリー近似を意図的に使用する場合は、explainer(X, approximate=True) に approximate=True を渡してください。コンストラクターには渡さないでください。

5. モデル非依存の呼び出し可能オブジェクトを意図的に使用する

解釈対象の出力を生成する、正確な呼び出し可能オブジェクトを渡します。

masker = shap.maskers.Independent(background, max_samples=100)
explainer = shap.Explainer(
    model.predict_proba,
    masker,
    algorithm="permutation",
    output_names=[str(label) for label in model.classes_],
    seed=7,
)

budget = 2 * X_test.shape[1] + 1
all_outputs = explainer(X_test.iloc[:20], max_evals=budget)
positive = all_outputs[..., 1]

推定が不安定な場合は、max_evals を増やして、より多くの順列にわたる平均を求めます。シード、背景サンプル、評価予算をレポートに記載してください。

6. 利用可能なプロットではなく、問いに合った可視化を選ぶ

問い	プロット
平均帰属の大きさが最も大きい特徴はどれですか？	shap.plots.bar(exp)
全体として、方向、大きさ、観測値はどのように変化しますか？	shap.plots.beeswarm(exp)
ある予測がベースラインと異なるのはなぜですか？	shap.plots.waterfall(exp[i])
ある特徴の帰属は、その特徴の値に応じてどのように変化しますか？	shap.plots.scatter(exp[:, feature])
説明にサンプル単位のパターンが見られますか？	shap.plots.heatmap(exp)
事前に定義したコホート間で、記述的にどのような違いがありますか？	shap.plots.bar(exp.cohorts(labels).abs.mean(0))
どのトークンまたは画像領域が出力に寄与していますか？	shap.plots.text(exp) または shap.plots.image(exp)

図をカスタマイズまたは保存する前に、references/plots.md をお読みください。

7. 結果とともに制限事項を報告する

最低限、次の項目を報告してください。

• 出力と単位；
• ベースライン／参照母集団；
• 説明器とマスカー；
• サンプル数と選択方法；
• 出力インデックス／名前；
• 加法性誤差または該当する近似診断；
• 既知の相関特徴／グループ化された特徴；
• 結果がローカル、集約、コホート固有のいずれであるか；
• 非因果性を明確に示す記述。

よくあるタスク

グローバル分析とローカル分析

グローバルプロットで重要なパターンを特定し、散布図でそのパターンを調べ、ローカルプロットで選択した行を詳しく調査します。選択ルールを記録せずに、視覚的に目立つ行だけを選ばないでください。

多クラスモデル

可能であれば output_names を設定し、explanation.output_names を確認してから、プロットの前に出力をスライスします。

class_exp = explanation[..., "class_name"]
# or
class_exp = explanation[..., class_index]

クラスをまたいで符号付き帰属を平均しないでください。クラス間で比較する場合は、同一のモデル、行、背景、出力空間、集約方法を維持してください。

コホート、サブグループ分析、公平性

SHAP で、モデルがコホートごとにどのように特徴を使用するかを比較できますが、これは公平性の検定ではありません。保護対象の特徴の SHAP の大きさが小さくても、代理変数による差別を否定できるわけではありません。また、保護対象の特徴を取り除いても、公平性が立証されるわけではありません。帰属分析を、性能、較正、エラー率、および対象領域に適した公平性指標と組み合わせてください。

コホートの構築、モデル比較、エラー分析、対数損失の説明、モニタリング、本番環境の記録については、references/workflows.md を参照してください。

テキストと画像

トークンやピクセルを通常の独立した列として扱うのではなく、ドメイン向けのマスカーを使用します。

• トークングループには shap.maskers.Text(tokenizer) と PartitionExplainer を使用します。
• 画像領域には shap.maskers.Image(...) と PartitionExplainer を使用します。
• 出力数が多く、計算コストの高いモデルでは outputs=... で制限します。

最新の例と出力形状に関するガイダンスは、references/modalities.md を参照してください。

トラブルシューティングの順序

1. Python、SHAP、モデルライブラリ、NumPy、フレームワークのバージョンを表示します。
2. モデルに、学習時とまったく同じ変換済みの列、順序、データ型、欠損値の表現が渡されていることを確認します。
3. values.shape、base_values.shape、data.shape、feature_names、output_names を表示します。
4. 選択した出力と出力単位を確認します。
5. 同じ行を同じ順序で使って予測を再計算します。
6. より小さなバッチと、代表的な背景データでテストします。
7. その後で、パッケージ固有の互換性や近似設定を調べます。

加法性の失敗、形状の不一致、カテゴリ特徴量、パイプライン、ディープラーニングフレームワーク、プロット、パフォーマンスについては、references/troubleshooting.md を参照してください。

同梱スクリプト

重要度データ、メタデータ、プロットを書き出す、決定論的で自己完結した表形式データの例を実行します。

uv run --no-project --python 3.12 --with "shap[plots]==0.52.0" \
  skills/shap/scripts/tabular_report.py --output-dir /tmp/shap-report

このスクリプトは、データをダウンロードしたり、モデルをデシリアライズしたりしません。テンプレートとして読み、出力の選択と加法性の検証を維持したまま、組み込みのデータセットとモデルを置き換えてください。

リファレンスマップ

ファイル	次の場合に参照
references/explainers.md	Explainer の選択や設定
references/data-maskers.md	背景データ、マスキングの意味、特徴量グループの選択
references/plots.md	可視化の選択、組み合わせ、保存
references/workflows.md	監査、比較、コホート、モニタリング、本番ワークフローの実行
references/modalities.md	テキスト、画像、ディープモデルの説明
references/migration.md	レガシーな SHAP コードの更新や古い Python のサポート
references/theory.md	推定対象、保証、依存関係、相互作用、制限の説明
references/troubleshooting.md	実行時、形状、加法性、互換性に関する問題の診断

主な情報源

• ドキュメント：https://shap.readthedocs.io/en/latest/
• API リファレンス：https://shap.readthedocs.io/en/latest/api.html
• リリースノート：https://shap.readthedocs.io/en/latest/release_notes.html
• リポジトリ：https://github.com/shap/shap

関連スキル

• alphagenome：GRCh38 の任意の一塩基バリアントについて、事前計算済みの AlphaGenome Atlas 効果を参照します（Phred 値付き AVI スコアと 18 個の SHAP 特徴量帰属…