facet.inspection.base.ModelInspector#

class facet.inspection.base.ModelInspector(model, *, shap_interaction=True, n_jobs=None, shared_memory=None, pre_dispatch=None, verbose=None)[source]#

Explain a model based on SHAP values.

Note

This is an abstract base class for inspectors explaining different kinds of models based on SHAP values.

Focus is on explaining the overall model, but the inspector also delivers SHAP explanations of the individual observations.

Available inspection methods are:

SHAP values
SHAP interaction values
feature importance derived from SHAP values (either as mean absolute values or as the root of mean squares)
pairwise feature redundancy matrix (requires availability of SHAP interaction values)
pairwise feature synergy matrix (requires availability of SHAP interaction values)
pairwise feature association matrix (upper bound for redundancy but can be inflated by synergy; available if SHAP interaction values are unknown)
pairwise feature interaction matrix (direct feature interaction quantified by SHAP interaction values)
feature redundancy linkage (to visualize clusters of redundant features in a dendrogram; requires availability of SHAP interaction values)
feature synergy linkage (to visualize clusters of synergistic features in a dendrogram; requires availability of SHAP interaction values)
feature association linkage (to visualize clusters of associated features in a dendrogram)

All inspections that aggregate across observations will respect sample weights, if specified in the underlying training sample.

Bases

FittableMixin [Sample], ParallelizableMixin

Generic types

~T_Model

Metaclasses

ABCMeta

Parameters

model (ModelInspector) – the model to inspect
shap_interaction (bool) – if True, calculate SHAP interaction values, else only calculate SHAP contribution values; SHAP interaction values are needed to determine feature synergy and redundancy (default: True)
n_jobs (Optional[int]) – number of jobs to use in parallel; if None, use joblib default (default: None)
shared_memory (Optional[bool]) – if True, use threads in the parallel runs; if False or None, use multiprocessing (default: None)
pre_dispatch (Union[int, str, None]) – number of batches to pre-dispatch; if None, use joblib default (default: None)
verbose (Optional[int]) – verbosity level used in the parallel computation; if None, use joblib default (default: None)

Method summary

`feature_association_linkage`	Calculate a linkage tree based on the `feature_association_matrix()`.
`feature_association_matrix`	Calculate the feature association matrix.
`feature_importance`	Calculate the relative importance of each feature based on SHAP values.
`feature_interaction_matrix`	Calculate relative shap interaction values for all feature pairings.
`feature_redundancy_linkage`	Calculate a linkage tree based on the `feature_redundancy_matrix()`.
`feature_redundancy_matrix`	Calculate the feature redundancy matrix.
`feature_synergy_linkage`	Calculate a linkage tree based on the `feature_synergy_matrix()`.
`feature_synergy_matrix`	Calculate the feature synergy matrix.
`fit`	Fit the inspector with the given sample, creating global explanations including feature redundancy and synergy.
`preprocess_features`	Preprocess the features prior to calculating SHAP values.
`shap_interaction_values`	Calculate the SHAP interaction values for all observations and pairs of features.
`shap_plot_data`	Consolidate SHAP values and corresponding feature values from this inspector for use in SHAP plots offered by the shap package.
`shap_values`	Calculate the SHAP values for all observations and features.

Attribute summary

`COL_IMPORTANCE`	Name for feature importance series or column.
`feature_names`	The feature names of the model being inspected.
`is_fitted`	[see superclass]
`output_names`	The names of the outputs explained by this inspector.
`sample_`	The background sample used to fit this inspector.
`shap_calculator`	The SHAP calculator used by this inspector.
`n_jobs`	Number of jobs to use in parallel; if `None`, use joblib default.
`shared_memory`	If `True`, use threads in the parallel runs; if `False` or `None`, use multiprocessing.
`pre_dispatch`	Number of batches to pre-dispatch; if `None`, use joblib default.
`verbose`	Verbosity level used in the parallel computation; if `None`, use joblib default.
`model`	The model to inspect.
`shap_interaction`	If `True`, calculate SHAP interaction values, else only calculate SHAP contribution values.

Definitions

feature_association_linkage()[source]#

Calculate a linkage tree based on the feature_association_matrix().

The linkage tree can be used to render a dendrogram indicating clusters of associated features.

In the case of multi-target regression and non-binary classification, returns a list of linkage trees per target or class.

Return type: Union[LinkageTree, List[LinkageTree]]
Returns: linkage tree of feature associations; list of linkage trees for multi-target regressors or non-binary classifiers

feature_association_matrix(*, absolute=False, symmetrical=False, clustered=True)[source]#

Calculate the feature association matrix.

This yields an asymmetric matrix where each row and column represents one feature, and the values at the intersections are the pairwise feature associations, ranging from 0.0 (no association) to 1.0 (full association).

The association of a feature with itself is defined as 1.0.

Feature association provides an upper bound for feature redundancy but might be inflated by feature synergy.

While it is preferable to assess redundancy and synergy separately, association can be calculated using only SHAP values, and thus can be used as a fallback if no SHAP interaction values are available.

In the case of multi-target regression and non-binary classification, returns a list of data frames with one matrix per output.

Parameters

absolute (bool) – if False, return relative association as a percentage of total feature importance; if True, return absolute association as a portion of feature importance
symmetrical (bool) – if False, return an asymmetrical matrix quantifying unilateral association of the features represented by rows with the features represented by columns; if True, return a symmetrical matrix quantifying mutual association (default: False)
clustered (bool) – if True, reorder the rows and columns of the matrix such that association between adjacent rows and columns is maximised; if False, keep rows and columns in the original features order (default: True)

Return type

Union[Matrix[float64], List[Matrix[float64]]]

Returns

feature association matrix as a data frame of shape (n_features, n_features), or a list of data frames for multiple outputs

feature_importance(*, method='rms')[source]#

Calculate the relative importance of each feature based on SHAP values.

The importance values of all features always add up to 1.0.

The calculation applies sample weights if specified in the underlying Sample.

Parameters: method (str) – method for calculating feature importance. Supported methods are rms (root of mean squares, default), mav (mean absolute values)
Return type: Union[Series, DataFrame]
Returns: a series of length n_features for single-output models, or a data frame of shape (n_features, n_outputs) for multi-output models

feature_interaction_matrix()[source]#

Calculate relative shap interaction values for all feature pairings.

Shap interactions quantify direct interactions between pairs of features. For a quantification of overall interaction (including indirect interactions across more than two features), see feature_synergy_matrix().

The relative values are normalised to add up to 1.0, and each value ranges between 0.0 and 1.0.

For features \(f_i\) and \(f_j\), relative feature interaction \(I\) is calculated as

\[I_{ij} = \frac {\sigma(\vec{\phi}_{ij})} {\sum_{a=1}^n \sum_{b=1}^n \sigma(\vec{\phi}_{ab})}\]

where \(\sigma(\vec v)\) is the standard deviation of all elements of vector \(\vec v\).

The total average interaction of features \(f_i\) and \(f_j\) is \(I_{ij} + I_{ji} = 2 I_{ij}\).

\(I_{ii}\) is the residual, non-synergistic contribution of feature \(f_i\)

The matrix returned by this method is a lower-triangular matrix

\[\begin{split}\newcommand\nan{\mathit{nan}} I_{} = \begin{pmatrix} I_{11} & \nan & \nan & \dots & \nan \\ 2I_{21} & I_{22} & \nan & \dots & \nan \\ 2I_{31} & 2I_{32} & I_{33} & \dots & \nan \\ \vdots & \vdots & \vdots & \ddots & \vdots \\ 2I_{n1} & 2I_{n2} & 2I_{n3} & \dots & I_{nn} \\ \end{pmatrix}\end{split}\]

with \(\sum_{a=1}^n \sum_{b=a}^n I_{ab} = 1\)

In the case of multi-target regression and non-binary classification, returns a list with one matrix per output.

Return type: Union[Matrix[float64], List[Matrix[float64]]]
Returns: relative shap interaction values as a data frame of shape (n_features, n_features); or a list of such data frames

feature_redundancy_linkage()[source]#

Calculate a linkage tree based on the feature_redundancy_matrix().

The linkage tree can be used to render a dendrogram indicating clusters of redundant features.

In the case of multi-target regression and non-binary classification, returns a list of linkage trees per target or class.

Return type: Union[LinkageTree, List[LinkageTree]]
Returns: linkage tree of feature redundancies; list of linkage trees for multi-target regressors or non-binary classifiers

feature_redundancy_matrix(*, absolute=False, symmetrical=False, clustered=True)[source]#

Calculate the feature redundancy matrix.

This yields an asymmetric matrix where each row and column represents one feature, and the values at the intersections are the pairwise feature redundancies, ranging from 0.0 (no redundancy - both features contribute to predictions fully independently of each other) to 1.0 (full redundancy, either feature can replace the other feature without loss of predictive power).

The redundancy of a feature with itself is defined as 1.0.

Feature redundancy calculations require SHAP interaction values; if only SHAP values are available consider calculating feature associations instead (see feature_association_matrix()).

In the case of multi-target regression and non-binary classification, returns a list of data frames with one matrix per output.

Parameters

absolute (bool) – if False, return relative redundancy as a percentage of total feature importance; if True, return absolute redundancy as a portion of feature importance
symmetrical (bool) – if True, return a symmetrical matrix quantifying mutual redundancy; if False, return an asymmetrical matrix quantifying unilateral redundancy of the features represented by rows with the features represented by columns (default: False)
clustered (bool) – if True, reorder the rows and columns of the matrix such that redundancy between adjacent rows and columns is maximised; if False, keep rows and columns in the original features order (default: True)

Return type

Union[Matrix[float64], List[Matrix[float64]]]

Returns

feature redundancy matrix as a data frame of shape (n_features, n_features), or a list of data frames for multiple outputs

feature_synergy_linkage()[source]#

Calculate a linkage tree based on the feature_synergy_matrix().

The linkage tree can be used to render a dendrogram indicating clusters of synergistic features.

In the case of multi-target regression and non-binary classification, returns a list of linkage trees per target or class.

Return type: Union[LinkageTree, List[LinkageTree]]
Returns: linkage tree of feature synergies; list of linkage trees for multi-target regressors or non-binary classifiers

feature_synergy_matrix(*, absolute=False, symmetrical=False, clustered=True)[source]#

Calculate the feature synergy matrix.

This yields an asymmetric matrix where each row and column represents one feature, and the values at the intersections are the pairwise feature synergies, ranging from 0.0 (no synergy - both features contribute to predictions fully autonomously of each other) to 1.0 (full synergy, both features rely on combining all of their information to achieve any contribution to predictions).

The synergy of a feature with itself is defined as 1.0.

Feature synergy calculations require SHAP interaction values; if only SHAP values are available consider calculating feature associations instead (see feature_association_matrix()).

In the case of multi-target regression and non-binary classification, returns a list of data frames with one matrix per output.

Parameters

absolute (bool) – if False, return relative synergy as a percentage of total feature importance; if True, return absolute synergy as a portion of feature importance
symmetrical (bool) – if True, return a symmetrical matrix quantifying mutual synergy; if False, return an asymmetrical matrix quantifying unilateral synergy of the features represented by rows with the features represented by columns (default: False)
clustered (bool) – if True, reorder the rows and columns of the matrix such that synergy between adjacent rows and columns is maximised; if False, keep rows and columns in the original features order (default: True)

Return type

Union[Matrix[float64], List[Matrix[float64]]]

Returns

feature synergy matrix as a data frame of shape (n_features, n_features), or a list of data frames for multiple outputs

fit(__sample, **fit_params)[source]#

Fit the inspector with the given sample, creating global explanations including feature redundancy and synergy.

This will calculate SHAP values and, if enabled in the underlying SHAP explainer, also SHAP interaction values.

Parameters

__sample (Sample) – the background sample to be used for the global explanation of this model
fit_params (Any) – additional keyword arguments (ignored; accepted for compatibility with FittableMixin)

Return type

ModelInspector

Returns

self

preprocess_features(features)[source]#

Preprocess the features prior to calculating SHAP values.

This method is called by fit() before fitting the inspector. By default, returns the features unchanged.

Parameters: features (Union[DataFrame, Series]) – features to preprocess
Return type: DataFrame
Returns: preprocessed features

shap_interaction_values()[source]#

Calculate the SHAP interaction values for all observations and pairs of features.

Returns a data frame of SHAP interaction values where each row corresponds to an observation and a feature (identified by a hierarchical index with two levels), and each column corresponds to a feature.

Return type: Union[DataFrame, List[DataFrame]]
Returns: a data frame with SHAP interaction values

shap_plot_data()[source]#

Consolidate SHAP values and corresponding feature values from this inspector for use in SHAP plots offered by the shap package.

The shap package provides functions for creating various SHAP plots. Most of these functions require:

one or more SHAP value matrices as a single numpy array, or a list of numpy arrays of shape (n_observations, n_features)
a feature matrix of shape (n_observations, n_features), which can be provided as a data frame to preserve feature names

This method provides this data inside a ShapPlotData object, plus:

the names of all outputs (i.e., the target names in case of regression, or the class names in case of classification)
corresponding target values as a series, or as a data frame in the case of multiple targets

This method also ensures that the rows of all arrays, frames, and series are aligned, even if only a subset of the observations in the original sample was used to calculate SHAP values.

Calculates mean shap values for each observation and feature, across all splits for which SHAP values were calculated.

Return type: ShapPlotData
Returns: consolidated SHAP and feature values for use shap plots

shap_values()[source]#

Calculate the SHAP values for all observations and features.

Returns a data frame of SHAP values where each row corresponds to an observation, and each column corresponds to a feature.

Return type: Union[DataFrame, List[DataFrame]]
Returns: a data frame with SHAP values

COL_IMPORTANCE = 'importance'#: Name for feature importance series or column.

abstract property feature_names: List[str]#

The feature names of the model being inspected.

These names may differ from the feature names expected for the sample set has been preprocessed before calculating SHAP values.

Return type: List[str]
Returns: the feature names

property is_fitted: bool#

[see superclass]

Return type: bool

model: T_Model#: The model to inspect.

property output_names: List[str]#

The names of the outputs explained by this inspector.

For regressors, these are the names of the target columns.

For binary classifiers, this is a list of length 1 with the name of a single class, since the SHAP values of the second class can be trivially derived as the negation of the SHAP values of the first class.

For non-binary classifiers, this is the list of all classes.

Return type: List[str]

property sample_: facet.data.Sample#

The background sample used to fit this inspector.

Return type: Sample

abstract property shap_calculator: facet.inspection.shap.ShapCalculator[Any]#

The SHAP calculator used by this inspector.

Return type: ShapCalculator[Any]

shap_interaction: bool#: If True, calculate SHAP interaction values, else only calculate SHAP contribution values. SHAP interaction values are needed to determine feature synergy and redundancy.

facet.inspection.base

facet.inspection.shap