interpret_community.explanation.explanation module¶
Defines the explanations that are returned from explaining models.
- class interpret_community.explanation.explanation.BaseExplanation(method, model_task, model_type=None, explanation_id=None, **kwargs)¶
Bases:
abc.ABC
,interpret_community.common.chained_identity.ChainedIdentity
The common explanation returned by explainers.
- Parameters
method (str) – The explanation method used to explain the model (e.g., SHAP, LIME).
model_task (str) – The task of the original model i.e., classification or regression.
model_type (str) – The type of the original model that was explained, e.g., sklearn.linear_model.LinearRegression.
explanation_id (str) – The unique identifier for the explanation.
- data(key=None)¶
Return the data of the explanation.
- property model_task¶
Get the task of the original model, i.e., classification or regression (others possibly in the future).
- Returns
The task of the original model.
- Return type
- property model_type¶
Get the type of the original model that was explained.
- Returns
A class name or ‘function’, if that information is available.
- Return type
- property name¶
Get the name of the explanation.
- Returns
The name of the explanation.
- Return type
- abstract property selector¶
Get the local or global selector.
- Returns
The selector as a pandas dataframe of records.
- Return type
- visualize(key=None)¶
- class interpret_community.explanation.explanation.ClassesMixin(classes=None, num_classes=None, **kwargs)¶
Bases:
object
The explanation mixin for classes.
This mixin is added when you specify classes in the classification scenario for creating a global or local explanation. This is activated when you specify the classes parameter for global or local explanations.
- class interpret_community.explanation.explanation.ExpectedValuesMixin(expected_values=None, **kwargs)¶
Bases:
object
The explanation mixin for expected values.
- Parameters
expected_values (numpy.ndarray) – The expected values of the model.
- data(key=None)¶
Return the data of the explanation with expected values added.
- property expected_values¶
Get the expected values.
In the classification case where there are multiple expected values, they will be in the same order as the numeric indices that the classifier outputs.
- Returns
The expected value of the model applied to the set of initialization examples.
- Return type
- class interpret_community.explanation.explanation.FeatureImportanceExplanation(features=None, num_features=None, is_raw=False, is_engineered=False, **kwargs)¶
Bases:
interpret_community.explanation.explanation.BaseExplanation
The common feature importance explanation returned by explainers.
- property is_engineered¶
Get the engineered explanation flag.
- Returns
True if it’s an engineered explanation (specifically not raw). False if raw or unknown.
- Return type
- property is_raw¶
Get the raw explanation flag.
- Returns
True if it’s a raw explanation. False if engineered or unknown.
- Return type
- class interpret_community.explanation.explanation.GlobalExplanation(global_importance_values=None, global_importance_rank=None, ranked_global_names=None, ranked_global_values=None, **kwargs)¶
Bases:
interpret_community.explanation.explanation.FeatureImportanceExplanation
The common global explanation returned by explainers.
- Parameters
global_importance_values (numpy.ndarray) – The feature importance values in the order of the original features.
global_importance_rank (numpy.ndarray) – The feature indexes sorted by importance.
ranked_global_names (list[str] TODO) – The feature names sorted by importance.
ranked_global_values (numpy.ndarray) – The feature importance values sorted by importance.
- data(key=None)¶
Return the data of the explanation with global importance values added.
- get_feature_importance_dict(top_k=None)¶
Get a dictionary pairing ranked global names and feature importance values.
- get_ranked_global_names(top_k=None)¶
Get feature names sorted by global feature importance values, highest to lowest.
- get_ranked_global_values(top_k=None)¶
Get global feature importance sorted from highest to lowest.
- get_raw_explanation(feature_maps, raw_feature_names=None, eval_data=None)¶
Get raw explanation using input feature maps.
- Parameters
feature_maps (list[Union[numpy.ndarray, scipy.sparse.csr_matrix]]) – list of feature maps from raw to generated feature where each array entry (raw_index, generated_index) is the weight for each raw, generated feature pair. The other entries are set to zero. For a sequence of transformations [t1, t2, …, tn] generating generated features from raw features, the list of feature maps correspond to the raw to generated maps in the same order as t1, t2, etc. If the overall raw to generated feature map from t1 to tn is available, then just that feature map in a single element list can be passed.
raw_feature_names ([str]) – list of raw feature names
eval_data (numpy.ndarray or pandas.DataFrame) – Evaluation data.
- Returns
raw explanation
- Return type
- get_raw_feature_importances(feature_maps)¶
Get global raw feature importance.
- property global_importance_rank¶
Get the overall feature importance rank or indexes.
For example, if original features are [f0, f1, f2, f3] and in global importance order they are [f2, f3, f0, f1], global_importance_rank would be [2, 3, 0, 1].
- property global_importance_values¶
Get the global feature importance values.
Values will be in their original order, the same as features, unless top_k was passed into upload_model_explanation or download_model_explanation. In those cases, returns the most important k values in highest to lowest importance order.
- property selector¶
Get the global selector if this is only a global explanation otherwise local.
- Returns
The selector as a pandas dataframe of records.
- Return type
- class interpret_community.explanation.explanation.LocalExplanation(local_importance_values=None, **kwargs)¶
Bases:
interpret_community.explanation.explanation.FeatureImportanceExplanation
The common local explanation returned by explainers.
- Parameters
local_importance_values (numpy.ndarray or scipy.sparse.csr_matrix or list[scipy.sparse.csr_matrix]) – The feature importance values.
- data(key=None)¶
Return the data of the explanation with local importance values added.
- get_local_importance_rank()¶
Get local feature importance rank or indexes.
For example, if original features are [f0, f1, f2, f3] and in local importance order for the first data point they are [f2, f3, f0, f1], local_importance_rank[0] would be [2, 3, 0, 1] (or local_importance_rank[0][0] if classification).
For documentation regarding order of classes in the classification case, please see the docstring for local_importance_values.
- get_ranked_local_names(top_k=None)¶
Get feature names sorted by local feature importance values, highest to lowest.
For documentation regarding order of classes in the classification case, please see the docstring for local_importance_values.
- get_ranked_local_values(top_k=None)¶
Get local feature importance sorted from highest to lowest.
For documentation regarding order of classes in the classification case, please see the docstring for local_importance_values.
- get_raw_explanation(feature_maps, raw_feature_names=None, eval_data=None)¶
Get raw explanation using input feature maps.
- Parameters
feature_maps (list[Union[numpy.ndarray, scipy.sparse.csr_matrix]]) – list of feature maps from raw to generated feature where each array entry (raw_index, generated_index) is the weight for each raw, generated feature pair. The other entries are set to zero. For a sequence of transformations [t1, t2, …, tn] generating generated features from raw features, the list of feature maps correspond to the raw to generated maps in the same order as t1, t2, etc. If the overall raw to generated feature map from t1 to tn is available, then just that feature map in a single element list can be passed.
raw_feature_names ([str]) – list of raw feature names
eval_data (numpy.ndarray or pandas.DataFrame) – Evaluation data.
- Returns
raw explanation
- Return type
- get_raw_feature_importances(raw_to_output_maps)¶
Get local raw feature importance.
For documentation regarding order of classes in the classification case, please see the docstring for local_importance_values.
- property is_local_sparse¶
Determines whether the local importance values are sparse.
- Returns
True if the local importance values are sparse.
- Return type
- property local_importance_values¶
Get the feature importance values in original order.
- Returns
For a model with a single output such as regression, this returns a list of feature importance values for each data point. For models with vector outputs this function returns a list of such lists, one for each output. The dimension of this matrix is (# examples x # features) or (# classes x # examples x # features).
In the classification case, the order of classes is the order of the numeric indices that the classifier outputs. For example, if your target values are [2, 2, 0, 1, 2, 1, 0], where 0 is “dog”, 1 is “cat”, and 2 is “fish”, the first 2d matrix of importance values will be for “dog”, the second will be for “cat”, and the last will be for “fish”. If you choose to pass in a classes array to the explainer, the names should be passed in using this same order.
- Return type
list[list[float]] or list[list[list[float]]] or scipy.sparse.csr_matrix or list[scipy.sparse.csr_matrix]
- property num_examples¶
Get the number of examples on the explanation.
- Returns
The number of examples on the explanation.
- Return type
- property selector¶
Get the local selector.
- Returns
The selector as a pandas dataframe of records.
- Return type
- class interpret_community.explanation.explanation.PerClassMixin(per_class_values=None, per_class_rank=None, ranked_per_class_names=None, ranked_per_class_values=None, **kwargs)¶
Bases:
interpret_community.explanation.explanation.ClassesMixin
The explanation mixin for per class aggregated information.
This mixin is added for the classification scenario for global explanations. The per class importance values are group averages of local importance values across different classes.
- Parameters
per_class_values (numpy.ndarray) – The feature importance values for each class in the order of the original features.
per_class_importance_rank (numpy.ndarray) – The feature indexes for each class sorted by importance.
ranked_per_class_names (list[str]) – The feature names for each class sorted by importance.
ranked_per_class_values (numpy.ndarray) – The feature importance values sorted by importance.
- get_ranked_per_class_names(top_k=None)¶
Get feature names sorted by per class feature importance values, highest to lowest.
For documentation regarding order of classes, please see the docstring for per_class_values.
- get_ranked_per_class_values(top_k=None)¶
Get per class feature importance sorted from highest to lowest.
For documentation regarding order of classes, please see the docstring for per_class_values.
- property per_class_rank¶
Get the per class importance rank or indexes.
For example, if original features are [f0, f1, f2, f3] and in per class importance order they are [[f2, f3, f0, f1], [f0, f2, f3, f1]], per_class_rank would be [[2, 3, 0, 1], [0, 2, 3, 1]].
For documentation regarding order of classes, please see the docstring for per_class_values.
- Returns
The per class indexes that would sort per_class_values.
- Return type
- property per_class_values¶
Get the per class importance values.
Values will be in their original order, the same as features, unless top_k was passed into upload_model_explanation or download_model_explanation. In those cases, returns the most important k values in highest to lowest importance order.
The order of classes in the output is the order of the numeric indices that the classifier outputs. For example, if your target values are [2, 2, 0, 1, 2, 1, 0], where 0 is “dog”, 1 is “cat”, and 2 is “fish”, the first 2d matrix of importance values will be for “dog”, the second will be for “cat”, and the last will be for “fish”. If you choose to pass in a classes array to the explainer, the names should be passed in using this same order.
- Returns
The model level per class feature importance values in original feature order.
- Return type