# -*- coding: utf-8 -*-
"""
Dispatch module. Explanation functions for conctere estimator classes
are defined in submodules.
"""
from eli5.base import Explanation
from eli5.base_utils import singledispatch
[docs]
@singledispatch
def explain_weights(estimator, **kwargs):
""" Return an explanation of estimator parameters (weights).
:func:`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
:class:`~Explanation` result. Use one of the formatting functions from
:mod:`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
:func:`eli5.show_weights` instead of :func:`eli5.explain_weights`
if you work with IPython: :func:`eli5.show_weights` allows to customize
formatting without a need to import :mod:`eli5.formatters` functions.
"""
return Explanation(
estimator=repr(estimator),
error="estimator %r is not supported" % estimator,
)
[docs]
@singledispatch
def explain_prediction(estimator, doc, **kwargs):
"""
Return an explanation of an estimator prediction.
:func:`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 :func:`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
:class:`~.Explanation` result. Use one of the formatting functions from
:mod:`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
:func:`eli5.show_prediction` instead of :func:`eli5.explain_prediction`
if you work with IPython: :func:`eli5.show_prediction` allows to
customize formatting without a need to import :mod:`eli5.formatters`
functions.
"""
return Explanation(
estimator=repr(estimator),
error="estimator %r is not supported" % estimator,
)