ELI5 top-level API

The following functions are exposed to a top level, e.g. eli5.explain_weights.

explain_weights(estimator, **kwargs)

Return an explanation of estimator parameters (weights).

explain_weights() is not doing any work itself, it dispatches to a concrete implementation based on estimator type.

Parameters:

• estimator (object) – Estimator instance. This argument must be positional.

• top (int or (int, int) tuple, optional) – Number of features to show. When top is int, top features with a highest absolute values are shown. When it is (pos, neg) tuple, no more than pos positive features and no more than neg negative features is shown. None value means no limit.

  This argument may be supported or not, depending on estimator type.

• target_names (list[str] or {‘old_name’: ‘new_name’} dict, optional) – Names of targets or classes. This argument can be used to provide human-readable class/target names for estimators which don’t expose clss names themselves. It can be also used to rename estimator-provided classes before displaying them.

  This argument may be supported or not, depending on estimator type.

• targets (list, optional) – Order of class/target names to show. This argument can be also used to show information only for a subset of classes. It should be a list of class / target names which match either names provided by an estimator or names defined in target_names parameter.

  This argument may be supported or not, depending on estimator type.

• feature_names (list, optional) – A list of feature names. It allows to specify feature names when they are not provided by an estimator object.

  This argument may be supported or not, depending on estimator type.

• feature_re (str, optional) – Only feature names which match feature_re regex are returned (more precisely, re.search(feature_re, x) is checked).

• feature_filter (Callable[[str], bool], optional) – Only feature names for which feature_filter function returns True are returned.

• **kwargs (dict) – Keyword arguments. All keyword arguments are passed to concrete explain_weights… implementations.

Returns:

Explanation – Explanation result. Use one of the formatting functions from eli5.formatters to print it in a human-readable form.

Explanation instances have repr which works well with IPython notebook, but it can be a better idea to use eli5.show_weights() instead of eli5.explain_weights() if you work with IPython: eli5.show_weights() allows to customize formatting without a need to import eli5.formatters functions.

explain_prediction(estimator, doc, **kwargs)

Return an explanation of an estimator prediction.

explain_prediction() is not doing any work itself, it dispatches to a concrete implementation based on estimator type.

Parameters:

• estimator (object) – Estimator instance. This argument must be positional.

• doc (object) – Example to run estimator on. Estimator makes a prediction for this example, and explain_prediction() tries to show information about this prediction. Pass a single element, not a one-element array: if you fitted your estimator on X, that would be X[i] for most containers, and X.iloc[i] for pandas.DataFrame.

• top (int or (int, int) tuple, optional) – Number of features to show. When top is int, top features with a highest absolute values are shown. When it is (pos, neg) tuple, no more than pos positive features and no more than neg negative features is shown. None value means no limit (default).

  This argument may be supported or not, depending on estimator type.

• top_targets (int, optional) – Number of targets to show. When top_targets is provided, only specified number of targets with highest scores are shown. Negative value means targets with lowest scores are shown. Must not be given with targets argument. None value means no limit: all targets are shown (default).

  This argument may be supported or not, depending on estimator type.

• target_names (list[str] or {‘old_name’: ‘new_name’} dict, optional) – Names of targets or classes. This argument can be used to provide human-readable class/target names for estimators which don’t expose class names themselves. It can be also used to rename estimator-provided classes before displaying them.

  This argument may be supported or not, depending on estimator type.

• targets (list, optional) – Order of class/target names to show. This argument can be also used to show information only for a subset of classes. It should be a list of class / target names which match either names provided by an estimator or names defined in target_names parameter. Must not be given with top_targets argument.

  In case of binary classification you can use this argument to set the class which probability or score should be displayed, with an appropriate explanation. By default a result for predicted class is shown. For example, you can use targets=[True] to always show result for a positive class, even if the predicted label is False.

  This argument may be supported or not, depending on estimator type.

• feature_names (list, optional) – A list of feature names. It allows to specify feature names when they are not provided by an estimator object.

  This argument may be supported or not, depending on estimator type.

• feature_re (str, optional) – Only feature names which match feature_re regex are returned (more precisely, re.search(feature_re, x) is checked).

• feature_filter (Callable[[str, float], bool], optional) – Only feature names for which feature_filter function returns True are returned. It must accept feature name and feature value. Missing features always have a NaN value.

• **kwargs (dict) – Keyword arguments. All keyword arguments are passed to concrete explain_prediction… implementations.

Returns:

Explanation – Explanation result. Use one of the formatting functions from eli5.formatters to print it in a human-readable form.

Explanation instances have repr which works well with IPython notebook, but it can be a better idea to use eli5.show_prediction() instead of eli5.explain_prediction() if you work with IPython: eli5.show_prediction() allows to customize formatting without a need to import eli5.formatters functions.

show_weights(estimator, **kwargs)

Return an explanation of estimator parameters (weights) as an IPython.display.HTML object. Use this function to show classifier weights in IPython.

show_weights() accepts all eli5.explain_weights() arguments and all eli5.formatters.html.format_as_html() keyword arguments, so it is possible to get explanation and customize formatting in a single call.

Parameters:

• estimator (object) – Estimator instance. This argument must be positional.

• top (int or (int, int) tuple, optional) – Number of features to show. When top is int, top features with a highest absolute values are shown. When it is (pos, neg) tuple, no more than pos positive features and no more than neg negative features is shown. None value means no limit.

  This argument may be supported or not, depending on estimator type.

• target_names (list[str] or {‘old_name’: ‘new_name’} dict, optional) – Names of targets or classes. This argument can be used to provide human-readable class/target names for estimators which don’t expose clss names themselves. It can be also used to rename estimator-provided classes before displaying them.

  This argument may be supported or not, depending on estimator type.

• targets (list, optional) – Order of class/target names to show. This argument can be also used to show information only for a subset of classes. It should be a list of class / target names which match either names provided by an estimator or names defined in target_names parameter.

  This argument may be supported or not, depending on estimator type.

• feature_names (list, optional) – A list of feature names. It allows to specify feature names when they are not provided by an estimator object.

  This argument may be supported or not, depending on estimator type.

• feature_re (str, optional) – Only feature names which match feature_re regex are shown (more precisely, re.search(feature_re, x) is checked).

• feature_filter (Callable[[str], bool], optional) – Only feature names for which feature_filter function returns True are shown.

• show (List[str], optional) – List of sections to show. Allowed values:

  • ‘targets’ - per-target feature weights;
  • ‘transition_features’ - transition features of a CRF model;
  • ‘feature_importances’ - feature importances of a decision tree or an ensemble-based estimator;
  • ‘decision_tree’ - decision tree in a graphical form;
  • ‘method’ - a string with explanation method;
  • ‘description’ - description of explanation method and its caveats.

  eli5.formatters.fields provides constants that cover common cases: INFO (method and description), WEIGHTS (all the rest), and ALL (all).

• horizontal_layout (bool) – When True, feature weight tables are printed horizontally (left to right); when False, feature weight tables are printed vertically (top to down). Default is True.

• highlight_spaces (bool or None, optional) – Whether to highlight spaces in feature names. This is useful if you work with text and have ngram features which may include spaces at left or right. Default is None, meaning that the value used is set automatically based on vectorizer and feature values.

• include_styles (bool) – Most styles are inline, but some are included separately in <style> tag; you can omit them by passing include_styles=False. Default is True.

• **kwargs (dict) – Keyword arguments. All keyword arguments are passed to concrete explain_weights… implementations.

Returns:

IPython.display.HTML – The result is printed in IPython notebook as an HTML widget. If you need to display several explanations as an output of a single cell, or if you want to display it from a function then use IPython.display.display:

from IPython.display import display
display(eli5.show_weights(clf1))
display(eli5.show_weights(clf2))

show_prediction(estimator, doc, **kwargs)

Return an explanation of estimator prediction as an IPython.display.HTML object. Use this function to show information about classifier prediction in IPython.

show_prediction() accepts all eli5.explain_prediction() arguments and all eli5.formatters.html.format_as_html() keyword arguments, so it is possible to get explanation and customize formatting in a single call.

If explain_prediction() returns an base.Explanation object with the image attribute not set to None, i.e. if explaining image based models, then formatting is dispatched to an image display implementation, and image explanations are shown in an IPython cell. Extra keyword arguments are passed to eli5.format_as_image().

Note that this image display implementation requires matplotlib and Pillow as extra dependencies. If the dependencies are missing, no formatting is done and the original base.Explanation object is returned.

Parameters:

• estimator (object) – Estimator instance. This argument must be positional.

• doc (object) – Example to run estimator on. Estimator makes a prediction for this example, and show_prediction() tries to show information about this prediction. Pass a single element, not a one-element array: if you fitted your estimator on X, that would be X[i] for most containers, and X.iloc[i] for pandas.DataFrame.

• top (int or (int, int) tuple, optional) – Number of features to show. When top is int, top features with a highest absolute values are shown. When it is (pos, neg) tuple, no more than pos positive features and no more than neg negative features is shown. None value means no limit (default).

  This argument may be supported or not, depending on estimator type.

• top_targets (int, optional) – Number of targets to show. When top_targets is provided, only specified number of targets with highest scores are shown. Negative value means targets with lowest scores are shown. Must not be given with targets argument. None value means no limit: all targets are shown (default).

  This argument may be supported or not, depending on estimator type.

• target_names (list[str] or {‘old_name’: ‘new_name’} dict, optional) – Names of targets or classes. This argument can be used to provide human-readable class/target names for estimators which don’t expose clss names themselves. It can be also used to rename estimator-provided classes before displaying them.

  This argument may be supported or not, depending on estimator type.

• targets (list, optional) – Order of class/target names to show. This argument can be also used to show information only for a subset of classes. It should be a list of class / target names which match either names provided by an estimator or names defined in target_names parameter.

  In case of binary classification you can use this argument to set the class which probability or score should be displayed, with an appropriate explanation. By default a result for predicted class is shown. For example, you can use targets=[True] to always show result for a positive class, even if the predicted label is False.

  This argument may be supported or not, depending on estimator type.

• feature_names (list, optional) – A list of feature names. It allows to specify feature names when they are not provided by an estimator object.

  This argument may be supported or not, depending on estimator type.

• feature_re (str, optional) – Only feature names which match feature_re regex are shown (more precisely, re.search(feature_re, x) is checked).

• feature_filter (Callable[[str, float], bool], optional) – Only feature names for which feature_filter function returns True are shown. It must accept feature name and feature value. Missing features always have a NaN value.

• show (List[str], optional) – List of sections to show. Allowed values:

  • ‘targets’ - per-target feature weights;
  • ‘transition_features’ - transition features of a CRF model;
  • ‘feature_importances’ - feature importances of a decision tree or an ensemble-based estimator;
  • ‘decision_tree’ - decision tree in a graphical form;
  • ‘method’ - a string with explanation method;
  • ‘description’ - description of explanation method and its caveats.

  eli5.formatters.fields provides constants that cover common cases: INFO (method and description), WEIGHTS (all the rest), and ALL (all).

• horizontal_layout (bool) – When True, feature weight tables are printed horizontally (left to right); when False, feature weight tables are printed vertically (top to down). Default is True.

• highlight_spaces (bool or None, optional) – Whether to highlight spaces in feature names. This is useful if you work with text and have ngram features which may include spaces at left or right. Default is None, meaning that the value used is set automatically based on vectorizer and feature values.

• include_styles (bool) – Most styles are inline, but some are included separately in <style> tag; you can omit them by passing include_styles=False. Default is True.

• force_weights (bool) – When True, a table with feature weights is displayed even if all features are already highlighted in text. Default is False.

• preserve_density (bool or None) – This argument currently only makes sense when used with text data and vectorizers from scikit-learn.

  If preserve_density is True, then color for longer fragments will be less intensive than for shorter fragments, so that “sum” of intensities will correspond to feature weight.

  If preserve_density is None, then it’s value is chosen depending on analyzer kind: it is preserved for “char” and “char_wb” analyzers, and not preserved for “word” analyzers.

  Default is None.

• show_feature_values (bool) – When True, feature values are shown along with feature contributions. Default is False.

• **kwargs (dict) – Keyword arguments. All keyword arguments are passed to concrete explain_prediction… implementations.

Returns:

• IPython.display.HTML – The result is printed in IPython notebook as an HTML widget. If you need to display several explanations as an output of a single cell, or if you want to display it from a function then use IPython.display.display:

  from IPython.display import display
  display(eli5.show_weights(clf1))
  display(eli5.show_weights(clf2))
  

• PIL.Image.Image – Image with a heatmap overlay, if explaining image based models. The image is shown in an IPython notebook cell if it is the last thing returned. To display the image in a loop, function, or other case, use IPython.display.display:

  from IPython.display import display
  for cls_idx in [0, 432]:
      display(eli5.show_prediction(clf, doc, targets=[cls_idx]))
  

transform_feature_names(transformer, in_names=None)

Get feature names for transformer output as a function of input names.

Used by explain_weights() when applied to a scikit-learn Pipeline, this singledispatch should be registered with custom name transformations for each class of transformer.

If there is no singledispatch handler registered for a transformer class, transformer.get_feature_names() method is called; if there is no such method then feature names are not supported and this function raises an exception.

Parameters:

• transformer (scikit-learn-compatible transformer)
• in_names (list of str, optional) – Names for features input to transformer.transform(). If not provided, the implementation may generate default feature names if the number of input features is known.

Returns:

feature_names (list of str)

explain_weights_df(estimator, **kwargs)

Explain weights and export them to pandas.DataFrame. All keyword arguments are passed to eli5.explain_weights(). Weights of all features are exported by default.

explain_weights_dfs(estimator, **kwargs)

Explain weights and export them to a dict with pandas.DataFrame values (as eli5.formatters.as_dataframe.format_as_dataframes() does). All keyword arguments are passed to eli5.explain_weights(). Weights of all features are exported by default.

explain_prediction_df(estimator, doc, **kwargs)

Explain prediction and export explanation to pandas.DataFrame All keyword arguments are passed to eli5.explain_prediction(). Weights of all features are exported by default.

explain_prediction_dfs(estimator, doc, **kwargs)

Explain prediction and export explanation to a dict with pandas.DataFrame values (as eli5.formatters.as_dataframe.format_as_dataframes() does). All keyword arguments are passed to eli5.explain_prediction(). Weights of all features are exported by default.

format_as_text(expl, show=('method', 'description', 'transition_features', 'targets', 'feature_importances', 'decision_tree'), highlight_spaces=None, show_feature_values=False)

Format explanation as text.

Parameters:

• expl (eli5.base.Explanation) – Explanation returned by eli5.explain_weights or eli5.explain_prediction functions.

• highlight_spaces (bool or None, optional) – Whether to highlight spaces in feature names. This is useful if you work with text and have ngram features which may include spaces at left or right. Default is None, meaning that the value used is set automatically based on vectorizer and feature values.

• show_feature_values (bool) – When True, feature values are shown along with feature contributions. Default is False.

• show (List[str], optional) – List of sections to show. Allowed values:

  • ‘targets’ - per-target feature weights;
  • ‘transition_features’ - transition features of a CRF model;
  • ‘feature_importances’ - feature importances of a decision tree or an ensemble-based estimator;
  • ‘decision_tree’ - decision tree in a graphical form;
  • ‘method’ - a string with explanation method;
  • ‘description’ - description of explanation method and its caveats.

  eli5.formatters.fields provides constants that cover common cases: INFO (method and description), WEIGHTS (all the rest), and ALL (all).

format_as_html(explanation, include_styles=True, force_weights=True, show=('method', 'description', 'transition_features', 'targets', 'feature_importances', 'decision_tree'), preserve_density=None, highlight_spaces=None, horizontal_layout=True, show_feature_values=False)

Format explanation as html. Most styles are inline, but some are included separately in <style> tag, you can omit them by passing include_styles=False and call format_html_styles to render them separately (or just omit them). With force_weights=False, weights will not be displayed in a table for predictions where it is possible to show feature weights highlighted in the document. If highlight_spaces is None (default), spaces will be highlighted in feature names only if there are any spaces at the start or at the end of the feature. Setting it to True forces space highlighting, and setting it to False turns it off. If horizontal_layout is True (default), multiclass classifier weights are laid out horizontally. If show_feature_values is True, feature values are shown if present. Default is False.

format_as_dataframe(explanation)

Export an explanation to a single pandas.DataFrame. In case several dataframes could be exported by eli5.formatters.as_dataframe.format_as_dataframes(), a warning is raised. If no dataframe can be exported, None is returned. This function also accepts some components of the explanation as arguments: feature importances, targets, transition features. Note that eli5.explain_weights() limits number of features by default. If you need all features, pass top=None to eli5.explain_weights(), or use explain_weights_df().

format_as_dataframes(explanation)

Export an explanation to a dictionary with pandas.DataFrame values and string keys that correspond to explanation attributes. Use this method if several dataframes can be exported from a single explanation (e.g. for CRF explanation with has both feature weights and transition matrix). Note that eli5.explain_weights() limits number of features by default. If you need all features, pass top=None to eli5.explain_weights(), or use explain_weights_dfs().

format_as_dict(explanation)

Return a dictionary representing the explanation that can be JSON-encoded. It accepts parts of explanation (for example feature weights) as well.

format_as_image(expl, resampling_filter=Image.LANCZOS, colormap=matplotlib.cm.viridis, alpha_limit=0.65)

Format a eli5.base.Explanation object as an image.

Note that this formatter requires matplotlib and Pillow optional dependencies.

Parameters:

• expl (Explanation) –

  eli5.base.Explanation object to be formatted. It must have an image attribute with a Pillow image that will be overlaid. It must have a targets attribute, a list of eli5.base.TargetExplanation instances that contain the attribute heatmap, a rank 2 numpy array with float values in the interval [0, 1]. Currently targets must be length 1 (only one target is supported).

  raises TypeError:  if heatmap is not a numpy array. raises ValueError:  if heatmap does not contain values as floats in the interval [0, 1]. raises TypeError:  if image is not a Pillow image.
• resampling_filter (int, optional) –

  Interpolation ID or Pillow filter to use when resizing the image.

  Example filters from PIL.Image

  • NEAREST
  • BOX
  • BILINEAR
  • HAMMING
  • BICUBIC
  • LANCZOS

  See also https://pillow.readthedocs.io/en/stable/handbook/concepts.html#filters.

  Note that these attributes are integer values.

  Default is PIL.Image.LANCZOS.

• colormap (callable, optional) –

  Colormap scheme to be applied when converting the heatmap from grayscale to RGB. Either a colormap from matplotlib.cm, or a callable that takes a rank 2 array and returns the colored heatmap as a [0, 1] RGBA numpy array.

  Example colormaps from matplotlib.cm

  • viridis
  • jet
  • binary

  See also https://matplotlib.org/gallery/color/colormap_reference.html.

  Default is matplotlib.cm.viridis (green/blue to yellow).

• alpha_limit (float or int, optional) –

  Maximum alpha (transparency / opacity) value allowed for the alpha channel pixels in the RGBA heatmap image.

  Between 0.0 and 1.0.

  Useful when laying the heatmap over the original image, so that the image can be seen over the heatmap.

  Default is 0.65.

  raises ValueError:  if alpha_limit is outside the [0, 1] interval. raises TypeError:  if alpha_limit is not float, int, or None.

Returns:

overlay (PIL.Image.Image) – PIL image instance of the heatmap blended over the image.