model-explanation

Model Explanation Report (portable)

Perform interpretability analysis on the XGBoost model based on SHAP (SHapley Additive exPlanations), and generate a Markdown report containing visualization charts.

---

Parameter Description

Parameter	Required	Default Value	Description
--model_path	✅	-	XGBoost model file path (.json)
--data_path	✅	-	Data file path (parquet/csv)
--target	✅	-	Target variable column name
--features		auto	Feature list, comma-separated. If not provided, read automatically from <model>_meta.json automatically
--sample_id		-	Single-sample explanation: sample index or ID
--sample_filter		-	Single-sample explanation: pandas query condition
--top_n		20	Global explanation displays Top N features
--interaction_features		-	Interaction analysis feature pair, e.g. f1,f2
--output_dir		./outputs/<ts>	Artifact output directory
--output_name		model_explanation_report	Report base name
--config		-	JSON configuration file path

---

Execution Method

python scripts/explainer.py \
  --model_path ./models/my_model.json \
  --data_path ./examples/toy.parquet \
  --target y_label \
  --output_dir ./outputs/explain_run

Single-sample explanation:

python scripts/explainer.py \
  --model_path ./models/my_model.json \
  --data_path ./examples/toy.parquet \
  --target y_label \
  --sample_id 1001 \
  --output_dir ./outputs/explain_run

Feature interaction analysis:

python scripts/explainer.py \
  --model_path ./models/my_model.json \
  --data_path ./examples/toy.parquet \
  --target y_label \
  --interaction_features "age,income" \
  --output_dir ./outputs/explain_run

---

Common Scenarios

Scenario 1: Global feature importance analysis

Explain the model's overall decision logic:

python scripts/explainer.py --model_path ./models/my_model.json \
  --data_path ./examples/toy.parquet --target y_label \
  --output_dir ./outputs/explain_run

Output:

• SHAP Summary Plot (feature importance ranking)
• SHAP Bar Plot (mean absolute SHAP value)
• Feature importance table

Scenario 2: Single-sample prediction explanation

Explain the prediction reason for a specific sample:

python scripts/explainer.py --model_path ./models/my_model.json \
  --data_path ./examples/toy.parquet --target y_label \
  --sample_id 1001 --output_dir ./outputs/explain_run

Output:

• SHAP Force Plot (positive and negative features driving the prediction)
• Waterfall plot (feature contribution decomposition)
• Comparison of the sample's feature values with the distribution

Scenario 3: Feature interaction analysis

Analyze the interaction effect of two features:

python scripts/explainer.py --model_path ./models/my_model.json \
  --data_path ./examples/toy.parquet --target y_label \
  --interaction_features "age,income" --output_dir ./outputs/explain_run

Output:

• SHAP Dependence Plot (feature value vs SHAP value)
• Interaction heatmap

---

Cross-skill chaining (recommended workflow)

xgb-modeling The artifact's result.json in role=model path can be fed directly to model-explanation：

# 1) 训练
python ../xgb-modeling/scripts/modeling.py \
  --data_path ./examples/toy.parquet --target y_label \
  --exclude_cols "cust_code" --output_dir ./outputs/mdl

# 2) 从 result.json 提模型路径
MODEL=$(jq -r '.files[] | select(.role=="model") | .path' ./outputs/mdl/result.json)

# 3) 解释（特征自动从 <model>_meta.json 读取）
python scripts/explainer.py \
  --model_path "$MODEL" \
  --data_path ./examples/toy.parquet --target y_label \
  --output_dir ./outputs/xpl

---

Feature list source

1. --features "f1,f2,..." Explicitly passed in
2. config.json in "features": [...]
3. Auto-discovery <model>_meta.json(included with the xgb-modeling artifact)

---

Report Output Structure

The generated model_explanation_report.md contains the following sections:

Section	Content
1. Model Overview	Model path, number of features, sample size
2. Global Feature Explanation	SHAP Summary Plot, Top N feature importance table
3. Single-Sample Explanation	Force Plot, waterfall plot, feature value comparison (if a sample is specified)
4. Feature Interaction Analysis	Dependence Plot, interaction effect description (if specified)
5. Visualization Attachments	List of generated PNG chart files

---

Artifact directory

<output_dir>/
├── model_explanation_report.md
└── assets/
    ├── shap_summary.png
    ├── shap_bar.png
    ├── force_plot_sample_1001.png
    └── dependence_age_income.png

---

Relationship with Other Skills

Skill	Responsibilities	Relationships
xgb-modeling	Train Model	Prerequisite: Need to first train and save a model with it
model-comparison	Multi-algorithm Comparison	Follow-up: Can be compared and explained with LR/DNN models
feature-analysis	Feature Analysis	Difference: feature-analysis analyzes feature quality before modeling

---

Dependencies

• shap、matplotlib(Chart)
• xgboost、pandas、numpy

---

Notes

1. Model Format: Only supports XGBoost JSON format model files
2. Data Consistency：--data_path Must be consistent with the data fields used during training
3. Sample Location：--sample_id Is the integer index of the data frame, not the business ID
4. Memory Usage: Global SHAP computation on large datasets may take a long time
5. Chart Dependencies: Requires matplotlib and shap library support
6. base_score Compatibility: In XGBoost >= 1.7, the base_score is an array, and the script will automatically fix it to a scalar to be compatible with SHAP