Source code for evalml.model_understanding.feature_explanations

"""Human Readable Pipeline Explanations."""

import pandas as pd

import evalml
from evalml.model_family import ModelFamily
from evalml.model_understanding import calculate_permutation_importance
from evalml.utils import get_logger, infer_feature_types


[docs]def readable_explanation( pipeline, X=None, y=None, importance_method="permutation", max_features=5, min_importance_threshold=0.05, objective="auto", ): """Outputs a human-readable explanation of trained pipeline behavior. Args: pipeline (PipelineBase): The pipeline to explain. X (pd.DataFrame): If importance_method is permutation, the holdout X data to compute importance with. Ignored otherwise. y (pd.Series): The holdout y data, used to obtain the name of the target class. If importance_method is permutation, used to compute importance with. importance_method (str): The method of determining feature importance. One of ["permutation", "feature"]. Defaults to "permutation". max_features (int): The maximum number of influential features to include in an explanation. This does not affect the number of detrimental features reported. Defaults to 5. min_importance_threshold (float): The minimum percent of total importance a single feature can have to be considered important. Defaults to 0.05. objective (str, ObjectiveBase): If importance_method is permutation, the objective to compute importance with. Ignored otherwise, defaults to "auto". Raises: ValueError: if any arguments passed in are invalid or the pipeline is not fitted. """ logger = get_logger(f"{__name__}.explain") if not pipeline._is_fitted: raise ValueError( "Pipelines must be fitted in order to run feature explanations.", ) if min_importance_threshold >= 1 or min_importance_threshold < 0: raise ValueError( f"The minimum importance threshold must be a percentage value in the range [0, 1), not {min_importance_threshold}.", ) if importance_method == "permutation": if objective == "auto": objective = evalml.automl.get_default_primary_search_objective( pipeline.problem_type, ) if X is None or y is None: raise ValueError( "X and y are required parameters for explaining pipelines with permutation importance.", ) X = infer_feature_types(X) y = infer_feature_types(y) imp_df = calculate_permutation_importance(pipeline, X, y, objective) elif importance_method == "feature": objective = None imp_df = pipeline.feature_importance else: raise ValueError(f"Unknown importance method {importance_method}.") linear_importance = False if ( pipeline.estimator.model_family == ModelFamily.LINEAR_MODEL and importance_method == "feature" ): linear_importance = True ( most_important_features, somewhat_important_features, detrimental_features, ) = get_influential_features( imp_df, max_features, min_importance_threshold, linear_importance, ) target = y if y is None else y.name explanation = _fill_template( pipeline.estimator, target, objective, most_important_features, somewhat_important_features, detrimental_features, ) logger.info(explanation)
[docs]def get_influential_features( imp_df, max_features=5, min_importance_threshold=0.05, linear_importance=False, ): """Finds the most influential features as well as any detrimental features from a dataframe of feature importances. Args: imp_df (pd.DataFrame): DataFrame containing feature names and associated importances. max_features (int): The maximum number of features to include in an explanation. Defaults to 5. min_importance_threshold (float): The minimum percent of total importance a single feature can have to be considered important. Defaults to 0.05. linear_importance (bool): When True, negative feature importances are not considered detrimental. Defaults to False. Returns: (list, list, list): Lists of feature names corresponding to heavily influential, somewhat influential, and detrimental features, respectively. """ heavy_importance_threshold = max(0.2, min_importance_threshold + 0.1) # Separate negative and positive features, if situation calls if linear_importance: pos_imp_df = imp_df pos_imp_df["importance"] = abs(pos_imp_df["importance"]) neg_imp_df = pd.DataFrame({"feature": [], "importance": []}) else: neg_imp_df = imp_df[imp_df["importance"] < 0] pos_imp_df = imp_df[imp_df["importance"] >= 0] # Normalize the positive features to sum to 1 pos_imp_df["importance"] = pos_imp_df["importance"] / sum(pos_imp_df["importance"]) num_feats = min(len(pos_imp_df), max_features) imp_features = pos_imp_df[:num_feats] heavy_importance = imp_features[ imp_features["importance"] >= heavy_importance_threshold ] somewhat_importance = imp_features[ imp_features["importance"] < heavy_importance_threshold ] return ( list(heavy_importance["feature"]), list( somewhat_importance[ somewhat_importance["importance"] >= min_importance_threshold ]["feature"], ), list(neg_imp_df["feature"]), )
def _fill_template( estimator, target, objective, most_important, somewhat_important, detrimental_feats, ): # Get the objective to a printable string if objective is not None: if isinstance(objective, evalml.objectives.ObjectiveBase): objective = objective.name if objective != "R2": # Remove any title case if necessary objective = objective.lower() # Beginning of description objective_str = f" as measured by {objective}" if objective is not None else "" beginning = ( f"{estimator}: The output{objective_str}" if target is None else f"{estimator}: The prediction of {target}{objective_str}" ) def enumerate_features(feature_list): text = "" if len(feature_list) == 2 else "," for i in range(1, len(feature_list)): if i == len(feature_list) - 1: text = text + f" and {feature_list[i]}" else: text = text + f" {feature_list[i]}," return text # Heavily influential description heavy = "" if len(most_important) > 0: heavy = f" is heavily influenced by {most_important[0]}" if len(most_important) > 1: heavy = heavy + enumerate_features(most_important) if len(somewhat_important) > 0: heavy = heavy + ", and" # Somewhat influential description somewhat = "" if len(somewhat_important) > 0: somewhat = f" is somewhat influenced by {somewhat_important[0]}" if len(somewhat_important) > 1: somewhat = somewhat + enumerate_features(somewhat_important) # Neither! neither = "." if not (len(heavy) or len(somewhat)): neither = " is not strongly influenced by any single feature. Lower the `min_importance_threshold` to see more." # Detrimental Description detrimental = "" if len(detrimental_feats) > 0: if len(detrimental_feats) == 1: detrimental = f"\nThe feature {detrimental_feats[0]}" tag = "this feature." else: detrimental = f"\nThe features {detrimental_feats[0]}" detrimental = detrimental + enumerate_features(detrimental_feats) tag = "these features." detrimental = ( detrimental + " detracted from model performance. We suggest removing " + tag ) return beginning + heavy + somewhat + neither + detrimental