webshap/dist/explainer/kernel.d.ts

Explain any ML models anywhere

/**
 * Kernel SHAP
 * @author: Jay Wang (jay@zijie.wang)
 */
import math from '../utils/math-import';
import type { RandomUniform, RandomInt } from 'd3-random';
/**
 * Kernel SHAP method to approximate Shapley attributions by solving s specially
 * weighted linear regression problem.
 */
export declare class KernelSHAP {
    /** Prediction model */
    model: (x: number[][]) => Promise<number[][]>;
    /** Background data */
    data: number[][];
    /** Whether this.init() has finished running */
    initialized: boolean;
    /**
     * Expected prediction value
     * [nTargets]
     */
    expectedValue: number[];
    /**
     * Model's prediction on the background ata
     * [nData, nTargets]
     */
    predictions: number[][];
    /** Number of features */
    nFeatures: number;
    /** Dimension of the prediction output */
    nTargets: number;
    /** Number of coalition samples added */
    nSamplesAdded: number;
    /**
     * Column indexes that the explaining x has different column value from at
     * least ont instance in the background data.
     */
    varyingIndexes: number[] | null;
    nVaryFeatures: number | null;
    /**
     * Sampled data in a matrix form.
     * It is initialized after the explain() call.
     * [nSamples * nBackground, nFeatures]
     */
    sampledData: math.Matrix | null;
    /**
     * Matrix to store the feature masks
     * [nSamples, nVaryFeatures]
     */
    maskMat: math.Matrix | null;
    /**
     * Kernel weights for each coalition sample
     * [nSamples, 1]
     */
    kernelWeight: math.Matrix | null;
    /**
     * Model prediction outputs on the sampled data
     * [nSamples * nBackground, nTargets]
     */
    yMat: math.Matrix | null;
    /**
     * Expected model predictions on the sample data
     * [nSamples, nTargets]
     */
    yExpMat: math.Matrix | null;
    /**
     * Mask used in the last run
     * [nSamples]
     */
    lastMask: math.Matrix | null;
    /** Random seed */
    lcg: () => number;
    /** Uniform random number generator*/
    rng: RandomUniform;
    /** Uniform random integer generator */
    rngInt: RandomInt;
    /**
     * Initialize a new KernelSHAP explainer.
     * @param model The trained model to explain
     * @param data The background data
     * @param seed Optional random seed in the range [0, 1)
     */
    constructor(model: (x: number[][]) => Promise<number[][]>, data: number[][], seed: number | null);
    /**
     * Initialize the model predictions on the background data
     */
    initializeModel: () => Promise<void>;
    /**
     * Estimate SHAP values of the given sample x
     * @param x One data sample
     * @param nSamples Number of coalitions to samples (default to null which uses
     * a heuristic to determine a large sample size)
     */
    explainOneInstance: (x: number[], nSamples?: number | null) => Promise<number[][]>;
    /**
     * Compute shap values on one target class
     * @param fractionEvaluated Fraction of sampled coalitions out of all
     * combinations
     * @param yPredProbMat Model prediction output matrix [1, nTargets]
     * @param target Current target class (a column in yPredProbMat)
     * @returns Shap values [nFeatures]
     */
    computeShap: (fractionEvaluated: number, yPredProbMat: math.Matrix, target: number) => number[];
    /**
     * Find varying indexes (if x has columns that are the same for every
     * background instances, then the shap value is 0 for those columns)
     * @param x Explaining instance x
     */
    getVaryingIndexes: (x: number[]) => number[];
    /**
     * Run the ML model on all sampled feature coalitions
     */
    inferenceFeatureCoalitions: () => Promise<void>;
    /**
     * Enumerate/sample feature coalitions to approximate the shapley values
     * @param x Instance to explain
     * @param nSamples Number of coalitions to sample
     * @returns Sample rate (fraction of sampled feature coalitions)
     */
    sampleFeatureCoalitions: (x: number[], nSamples: number | null) => number;
    addSample(x: number[], mask: number[], weight: number): void;
    /**
     * Initialize data structures to prepare for the feature coalition sampling
     * @param nSamples Number of coalitions to sample
     */
    prepareSampling: (nSamples: number) => void;
    /**
     * Helper function to convert a mask array into a string
     * @param mask Binary mask array
     * @returns String version of the binary mask array
     */
    static getMaskStr: (mask: number[]) => string;
}