InterpretableModelHelper

Helpers & Utilities · AiDotNet.Interpretability

Provides static helper methods for model interpretability operations using production-ready explainer algorithms.

For Beginners

This class serves as a facade that connects interpretable models to the actual explainer implementations (SHAP, LIME, PDP, Integrated Gradients, DeepLIFT, GradCAM, etc.). It handles the conversion between model interfaces and the prediction functions that explainers need.

How It Works

IMPORTANT: These methods delegate to production-ready explainer classes:

  • SHAPExplainer: Kernel SHAP for model-agnostic Shapley value explanations
  • LIMEExplainer: Local interpretable model-agnostic explanations
  • PartialDependenceExplainer: PDP and ICE curves
  • FeatureInteractionExplainer: Friedman’s H-statistic
  • IntegratedGradientsExplainer: Neural network attribution (requires gradient access)
  • DeepLIFTExplainer: Fast neural network attribution
  • GradCAMExplainer: Visual CNN explanations
  • PermutationFeatureImportance: Model-agnostic global importance

CRITICAL: Methods that require background data will throw if no data is provided. Synthetic background data is only used as a last resort and will emit warnings.

Methods

Method Summary
Task<AnchorExplanation<T>> GetAnchorExplanationAsync(IInterpretableModel<T> model, HashSet<InterpretationMethod> enabledMethods, Tensor<T> input, T threshold) Gets anchor explanation for a given input using beam search to find sufficient conditions (rules) that anchor the prediction.
Task<CounterfactualExplanation<T>> GetCounterfactualAsync(IInterpretableModel<T> model, HashSet<InterpretationMethod> enabledMethods, Tensor<T> input, Tensor<T> desiredOutput, int maxChanges) Gets counterfactual explanation for a given input and desired output.
Task<DeepLIFTExplanation<T>> GetDeepLIFTAsync(IInterpretableModel<T> model, HashSet<InterpretationMethod> enabledMethods, Tensor<T> input, Tensor<T> baseline, DeepLIFTRule rule) Gets DeepLIFT attributions for neural network explanation.
Task<DeepLIFTExplanation<T>> GetDeepLIFTWithBackpropAsync(INeuralNetwork<T> neuralNetwork, HashSet<InterpretationMethod> enabledMethods, Tensor<T> input, Tensor<T> baseline, DeepLIFTRule rule, string[] featureNames) Gets DeepLIFT attributions using efficient backpropagation for a neural network.
Task<Dictionary<int, T>> GetGlobalFeatureImportanceAsync(IInterpretableModel<T> model, HashSet<InterpretationMethod> enabledMethods) Gets the global feature importance (simplified overload for backwards compatibility).
Task<Dictionary<int, T>> GetGlobalFeatureImportanceAsync(IInterpretableModel<T> model, HashSet<InterpretationMethod> enabledMethods, Matrix<T> data, Vector<T> labels, int nRepeats) Gets the global feature importance using permutation feature importance.
Task<Dictionary<int, T>> GetLocalFeatureImportanceAsync(IInterpretableModel<T> model, HashSet<InterpretationMethod> enabledMethods, Tensor<T> input) Gets the local feature importance for a specific input using gradient-based attribution.
Task<Dictionary<string, object>> GetModelSpecificInterpretabilityAsync(IInterpretableModel<T> model) Gets model-specific interpretability information.
Task<FairnessMetrics<T>> ValidateFairnessAsync(IInterpretableModel<T> model, Tensor<T> inputs, Vector<T> groundTruthLabels, int sensitiveFeatureIndex, List<FairnessMetric> fairnessMetrics) Validates fairness metrics for the given inputs with ground truth labels.
Task<FairnessMetrics<T>> ValidateFairnessAsync(IInterpretableModel<T> model, Tensor<T> inputs, int sensitiveFeatureIndex, List<FairnessMetric> fairnessMetrics) Validates fairness metrics without ground truth (uses approximations).
Task<FairnessMetrics<T>> ValidateFairnessAsync(List<FairnessMetric> fairnessMetrics) Legacy overload without input data.
Task<GradCAMExplanation<T>> GetGradCAMAsync(IInterpretableModel<T> model, HashSet<InterpretationMethod> enabledMethods, Tensor<T> input, int[] inputShape, int[] featureMapShape, int targetClass, Func<Tensor<T>, int, Tensor<T>> featureMapFunction, Func<Tensor<T>, int, int, Tensor<T>> gradientFunction, bool useGradCAMPlusPlus) Gets Grad-CAM visual explanation for a CNN prediction.
Task<IntegratedGradientsExplanation<T>> GetIntegratedGradientsAsync(IInterpretableModel<T> model, HashSet<InterpretationMethod> enabledMethods, Tensor<T> input, Tensor<T> baseline, int numSteps, Func<Vector<T>, int, Vector<T>> gradientFunction) Gets Integrated Gradients attributions for neural network explanation.
Task<IntegratedGradientsExplanation<T>> GetIntegratedGradientsWithBackpropAsync(INeuralNetwork<T> neuralNetwork, HashSet<InterpretationMethod> enabledMethods, Tensor<T> input, Tensor<T> baseline, int numSteps, string[] featureNames) Gets Integrated Gradients attributions using efficient backpropagation for a neural network.
Task<LimeExplanation<T>> GetLimeExplanationAsync(IInterpretableModel<T> model, HashSet<InterpretationMethod> enabledMethods, Tensor<T> input, int numFeatures, int nSamples, double kernelWidth) Gets LIME explanation for a specific input using local linear approximation.
Task<Matrix<T>> GetShapValuesAsync(IInterpretableModel<T> model, HashSet<InterpretationMethod> enabledMethods, Tensor<T> inputs) Gets SHAP values (backwards compatible overload that uses input as background).
Task<Matrix<T>> GetShapValuesAsync(IInterpretableModel<T> model, HashSet<InterpretationMethod> enabledMethods, Tensor<T> inputs, Matrix<T> backgroundData, int nSamples) Gets SHAP values for the given inputs using Kernel SHAP algorithm.
Task<PartialDependenceData<T>> GetPartialDependenceAsync(IInterpretableModel<T> model, HashSet<InterpretationMethod> enabledMethods, Vector<int> featureIndices, Matrix<T> backgroundData, int gridResolution, bool computeIce) Gets partial dependence data for specified features.
Task<PartialDependenceData<T>> GetPartialDependenceAsync(IInterpretableModel<T> model, HashSet<InterpretationMethod> enabledMethods, Vector<int> featureIndices, int gridResolution) Gets partial dependence data (backwards compatible overload with synthetic data fallback).
Task<T> GetFeatureInteractionAsync(HashSet<InterpretationMethod> enabledMethods, int feature1Index, int feature2Index) Legacy overload without model parameter.
Task<T> GetFeatureInteractionAsync(IInterpretableModel<T> model, HashSet<InterpretationMethod> enabledMethods, int feature1Index, int feature2Index) Gets feature interaction (backwards compatible overload).
Task<T> GetFeatureInteractionAsync(IInterpretableModel<T> model, HashSet<InterpretationMethod> enabledMethods, int feature1Index, int feature2Index, Matrix<T> backgroundData, int gridSize) Gets feature interaction effects between two features using Friedman’s H-statistic.
Task<TreeSHAPExplanation<T>> GetTreeSHAPAsync(DecisionTreeNode<T> tree, HashSet<InterpretationMethod> enabledMethods, Tensor<T> input, T expectedValue, string[] featureNames) Gets TreeSHAP values for an ensemble of trees (Random Forest, Gradient Boosting).
Task<TreeSHAPExplanation<T>> GetTreeSHAPAsync(IEnumerable<DecisionTreeNode<T>> trees, HashSet<InterpretationMethod> enabledMethods, Tensor<T> input, T expectedValue, string[] featureNames) Gets TreeSHAP values for an ensemble of trees (Random Forest, Gradient Boosting).
Task<string> GenerateTextExplanationAsync(IInterpretableModel<T> model, Tensor<T> input, Tensor<T> prediction) Generates a text explanation for a prediction.