************************** :py:mod:`wildboar.explain` ************************** .. py:module:: wildboar.explain .. autoapi-nested-parse:: Explanation methods for classifiers and regressors. .. !! processed by numpydoc !! Subpackages =========== .. toctree:: :titlesonly: :maxdepth: 3 counterfactual/index.rst Package Contents ---------------- Classes ------- .. autoapisummary:: wildboar.explain.AmplitudeImportance wildboar.explain.FrequencyImportance wildboar.explain.IntervalImportance wildboar.explain.ShapeletImportance Functions --------- .. autoapisummary:: wildboar.explain.plot_importances .. py:class:: AmplitudeImportance(scoring=None, n_intervals='sqrt', window=None, binning='normal', n_bins=4, n_repeat=1, random_state=None) Compute the importance of equi-probable amplitude intervals. The implementation uses :class:`transform.SAX` to discretize the time series and then for each bin permute the samples along that bin. .. !! processed by numpydoc !! .. py:method:: fit_explain(estimator, x=None, y=None, **kwargs) Fit and return the explanation. :Parameters: **estimator** : Estimator The estimator to explain. **x** : time-series, optional The input time series. **y** : array-like of shape (n_samples, ), optional The labels. **\*\*kwargs** Optional extra arguments. :Returns: ndarray The explanation. .. !! processed by numpydoc !! .. py:method:: get_metadata_routing() Get metadata routing of this object. Please check :ref:`User Guide ` on how the routing mechanism works. :Returns: **routing** : MetadataRequest A :class:`~sklearn.utils.metadata_routing.MetadataRequest` encapsulating routing information. .. !! processed by numpydoc !! .. py:method:: get_params(deep=True) Get parameters for this estimator. :Parameters: **deep** : bool, default=True If True, will return the parameters for this estimator and contained subobjects that are estimators. :Returns: **params** : dict Parameter names mapped to their values. .. !! processed by numpydoc !! .. py:method:: plot(x=None, y=None, *, ax=None, n_samples=100, scoring=None, preprocess=True, k=None, show_bins=False, show_grid=True) Plot the importances. If x is given, the importances are plotted over the samples optionally labeling each sample using the supplied labels. If x is not give, the importances are plotted as one or more boxplots. :Parameters: **x** : array-like of shape (n_samples, n_timesteps), optional The samples. **y** : array-like of shape (n_samples, ), optional The labels. **ax** : Axes, optional Axes to plot. If ax is set, x is None and scoring is None, the number of axes must be the same as the number of scorers. **n_samples** : int or float, optional The number of samples to plot, set to `None` to plot all. **scoring** : str, optional The scoring to plot if multiple scorers were used when fitting. **preprocess** : bool, optional Preprocess the time series to align with the bins, ignored if x is not None. **k** : int or float, optional The number of top bins to plot, ignored if x is not None. - if int, the specified number of bins are shown - if float, a fraction of the number of bins are shown. **show_bins** : bool, optional Annotate the plot with the index of the bin, ignored if x is not None. **show_grid** : bool, optional Annotate the plot with the bin thresholds, ignored if x is not None. :Returns: **ax** : Axis The axis. **mappable** : ScalarMappable, optional Return the mappable used to plot the colorbar. Only returned if ax is not None and x is not None. .. !! processed by numpydoc !! .. py:method:: set_params(**params) Set the parameters of this estimator. The method works on simple estimators as well as on nested objects (such as :class:`~sklearn.pipeline.Pipeline`). The latter have parameters of the form ``__`` so that it's possible to update each component of a nested object. :Parameters: **\*\*params** : dict Estimator parameters. :Returns: **self** : estimator instance Estimator instance. .. !! processed by numpydoc !! .. py:class:: FrequencyImportance(window=1, scoring=None, n_repeat=1, random_state=None) Mixin class for all explainers in wildboar. .. !! processed by numpydoc !! .. py:method:: fit_explain(estimator, x=None, y=None, **kwargs) Fit and return the explanation. :Parameters: **estimator** : Estimator The estimator to explain. **x** : time-series, optional The input time series. **y** : array-like of shape (n_samples, ), optional The labels. **\*\*kwargs** Optional extra arguments. :Returns: ndarray The explanation. .. !! processed by numpydoc !! .. py:method:: get_metadata_routing() Get metadata routing of this object. Please check :ref:`User Guide ` on how the routing mechanism works. :Returns: **routing** : MetadataRequest A :class:`~sklearn.utils.metadata_routing.MetadataRequest` encapsulating routing information. .. !! processed by numpydoc !! .. py:method:: get_params(deep=True) Get parameters for this estimator. :Parameters: **deep** : bool, default=True If True, will return the parameters for this estimator and contained subobjects that are estimators. :Returns: **params** : dict Parameter names mapped to their values. .. !! processed by numpydoc !! .. py:method:: plot(x=None, y=None, ax=None) Plot the explanation. :Returns: **ax** : Axes The axes object .. !! processed by numpydoc !! .. py:method:: set_params(**params) Set the parameters of this estimator. The method works on simple estimators as well as on nested objects (such as :class:`~sklearn.pipeline.Pipeline`). The latter have parameters of the form ``__`` so that it's possible to update each component of a nested object. :Parameters: **\*\*params** : dict Estimator parameters. :Returns: **self** : estimator instance Estimator instance. .. !! processed by numpydoc !! .. py:class:: IntervalImportance(*, scoring=None, n_repeat=5, n_intervals='sqrt', window=None, random_state=None) Interval importance for time series. :Parameters: **scoring** : str, list, dict or callable, optional The scoring function. By default the estimators score function is used. **n_repeat** : int, optional The number of repeated permutations. **n_intervals** : str, optional The number of intervals. - if "sqrt", the number of intervals is the square root of n_timestep. - if "log2", the number of intervals is the log2 of n_timestep. - if int, exact number of intervals. **window** : int, optional The window size. If specicied, n_intervals is ignored and the number of intervals is computed such that each interval is (at least) of size window. **random_state** : int or RandomState - If `int`, `random_state` is the seed used by the random number generator - If `RandomState` instance, `random_state` is the random number generator - If `None`, the random number generator is the `RandomState` instance used by `np.random`. :Attributes: **importances_** : dict or Importance The importance scores for each interval. If dict, one value per scoring function. **components_** : ndarray of shape (n_intervals, 2) The interval start and end positions. .. !! processed by numpydoc !! .. py:method:: fit_explain(estimator, x=None, y=None, **kwargs) Fit and return the explanation. :Parameters: **estimator** : Estimator The estimator to explain. **x** : time-series, optional The input time series. **y** : array-like of shape (n_samples, ), optional The labels. **\*\*kwargs** Optional extra arguments. :Returns: ndarray The explanation. .. !! processed by numpydoc !! .. py:method:: get_metadata_routing() Get metadata routing of this object. Please check :ref:`User Guide ` on how the routing mechanism works. :Returns: **routing** : MetadataRequest A :class:`~sklearn.utils.metadata_routing.MetadataRequest` encapsulating routing information. .. !! processed by numpydoc !! .. py:method:: get_params(deep=True) Get parameters for this estimator. :Parameters: **deep** : bool, default=True If True, will return the parameters for this estimator and contained subobjects that are estimators. :Returns: **params** : dict Parameter names mapped to their values. .. !! processed by numpydoc !! .. py:method:: plot(x=None, y=None, *, ax=None, scoring=None, k=None, n_samples=100, show_grid=True) Plot the explanation. :Returns: **ax** : Axes The axes object .. !! processed by numpydoc !! .. py:method:: set_params(**params) Set the parameters of this estimator. The method works on simple estimators as well as on nested objects (such as :class:`~sklearn.pipeline.Pipeline`). The latter have parameters of the form ``__`` so that it's possible to update each component of a nested object. :Parameters: **\*\*params** : dict Estimator parameters. :Returns: **self** : estimator instance Estimator instance. .. !! processed by numpydoc !! .. py:class:: ShapeletImportance(scoring=None, n_repeat=1, n_shapelets=10, min_shapelet_size=0.0, max_shapelet_size=1.0, metric='euclidean', metric_params=None, random_state=None) Compute the importance of shapelets. The importance is given by permuting time series sections with the minimum distance to shapelets. :Parameters: **scoring** : str, list, dict or callable, optional The scoring function. By default the estimators score function is used. **n_repeat** : int, optional The number of repeated permutations. **n_shapelets** : int, optional The number of shapelets to sample for the explanation. **min_shapelet_size** : float, optional The minimum size of shapelets used for explanation. **max_shapelet_size** : float, optional The maximum size of shapelets used for explanation. **metric** : str, optional The metric. **metric_params** : str, optional The metric parameters. **random_state** : int or RandomState, optional Controls the random resampling of the original dataset. - If `int`, `random_state` is the seed used by the random number generator. - If :class:`numpy.random.RandomState` instance, `random_state` is the random number generator. - If `None`, the random number generator is the :class:`numpy.random.RandomState` instance used by :func:`numpy.random`. :Attributes: **components** : ndarray The shapelets .. !! processed by numpydoc !! .. py:method:: fit_explain(estimator, x=None, y=None, **kwargs) Fit and return the explanation. :Parameters: **estimator** : Estimator The estimator to explain. **x** : time-series, optional The input time series. **y** : array-like of shape (n_samples, ), optional The labels. **\*\*kwargs** Optional extra arguments. :Returns: ndarray The explanation. .. !! processed by numpydoc !! .. py:method:: get_metadata_routing() Get metadata routing of this object. Please check :ref:`User Guide ` on how the routing mechanism works. :Returns: **routing** : MetadataRequest A :class:`~sklearn.utils.metadata_routing.MetadataRequest` encapsulating routing information. .. !! processed by numpydoc !! .. py:method:: get_params(deep=True) Get parameters for this estimator. :Parameters: **deep** : bool, default=True If True, will return the parameters for this estimator and contained subobjects that are estimators. :Returns: **params** : dict Parameter names mapped to their values. .. !! processed by numpydoc !! .. py:method:: plot(X=None, y=None, k=None, scoring=None, kernel_scale=0.25, ax=None) Plot the explanation. :Returns: **ax** : Axes The axes object .. !! processed by numpydoc !! .. py:method:: set_params(**params) Set the parameters of this estimator. The method works on simple estimators as well as on nested objects (such as :class:`~sklearn.pipeline.Pipeline`). The latter have parameters of the form ``__`` so that it's possible to update each component of a nested object. :Parameters: **\*\*params** : dict Estimator parameters. :Returns: **self** : estimator instance Estimator instance. .. !! processed by numpydoc !! .. py:function:: plot_importances(importances, ax=None, labels=None) Plot the importances as a boxplot. :Parameters: **importances** : Importance or dict The importances. **ax** : Axes, optional The axes to plot. If importances is dict, ax must contain at least len(importances) Axes objects. **labels** : array-like, optional The labels for the importances. :Returns: Axes The plotted Axes. .. !! processed by numpydoc !!