@synsci/cli-darwin-x64-baseline 1.1.77 → 1.1.78

package/bin/skills/shap/references/explainers.md

@@ -0,0 +1,339 @@
+# SHAP Explainers Reference
+
+This document provides comprehensive information about all SHAP explainer classes, their parameters, methods, and when to use each type.
+
+## Overview
+
+SHAP provides specialized explainers for different model types, each optimized for specific architectures. The general `shap.Explainer` class automatically selects the appropriate algorithm based on the model type.
+
+## Core Explainer Classes
+
+### shap.Explainer (Auto-selector)
+
+**Purpose**: Automatically uses Shapley values to explain any machine learning model or Python function by selecting the most appropriate explainer algorithm.
+
+**Constructor Parameters**:
+- `model`: The model to explain (function or model object)
+- `masker`: Background data or masker object for feature manipulation
+- `algorithm`: Optional override to force specific explainer type
+- `output_names`: Names for model outputs
+- `feature_names`: Names for input features
+
+**When to Use**: Default choice when unsure which explainer to use; automatically selects the best algorithm based on model type.
+
+### TreeExplainer
+
+**Purpose**: Fast and exact SHAP value computation for tree-based ensemble models using the Tree SHAP algorithm.
+
+**Constructor Parameters**:
+- `model`: Tree-based model (XGBoost, LightGBM, CatBoost, PySpark, or scikit-learn trees)
+- `data`: Background dataset for feature integration (optional with tree_path_dependent)
+- `feature_perturbation`: How to handle dependent features
+  - `"interventional"`: Requires background data; follows causal inference rules
+  - `"tree_path_dependent"`: No background data needed; uses training examples per leaf
+  - `"auto"`: Defaults to interventional if data provided, otherwise tree_path_dependent
+- `model_output`: What model output to explain
+  - `"raw"`: Standard model output (default)
+  - `"probability"`: Probability-transformed output
+  - `"log_loss"`: Natural log of loss function
+  - Custom method names like `"predict_proba"`
+- `feature_names`: Optional feature naming
+
+**Supported Models**:
+- XGBoost (xgboost.XGBClassifier, xgboost.XGBRegressor, xgboost.Booster)
+- LightGBM (lightgbm.LGBMClassifier, lightgbm.LGBMRegressor, lightgbm.Booster)
+- CatBoost (catboost.CatBoostClassifier, catboost.CatBoostRegressor)
+- PySpark MLlib tree models
+- scikit-learn (DecisionTreeClassifier, DecisionTreeRegressor, RandomForestClassifier, RandomForestRegressor, ExtraTreesClassifier, ExtraTreesRegressor, GradientBoostingClassifier, GradientBoostingRegressor)
+
+**Key Methods**:
+- `shap_values(X)`: Computes SHAP values for samples; returns arrays where each row represents feature attribution
+- `shap_interaction_values(X)`: Estimates interaction effects between feature pairs; provides matrices with main effects and pairwise interactions
+- `explain_row(row)`: Explains individual rows with detailed attribution information
+
+**When to Use**:
+- Primary choice for all tree-based models
+- When exact SHAP values are needed (not approximations)
+- When computational speed is important for large datasets
+- For models like random forests, gradient boosting, or XGBoost
+
+**Example**:
+```python
+import shap
+import xgboost
+
+# Train model
+model = xgboost.XGBClassifier().fit(X_train, y_train)
+
+# Create explainer
+explainer = shap.TreeExplainer(model)
+
+# Compute SHAP values
+shap_values = explainer.shap_values(X_test)
+
+# Compute interaction values
+shap_interaction = explainer.shap_interaction_values(X_test)
+```
+
+### DeepExplainer
+
+**Purpose**: Approximates SHAP values for deep learning models using an enhanced version of the DeepLIFT algorithm.
+
+**Constructor Parameters**:
+- `model`: Framework-dependent specification
+  - **TensorFlow**: Tuple of (input_tensor, output_tensor) where output is single-dimensional
+  - **PyTorch**: `nn.Module` object or tuple of `(model, layer)` for layer-specific explanations
+- `data`: Background dataset for feature integration
+  - **TensorFlow**: numpy arrays or pandas DataFrames
+  - **PyTorch**: torch tensors
+  - **Recommended size**: 100-1000 samples (not full training set) to balance accuracy and computational cost
+- `session` (TensorFlow only): Optional session object; auto-detected if None
+- `learning_phase_flags`: Custom learning phase tensors for handling batch norm/dropout during inference
+
+**Supported Frameworks**:
+- **TensorFlow**: Full support including Keras models
+- **PyTorch**: Complete integration with nn.Module architecture
+
+**Key Methods**:
+- `shap_values(X)`: Returns approximate SHAP values for the model applied to data X
+- `explain_row(row)`: Explains single rows with attribution values and expected outputs
+- `save(file)` / `load(file)`: Serialization support for explainer objects
+- `supports_model_with_masker(model, masker)`: Compatibility checker for model types
+
+**When to Use**:
+- For deep neural networks in TensorFlow or PyTorch
+- When working with convolutional neural networks (CNNs)
+- For recurrent neural networks (RNNs) and transformers
+- When model-specific explanation is needed for deep learning architectures
+
+**Key Design Feature**:
+Variance of expectation estimates scales approximately as 1/√N, where N is the number of background samples, enabling accuracy-efficiency trade-offs.
+
+**Example**:
+```python
+import shap
+import tensorflow as tf
+
+# Assume model is a Keras model
+model = tf.keras.models.load_model('my_model.h5')
+
+# Select background samples (subset of training data)
+background = X_train[:100]
+
+# Create explainer
+explainer = shap.DeepExplainer(model, background)
+
+# Compute SHAP values
+shap_values = explainer.shap_values(X_test[:10])
+```
+
+### KernelExplainer
+
+**Purpose**: Model-agnostic SHAP value computation using the Kernel SHAP method with weighted linear regression.
+
+**Constructor Parameters**:
+- `model`: Function or model object that takes a matrix of samples and returns model outputs
+- `data`: Background dataset (numpy array, pandas DataFrame, or sparse matrix) used to simulate missing features
+- `feature_names`: Optional list of feature names; automatically derived from DataFrame column names if available
+- `link`: Connection function between feature importance and model output
+  - `"identity"`: Direct relationship (default)
+  - `"logit"`: For probability outputs
+
+**Key Methods**:
+- `shap_values(X, **kwargs)`: Calculates SHAP values for sample predictions
+  - `nsamples`: Evaluation count per prediction ("auto" or integer); higher values reduce variance
+  - `l1_reg`: Feature selection regularization ("num_features(int)", "aic", "bic", or float)
+  - Returns arrays where each row sums to the difference between model output and expected value
+- `explain_row(row)`: Explains individual predictions with attribution values and expected values
+- `save(file)` / `load(file)`: Persist and restore explainer objects
+
+**When to Use**:
+- For black-box models where specialized explainers aren't available
+- When working with custom prediction functions
+- For any model type (neural networks, SVMs, ensemble methods, etc.)
+- When model-agnostic explanations are needed
+- **Note**: Slower than specialized explainers; use only when no specialized option exists
+
+**Example**:
+```python
+import shap
+from sklearn.svm import SVC
+
+# Train model
+model = SVC(probability=True).fit(X_train, y_train)
+
+# Create prediction function
+predict_fn = lambda x: model.predict_proba(x)[:, 1]
+
+# Select background samples
+background = shap.sample(X_train, 100)
+
+# Create explainer
+explainer = shap.KernelExplainer(predict_fn, background)
+
+# Compute SHAP values (may be slow)
+shap_values = explainer.shap_values(X_test[:10])
+```
+
+### LinearExplainer
+
+**Purpose**: Specialized explainer for linear models that accounts for feature correlations.
+
+**Constructor Parameters**:
+- `model`: Linear model or tuple of (coefficients, intercept)
+- `masker`: Background data for feature correlation
+- `feature_perturbation`: How to handle feature correlations
+  - `"interventional"`: Assumes feature independence
+  - `"correlation_dependent"`: Accounts for feature correlations
+
+**Supported Models**:
+- scikit-learn linear models (LinearRegression, LogisticRegression, Ridge, Lasso, ElasticNet)
+- Custom linear models with coefficients and intercept
+
+**When to Use**:
+- For linear regression and logistic regression models
+- When feature correlations are important to explanation accuracy
+- When extremely fast explanations are needed
+- For GLMs and other linear model types
+
+**Example**:
+```python
+import shap
+from sklearn.linear_model import LogisticRegression
+
+# Train model
+model = LogisticRegression().fit(X_train, y_train)
+
+# Create explainer
+explainer = shap.LinearExplainer(model, X_train)
+
+# Compute SHAP values
+shap_values = explainer.shap_values(X_test)
+```
+
+### GradientExplainer
+
+**Purpose**: Uses expected gradients to approximate SHAP values for neural networks.
+
+**Constructor Parameters**:
+- `model`: Deep learning model (TensorFlow or PyTorch)
+- `data`: Background samples for integration
+- `batch_size`: Batch size for gradient computation
+- `local_smoothing`: Amount of noise to add for smoothing (default 0)
+
+**When to Use**:
+- As an alternative to DeepExplainer for neural networks
+- When gradient-based explanations are preferred
+- For differentiable models where gradient information is available
+
+**Example**:
+```python
+import shap
+import torch
+
+# Assume model is a PyTorch model
+model = torch.load('model.pt')
+
+# Select background samples
+background = X_train[:100]
+
+# Create explainer
+explainer = shap.GradientExplainer(model, background)
+
+# Compute SHAP values
+shap_values = explainer.shap_values(X_test[:10])
+```
+
+### PermutationExplainer
+
+**Purpose**: Approximates Shapley values by iterating through permutations of inputs.
+
+**Constructor Parameters**:
+- `model`: Prediction function
+- `masker`: Background data or masker object
+- `max_evals`: Maximum number of model evaluations per sample
+
+**When to Use**:
+- When exact Shapley values are needed but specialized explainers aren't available
+- For small feature sets where permutation is tractable
+- As a more accurate alternative to KernelExplainer (but slower)
+
+**Example**:
+```python
+import shap
+
+# Create explainer
+explainer = shap.PermutationExplainer(model.predict, X_train)
+
+# Compute SHAP values
+shap_values = explainer.shap_values(X_test[:10])
+```
+
+## Explainer Selection Guide
+
+**Decision Tree for Choosing an Explainer**:
+
+1. **Is your model tree-based?** (XGBoost, LightGBM, CatBoost, Random Forest, etc.)
+   - Yes → Use `TreeExplainer` (fast and exact)
+   - No → Continue to step 2
+
+2. **Is your model a deep neural network?** (TensorFlow, PyTorch, Keras)
+   - Yes → Use `DeepExplainer` or `GradientExplainer`
+   - No → Continue to step 3
+
+3. **Is your model linear?** (Linear/Logistic Regression, GLMs)
+   - Yes → Use `LinearExplainer` (extremely fast)
+   - No → Continue to step 4
+
+4. **Do you need model-agnostic explanations?**
+   - Yes → Use `KernelExplainer` (slower but works with any model)
+   - If computational budget allows and high accuracy is needed → Use `PermutationExplainer`
+
+5. **Unsure or want automatic selection?**
+   - Use `shap.Explainer` (auto-selects best algorithm)
+
+## Common Parameters Across Explainers
+
+**Background Data / Masker**:
+- Purpose: Represents the "typical" input to establish baseline expectations
+- Size recommendations: 50-1000 samples (more for complex models)
+- Selection: Random sample from training data or kmeans-selected representatives
+
+**Feature Names**:
+- Automatically extracted from pandas DataFrames
+- Can be manually specified for numpy arrays
+- Important for plot interpretability
+
+**Model Output Specification**:
+- Raw model output vs. transformed output (probabilities, log-odds)
+- Critical for correct interpretation of SHAP values
+- Example: For XGBoost classifiers, SHAP explains margin output (log-odds) before logistic transformation
+
+## Performance Considerations
+
+**Speed Ranking** (fastest to slowest):
+1. `LinearExplainer` - Nearly instantaneous
+2. `TreeExplainer` - Very fast, scales well
+3. `DeepExplainer` - Fast for neural networks
+4. `GradientExplainer` - Fast for neural networks
+5. `KernelExplainer` - Slow, use only when necessary
+6. `PermutationExplainer` - Very slow but most accurate for small feature sets
+
+**Memory Considerations**:
+- `TreeExplainer`: Low memory overhead
+- `DeepExplainer`: Memory proportional to background sample size
+- `KernelExplainer`: Can be memory-intensive for large background datasets
+- For large datasets: Use batching or sample subsets
+
+## Explainer Output: The Explanation Object
+
+All explainers return `shap.Explanation` objects containing:
+- `values`: SHAP values (numpy array)
+- `base_values`: Expected model output (baseline)
+- `data`: Original feature values
+- `feature_names`: Names of features
+
+The Explanation object supports:
+- Slicing: `explanation[0]` for first sample
+- Array operations: Compatible with numpy operations
+- Direct plotting: Can be passed to plot functions